|POUNCE(1)||FreeBSD General Commands Manual||POUNCE(1)|
pouncedaemon is a multi-client, TLS-only IRC bouncer. It maintains a persistent connection to an IRC server while allowing clients to connect and disconnect, receiving messages that were missed upon reconnection. The IRCv3 server-time extension is used to indicate when messages were originally received.
One instance of
pounce must be configured
for each IRC network. Instances of
either use different local ports with
different local hosts with
-U to be dispatched from the same port by
TLS certificates can be automatically loaded from
/usr/local/etc/letsencrypt (or equivalent) based on
the local host set by
-H. These certificates can be
obtained using certbot(8).
Clients must uniquely identify themselves to
pounce by their IRC username. See
Client Configuration for
Options can be loaded from files listed on the command line. Files
are searched for in $XDG_CONFIG_DIRS/pounce unless
the path starts with ‘
../’. Certificate and private key
paths are searched for in the same manner. Each option is placed on a line,
and lines beginning with ‘
ignored. The options are listed below following their corresponding
The arguments are as follows:
- Require clients to authenticate using a TLS client certificate signed by
the certificate authority loaded from path. See
-Wis also set, clients may instead authenticate with a server password.
- Load TLS certificate from path. The default path is
the certbot(8) path for the
host set by
- Bind to host. The default host is localhost.
- Load TLS private key from path. The default path is
the certbot(8) path for the
host set by
- 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.
- 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.
- Bind to port. The default port is 6697.
- Set the server send queue interval in milliseconds. The queue is only used
for automated messages sent by
pounce. Messages from clients are sent to the server immediately. The default interval is 200 milliseconds.
- Blindly request the IRCv3 capabilities caps. This can be used to enable hidden capabilities, such as userhost-in-names on some networks.
- Bind to source address host when connecting to the server.
- Do not advertise a strict transport security (STS) policy to clients.
- 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
-His appended to it. This option takes precedence over
- Require the server password pass for clients to
connect. The pass string must be hashed using
-Ais also set, clients may instead authenticate using a TLS client certificate.
- Authenticate as user with pass
using SASL PLAIN. Since this method requires the account password in
plaintext, it is recommended to use SASL EXTERNAL instead with
- Load the TLS client certificate from path. If the
private key is in a separate file, it is loaded with
-e, authenticate using SASL EXTERNAL. Certificates can be generated with
- Authenticate using SASL EXTERNAL, also known as CertFP. The TLS client
certificate is loaded with
-c. See Configuring CertFP.
- Save and load the contents of the buffer from path
in $XDG_DATA_DIRS/pounce, or an absolute or
relative path if path starts with
./’ or ‘
../’. The file is truncated after loading.
- Generate a TLS client certificate using
openssl(1) and write it to
path. The certificate is signed by the certificate
-Ais set, otherwise it is self-signed.
- Connect to host.
-jchannels [keys] |
join= channels [keys]
- Join the comma-separated list of channels with the optional comma-separated list of channel keys.
- Load the TLS client private key from path.
- Set the user mode.
- Set nickname to nick. The default nickname is the user's name.
- Print the server certificate chain to standard output in PEM format and exit.
- Connect to port. The default port is 6697.
- Quit with message mesg when shutting down.
- Set realname to real. The default realname is the same as the nickname.
- Set the number of messages contained in the buffer to size. The size must be a power of two. The default size is 4096.
- Trust the certificate loaded from path. Server name verification is disabled. See Connecting to Servers with Self-signed Certificates.
- Set username to user. The default username is the same as the nickname.
- Write IRC messages to standard error in the following colors:
pounceto the server
- from the server to
- from clients to
- Log in with the server password pass.
- Prompt for a password and output a hash for use with
- Set away status to mesg when no clients are connected.
Client connections are not accepted until successful login to the
server. If the server connection is lost, the
Upon receiving the
SIGUSR1 signal, the
certificate, private key and local CA will be reloaded from the paths
-P, with TLS or SSL enabled. If
-Wis used, clients must send a server password. If
-Ais used, clients must connect with a client certificate and may request SASL EXTERNAL. If both are used, clients may authenticate with either method.
Clients must register with unique usernames, 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.
- Generate self-signed client certificates and private keys:
pounce -g client1.pem pounce -g client2.pem
- 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
pounceto 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:
- Generate a self-signed certificate authority:
pounce -g auth.pem
- Generate and sign client certificates using the CA:
pounce -A auth.pem -g client1.pem pounce -A auth.pem -g client2.pem
- 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
pounceto verify client certificates against the CA:
local-ca = auth.crt # or: pounce -A auth.crt
- Generate a new TLS client certificate:
pounce -g ~/.config/pounce/example.pem
- Connect to the server using the certificate:
client-cert = example.pem # or: pounce -c example.pem
- Identify with services or use
sasl-plain, then add the certificate fingerprint to your account:
/msg NickServ CERT ADD
- Enable SASL EXTERNAL to require successful authentication when connecting:
client-cert = example.pem sasl-external # or: pounce -e -c example.pem
- Connect to the server and write its certificate to a file:
pounce -o -h irc.example.org > ~/.config/pounce/example.pem
pounceto trust the certificate:
trust = example.pem # or: pounce -t example.pem
- The default nickname.
- Configuration files, certificates and private keys are searched for first
$XDG_CONFIG_HOME, usually ~/.config, followed by the colon-separated list of paths
$XDG_CONFIG_DIRS, usually /etc/xdg.
- The most likely location of configuration files.
- Save files are searched for first in
$XDG_DATA_HOME, usually ~/.local/share, followed by the colon-separated list of paths
$XDG_DATA_DIRS, usually /usr/local/share:/usr/share. New save files are created in
- The most likely location of save files.
sudo certbot certonly -d irc.example.org sudo chown :$USER /etc/letsencrypt/live/irc.example.org/privkey.pem sudo chmod g+r /etc/letsencrypt/live/irc.example.org/privkey.pem
pounce -H irc.example.org -h irc.tilde.chat -j '#ascii.town'
Equivalent configuration file:
local-host = irc.example.org host = irc.tilde.chat join = #ascii.town
- Waldo Bastian, Ryan Lortie, and Lennart Poettering, XDG Base Directory Specification, https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html, November 24, 2010.
- Kyle Fuller, Stéphan Kochen, Alexey Sokolov, and James Wheare, server-time Extension, IRCv3 Working Group, https://ircv3.net/specs/extensions/server-time.
- Lee Hardy, Perry Lorier, Kevin L. Mitchell, Attila Molnar, Daniel Oakley, William Pitcock, and James Wheare, IRCv3 Client Capability Negotiation, IRCv3 Working Group, https://ircv3.net/specs/core/capability-negotiation.
- S. Josefsson, The Base16, Base32, and Base64 Data Encodings, IETF, RFC 4648, https://tools.ietf.org/html/rfc4648, October 2006.
- C. Kalt, Internet Relay Chat: Client Protocol, IETF, RFC 2812, https://tools.ietf.org/html/rfc2812, April 2000.
- Attila Molnar and James Wheare, IRCv3 Strict Transport Security, IRCv3 Working Group, https://ircv3.net/specs/extensions/sts.
- Attila Molnar and William Pitcock, IRCv3.2 SASL Authentication, IRCv3 Working Group, https://ircv3.net/specs/extensions/sasl-3.2.
- K. Zeilenga, Ed., The PLAIN Simple Authentication and Security Layer (SASL) Mechanism, IETF, RFC 4616, https://tools.ietf.org/html/rfc4616, August 2006.
@causal.agency/pos=42069’. This capability may be requested with the value of the last causal.agency/pos tag received by the client, e.g. ‘
CAP REQ causal.agency/consumer=42069’, setting its consumer position. By persisting this value across connections, a client can ensure no messages are missed, even in case of network issues or application crashes.
IRCv3 Client Capability Negotiation
specifies that capabilities MAY have values in ‘
LS’ or ‘
responses. It does not, however, indicate if ‘
REQ’ capabilities MUST NOT have values. The
pounce daemon parses ‘
REQ’ values in the same way as ‘
The causal.agency/passive vendor-specific IRCv3 capability indicates that a client should not affect the automatic away status.
pounceis required for each server connection. The
pouncedaemon must be restarted if the server connection is lost.
pounce daemon makes no distinction
between channels. Elevated activity in one channel may push messages from a
quieter channel out of the buffer.
A client will sometimes receive its own message, causing it to be displayed twice. This happens when a message is sent while responses are not yet consumed.
|June 18, 2021||FreeBSD 12.2-RELEASE-p7|