Local Server Options

-A path | local-ca = path

Require clients to authenticate using a TLS client certificate either contained in or signed by a certificate in the file loaded from path. The file is reloaded when the SIGUSR1 signal is received. See Generating Client Certificates. If local-pass is also set, clients may instead authenticate with a server password.

-C path | local-cert = path

Load TLS certificate from path. The file is reloaded when the SIGUSR1 signal is received. The default path is host.pem, where host is set by local-host.

-H host | local-host = host

Bind to host. The default host is localhost.

-K path | local-priv = path

Load TLS private key from path. The file is reloaded when the SIGUSR1 signal is received. The default path is host.key, where host is set by local-host.

-L | palaver

Advertise the palaverapp.com IRCv3 vendor-specific capability to clients. This option only enables the capability; push notifications must be provided by the pounce-palaver(1) special-purpose client.

-P port | local-port = port

Bind to port. The default port is 6697.

-T | no-sts

Do not advertise a strict transport security (STS) policy to clients.

-U path | local-path = path

Bind to a UNIX-domain socket at path. Clients are only accepted as dispatched by calico(1). If path is a directory, the host set by local-host is appended to it. This option takes precedence over local-host and local-port.

-W pass | local-pass = pass

Require the server password pass for clients to connect. The pass string must be hashed using -x. If local-ca is also set, clients may instead authenticate using a TLS client certificate.

-f path | save = path

Save and load the contents of the buffer from path in $XDG_DATA_DIRS/pounce, usually ~/.local/share/pounce, or an absolute or relative path if path starts with ‘/’, ‘./’ or ‘../’. The file is truncated after loading.

-s size | size = size

Set the number of messages contained in the buffer to size. This sets the maximum number of recent messages which can be relayed to a reconnecting client. The size must be a power of two. The default size is 4096.

Remote Server Options

-N | no-names

Do not request ‘NAMES’ for each channel when a client connects. This avoids already connected clients receiving unsolicited responses but prevents new clients from populating user lists.

-Q ms | queue-interval = ms

Set the server send queue interval in milliseconds. The queue is used to send automated messages from pounce to the server. Messages from clients are sent to the server directly. The default interval is 200 milliseconds.

-R caps | blind-req = caps

Blindly request the IRCv3 capabilities caps, which must be supported by pounce. This can be used to enable hidden capabilities, such as userhost-in-names on some networks.

-S host | bind = host

Bind to source address host when connecting to the server.

-a user:pass | sasl-plain = user:pass

Authenticate as user with pass using SASL PLAIN. Since this method requires the account password in plaintext, it is recommended to use CertFP instead with sasl-external.

-c path | client-cert = path

Load the TLS client certificate from path. If the private key is in a separate file, it is loaded with client-priv. With sasl-external, authenticate using SASL EXTERNAL. Certificates can be generated with -g.

-e | sasl-external

Authenticate using SASL EXTERNAL, also known as CertFP. The TLS client certificate is loaded with client-cert. See Configuring CertFP.

-h host | host = host

Connect to host.

-j channels [keys] | join = channels [keys]

Join the comma-separated list of channels with the optional comma-separated list of channel keys.

-k path | client-priv = path

Load the TLS client private key from path.

-m mode | mode = mode

Set the user mode.

-n nick | nick = nick

Set nickname to nick. The default nickname is the user's name.

-p port | port = port

Connect to port. The default port is 6697.

-q mesg | quit = mesg

Quit with message mesg when shutting down.

-r real | real = real

Set realname to real. The default realname is the same as the nickname.

-t path | trust = path

Trust the certificate loaded from path. Server name verification is disabled. See Connecting to Servers with Self-signed Certificates.

-u user | user = user

Set username to user. The default username is the same as the nickname.

-w pass | pass = pass

Log in with the server password pass.

-y mesg | away = mesg

Set away status to mesg when no clients are connected and no other away status has been set.

Other Options

-g path

Generate a TLS client certificate using openssl(1) and write it to path. The certificate is signed by the certificate authority if -A is set, otherwise it is self-signed.

-o

Print the server certificate chain to standard output in PEM format and exit.

-v | verbose

Log IRC messages to standard output:

<<

from pounce to the server

>>

from the server to pounce

->

from clients to pounce

<-

from pounce to clients

-x

Prompt for a password and output a hash for use with local-pass.

Client Configuration

Clients must register with unique usernames (not nicknames), for example the name of the client software or location from which it is connecting. New clients with the same username are assumed to be reconnections and will cause previous connections to stop receiving messages. The nickname and real name sent by clients are ignored.

Clients which request the causal.agency/passive capability or with usernames beginning with hyphen ‘-’ are considered passive and do not affect automatic away status.

Pass-through of the following IRCv3 capabilities is supported: account-notify, account-tag, away-notify, batch, cap-notify, chghost, echo-message, extended-join, invite-notify, labeled-response, message-tags, multi-prefix, server-time, setname, userhost-in-names.

Private messages and notices sent to the user's own nickname are relayed only to other clients, not to the server.

Generating Client Certificates

1. Generate self-signed client certificates and private keys:

   $ pounce -g client1.pem
   $ pounce -g client2.pem
       

2. Concatenate the certificate public keys into a CA file:

   $ openssl x509 -subject -in client1.pem \
   	>> ~/.config/pounce/auth.pem
   $ openssl x509 -subject -in client2.pem \
   	>> ~/.config/pounce/auth.pem
       

3. Configure pounce to verify client certificates against the CA file:

   local-ca = auth.pem
   # or: $ pounce -A auth.pem
       

Alternatively, client certificates can be signed by a generated certificate authority:

1. Generate a self-signed certificate authority:

   $ pounce -g auth.pem
       

2. Generate and sign client certificates using the CA:

   $ pounce -A auth.pem -g client1.pem
   $ pounce -A auth.pem -g client2.pem
       

3. Since only the public key is needed for certificate verification, extract it from the CA:

   $ openssl x509 -in auth.pem -out ~/.config/pounce/auth.crt
       

4. Configure pounce to verify client certificates against the CA:

   local-ca = auth.crt
   # or: $ pounce -A auth.crt
       

Configuring CertFP

1. Generate a new TLS client certificate:

   $ pounce -g ~/.config/pounce/example.pem
       

2. Connect to the server using the certificate:

   client-cert = example.pem
   # or: $ pounce -c example.pem
       

3. Identify with services or use sasl-plain, then add the certificate fingerprint to your account:

   /msg NickServ CERT ADD
       

4. Enable SASL EXTERNAL to require successful authentication when connecting:

   client-cert = example.pem
   sasl-external
   # or: $ pounce -e -c example.pem
       

Connecting to Servers with Self-signed Certificates

1. Connect to the server and write its certificate to a file:

   $ pounce -o -h irc.example.org > ~/.config/pounce/example.pem
       

2. Configure pounce to trust the certificate:

   trust = example.pem
   # or: $ pounce -t example.pem
       

Extensions

IRCv3 Client Capability Negotiation specifies that capabilities MAY have values in ‘CAP LS’ or ‘CAP NEW’ responses. It does not, however, indicate if ‘CAP REQ’ capabilities MUST NOT have values. The pounce implementation parses ‘CAP REQ’ values in the same way as ‘CAP LS’ values.

The causal.agency/passive vendor-specific IRCv3 capability indicates that a client should not affect the automatic away status.