IRC bouncer
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

pounce.1 9.4KB

POUNCE(1)               FreeBSD General Commands Manual              POUNCE(1)

NAME
     pounce – IRC bouncer

SYNOPSIS
     pounce [-Nev] [-A away] [-C cert] [-H host] [-K priv] [-P port] [-Q quit]
            [-U unix] [-W pass] [-a auth] [-c cert] [-f save] [-h host]
            [-j join] [-k priv] [-n nick] [-p port] [-r real] [-s size]
            [-u user] [-w pass] [config ...]
     pounce -g cert
     pounce -x

DESCRIPTION
     The pounce daemon 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.  Clients should use the IRCv3.2 server-time extension to
     know when missed messages were received and uniquely identify themselves
     by username.  See Client Configuration for details.

     Options can be loaded from files listed on the command line.  Each option
     is placed on a line, and lines beginning with ‘#’ are ignored.  The
     options are listed below following their corresponding flags.

     The arguments are as follows:

     -A mesg, away = mesg
             Set away status to mesg when no clients are connected.

     -C path, cert = path
             Load TLS certificate from path.  The default path is the
             certbot(8) path for the host set by -H.

     -H host, bind-host = host
             Bind to host.  The default host is localhost.

     -K path, priv = path
             Load TLS private key from path.  The default path is the
             certbot(8) path for the host set by -H.

     -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.

     -P port, bind-port = port
             Bind to port.  The default port is 6697.

     -Q mesg, quit = mesg
             Quit with message mesg when shutting down.

     -U path, bind-path = path
             Bind to a UNIX-domain socket at path.  Clients are accepted as
             sent by calico(1).  If path is a directory, the host set by -H is
             appended to it.  This option takes precedence over -H and -P.

     -W pass, client-pass = pass
             Require the server password pass for clients to connect.  The
             pass string must be hashed using -x.

     -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 SASL EXTERNAL instead with -e.

     -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 -k.  With -e, authenticate
             using SASL EXTERNAL.  Certificates can be generated with -g.

     -e, sasl-external
             Authenticate using SASL EXTERNAL.  The TLS client certificate is
             loaded with -c.  For more information, see Configuring SASL
             EXTERNAL.

     -f path, save = path
             Load the contents of the buffer from path, if it exists, and
             truncate it.  On shutdown, save the contents of the buffer to
             path.

     -g path
             Generate a TLS client certificate using openssl(1) and write it
             to path.

     -h host, host = host
             Connect to host.

     -j chan, join = chan
             Join the comma-separated list of chan.

     -k path, client-priv = path
             Load the TLS client private key from path.

     -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.

     -r real, real = real
             Set realname to real.  The default realname is the same as the
             nickname.

     -s size, size = size
             Set the number of messages contained in the buffer to size.  The
             size must be a power of two.  The default size is 4096.

     -u user, user = user
             Set username to user.  The default username is the same as the
             nickname.

     -v, verbose
             Write IRC messages to standard error in red to the server, green
             from the server, yellow from clients and blue to clients.

     -w pass, pass = pass
             Log in with the server password pass.

     -x      Prompt for a password and output a hash for use with -W.

     Client connections are not accepted until successful login to the server.
     If the server connection is lost, the pounce daemon exits.

     Upon receiving the SIGUSR1 signal, the certificate and private key will
     be reloaded from the paths specified by -C and -K.

   Client Configuration
     Clients should be configured to connect to the host and port set by -H
     and -P, with TLS or SSL enabled.  If -W is used, clients must send a
     server password.  Clients should not attempt SASL.

     Clients should 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.  Clients with usernames
     beginning with hyphen ‘-’ are considered passive and do not affect away
     status.  The nickname and real name sent by clients are ignored.

     Pass-through of the following IRCv3 capabilities is supported:
     account-notify, away-notify, chghost, extended-join, invite-notify,
     multi-prefix, userhost-in-names.

   Configuring SASL EXTERNAL
     1.   Generate a new TLS client certificate:

                pounce -g 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 (CertFP) 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

   Service Configuration
     Add the following to /etc/rc.conf to enable the pounce daemon:

           pounce_enable="YES"

     By default, the pounce daemon is started in the /usr/local/etc/pounce
     directory.  Configuration files in that location can be loaded by setting
     pounce_flags:

           pounce_flags="example.conf"

     The pounce service supports profiles for running multiple instances.  Set
     pounce_profiles to a space-separated list of names.  Flags for each
     profile will be set from pounce_${profile}_flags.  For example:

           pounce_profiles="example1 example2"
           pounce_example1_flags="example1.conf"
           pounce_example2_flags="example2.conf"

     The commands start, stop, etc. will operate on the profile given as an
     additional argument, or on all profiles without an additional argument.

     The reload command will cause the pounce daemon to reload certificate
     files.  To reload other configuration, use the restart command.

ENVIRONMENT
     USER    The default nickname.

EXAMPLES
     Configuration on the command line:

           pounce -H pounce.example.org -h chat.freenode.net -j '#ascii.town'

     Configuration in a file:

           bind-host = pounce.example.org
           host = chat.freenode.net
           join = #ascii.town

SEE ALSO
     calico(1)

STANDARDS
     The pounce daemon implements the following:

     Kyle Fuller, Stéphan Kochen, Alexey Sokolov, and James Wheare, IRCv3.2
     server-time Extension, IRCv3 Working Group,
     https://ircv3.net/specs/extensions/server-time-3.2.

     Lee Hardy, Perry Lorier, Kevin L. Mitchell, and William Pitcock, IRCv3.1
     Client Capability Negotiation, IRCv3 Working Group,
     https://ircv3.net/specs/core/capability-negotiation-3.1.html.

     S. Josefsson, The Base16, Base32, and Base64 Data Encodings, IETF, RFC
     4648, https://tools.ietf.org/html/rfc4648, SJD, October 2006.

     C. Kalt, Internet Relay Chat: Client Protocol, IETF, RFC 2812,
     https://tools.ietf.org/html/rfc2812, April 2000.

     William Pitcock and Jilles Tjoelker, IRCv3.1 SASL Authentication, IRCv3
     Working Group, https://ircv3.net/specs/extensions/sasl-3.1.html.

     K. Zeilenga, Ed., The PLAIN Simple Authentication and Security Layer
     (SASL) Mechanism, IETF, RFC 4616, https://tools.ietf.org/html/rfc4616,
     OpenLDAP Foundation, August 2006.

AUTHORS
     June Bug <june@causal.agency>

CAVEATS
     One instance of pounce, and therefore one local port, is required for
     each server connection.  Alternatively, the calico(1) daemon can be used
     to dispatch from one local port to many instances of pounce using Server
     Name Indication.

     The pounce daemon makes no distinction between channels.  Elevated
     activity in one channel may push messages from a quieter channel out of
     the buffer.

BUGS
     Send mail to <june@causal.agency> or join #ascii.town on
     chat.freenode.net.

     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.

FreeBSD 12.0-RELEASE-p12       November 18, 2019      FreeBSD 12.0-RELEASE-p12