path: root/pounce.1

.Dd November 6, 2019
.Dt POUNCE 1
.Os
.
.Sh NAME
.Nm pounce
.Nd IRC bouncer
.
.Sh SYNOPSIS
.Nm
.Op Fl Nev
.Op Fl A Ar away
.Op Fl C Ar cert
.Op Fl H Ar host
.Op Fl K Ar priv
.Op Fl P Ar port
.Op Fl Q Ar quit
.Op Fl U Ar unix
.Op Fl W Ar pass
.Op Fl a Ar auth
.Op Fl c Ar cert
.Op Fl f Ar save
.Op Fl h Ar host
.Op Fl j Ar join
.Op Fl k Ar priv
.Op Fl n Ar nick
.Op Fl p Ar port
.Op Fl r Ar real
.Op Fl s Ar size
.Op Fl u Ar user
.Op Fl w Ar pass
.Op Ar config ...
.
.Nm
.Fl g Ar cert
.
.Nm
.Fl x
.
.Sh DESCRIPTION
The
.Nm
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.
.
.Pp
Options can be loaded from
files listed on the command line.
Each option is placed on a line,
and lines beginning with
.Ql #
are ignored.
The options are listed below
following their corresponding flags.
.
.Pp
The arguments are as follows:
.
.Bl -tag -width Ds
.It Fl A Ar mesg , Cm away = Ar mesg
Set away status to
.Ar mesg
when no clients are connected.
.
.It Fl C Ar path , Cm cert = Ar path
Load TLS certificate from
.Ar path .
The default path is the
.Xr certbot 8
path for the
.Ar host
set by
.Fl H .
.
.It Fl H Ar host , Cm bind-host = Ar host
Bind to
.Ar host .
The default host is localhost.
.
.It Fl K Ar path , Cm priv = Ar path
Load TLS private key from
.Ar path .
The default path is the
.Xr certbot 8
path for the
.Ar host
set by
.Fl H .
.
.It Fl N , Cm names
Request
.Ql NAMES
for each channel when a client connects.
This allows clients to populate user lists,
but may just cause noise for some.
.
.It Fl P Ar port , Cm bind-port = Ar port
Bind to
.Ar port .
The default port is 6697.
.
.It Fl Q Ar mesg , Cm quit = Ar mesg
Quit with message
.Ar mesg
when shutting down.
.
.It Fl U Ar path , Cm bind-path = Ar path
Bind to a UNIX-domain socket at
.Ar path .
Clients are accepted as sent by
.Xr calico 1 .
If
.Ar path
is a directory,
the
.Ar host
set by
.Fl H
is appended to it.
This option takes precedence over
.Fl H
and
.Fl P .
.
.It Fl W Ar pass , Cm client-pass = Ar pass
Require the server password
.Ar pass
for clients to connect.
The
.Ar pass
string must be hashed using
.Fl x .
.
.It Fl a Ar user : Ns Ar pass , Cm sasl-plain = Ar user : Ns Ar pass
Authenticate as
.Ar user
with
.Ar pass
using SASL PLAIN.
Since this method requires
the account password in plaintext,
it is recommended to use SASL EXTERNAL instead with
.Fl e .
.
.It Fl c Ar path , Cm client-cert = Ar path
Load the TLS client certificate from
.Ar path .
If the private key is in a separate file,
it is loaded with
.Fl k .
With
.Fl e ,
authenticate using SASL EXTERNAL.
Certificates can be generated with
.Fl g .
.
.It Fl e , Cm sasl-external
Authenticate using SASL EXTERNAL.
The TLS client certificate is loaded with
.Fl c .
For more information, see
.Sx Configuring SASL EXTERNAL .
.
.It Fl f Ar path , Cm save = Ar path
Load the contents of the buffer from
.Ar path ,
if it exists,
and truncate it.
On shutdown,
save the contents of the buffer to
.Ar path .
.
.It Fl g Ar path
Generate a TLS client certificate using
.Xr openssl 1
and write it to
.Ar path .
.
.It Fl h Ar host , Cm host = Ar host
Connect to
.Ar host .
.
.It Fl j Ar chan , Cm join = Ar chan
Join the comma-separated list of
.Ar chan .
.
.It Fl k Ar path , Cm client-priv = Ar path
Load the TLS client private key from
.Ar path .
.
.It Fl n Ar nick , Cm nick = Ar nick
Set nickname to
.Ar nick .
The default nickname is the user's name.
.
.It Fl p Ar port , Cm port = Ar port
Connect to
.Ar port .
The default port is 6697.
.
.It Fl r Ar real , Cm real = Ar real
Set realname to
.Ar real .
The default realname is the same as the nickname.
.
.It Fl s Ar size , Cm size = Ar size
Set the number of messages contained in the buffer to
.Ar size .
The size must be a power of two.
The default size is 4096.
.
.It Fl u Ar user , Cm user = Ar user
Set username to
.Ar user .
The default username is the same as the nickname.
.
.It Fl v , Cm verbose
Write IRC messages to standard error
in red to the server,
green from the server,
yellow from clients
and blue to clients.
.
.It Fl w Ar pass , Cm pass = Ar pass
Log in with the server password
.Ar pass .
.
.It Fl x
Prompt for a password
and output a hash
for use with
.Fl W .
.El
.
.Pp
Upon receiving the
.Dv SIGUSR1
signal,
the certificate and private key
will be reloaded from the paths
specified by
.Fl C
and
.Fl K .
.
.Ss Configuring SASL EXTERNAL
.Bl -enum
.It
Generate a new TLS client certificate:
.Bd -literal -offset indent
pounce -g example.pem
.Ed
.It
Connect to the server using the certificate:
.Bd -literal -offset indent
client-cert = example.pem
# or: pounce -c example.pem
.Ed
.It
Identify with services or use
.Cm sasl-plain ,
then add the certificate fingerprint to your account:
.Bd -literal -offset indent
/msg NickServ CERT ADD
.Ed
.It
Enable SASL EXTERNAL
to require successful authentication when connecting:
.Bd -literal -offset indent
client-cert = example.pem
sasl-external
# or: pounce -e -c example.pem
.Ed
.El
.
.Ss Service Configuration
Add the following to
.Pa /etc/rc.conf
to enable the
.Nm
daemon:
.Bd -literal -offset indent
pounce_enable="YES"
.Ed
.
.Pp
By default,
the
.Nm
daemon is started in the
.Pa /usr/local/etc/pounce
directory.
Configuration files in that location
can be loaded by setting
.Va pounce_flags :
.Bd -literal -offset indent
pounce_flags="example.conf"
.Ed
.
.Pp
The
.Nm
service supports profiles
for running multiple instances.
Set
.Va pounce_profiles
to a space-separated list of names.
Flags for each profile will be set from
.Va pounce_${profile}_flags .
For example:
.Bd -literal -offset indent
pounce_profiles="example1 example2"
pounce_example1_flags="example1.conf"
pounce_example2_flags="example2.conf"
.Ed
.
.Pp
The commands
.Cm start , stop ,
etc.\&
will operate on the profile given as an additional argument,
or on all profiles without an additional argument.
.
.Pp
The
.Cm reload
command will cause the
.Nm
daemon to reload certificate files.
To reload other configuration,
use the
.Cm restart
command.
.
.Sh ENVIRONMENT
.Bl -tag -width Ds
.It Ev USER
The default nickname.
.El
.
.Sh EXAMPLES
Configuration on the command line:
.Bd -literal -offset indent
pounce -H pounce.example.org -h chat.freenode.net -j '#ascii.town'
.Ed
.
.Pp
Configuration in a file:
.Bd -literal -offset indent
bind-host = pounce.example.org
host = chat.freenode.net
join = #ascii.town
.Ed
.
.Sh SEE ALSO
.Xr calico 1
.
.Sh STANDARDS
The
.Nm
daemon implements the following:
.
.Bl -item
.It
.Rs
.%A E. Brocklesby
.%A L. Hardy
.%A K. Mitchell
.%T IRC RPL_ISUPPORT Numeric Definition
.%I IETF
.%D January 2005
.%U https://tools.ietf.org/html/draft-hardy-irc-isupport-00
.Re
.
.It
.Rs
.%A Kyle Fuller
.%A St\('ephan Kochen
.%A Alexey Sokolov
.%A James Wheare
.%T IRCv3.2 server-time Extension
.%I IRCv3 Working Group
.%U https://ircv3.net/specs/extensions/server-time-3.2
.Re
.
.It
.Rs
.%A Lee Hardy
.%A Perry Lorier
.%A Kevin L. Mitchell
.%A William Pitcock
.%T IRCv3.1 Client Capability Negotiation
.%I IRCv3 Working Group
.%U https://ircv3.net/specs/core/capability-negotiation-3.1.html
.Re
.
.It
.Rs
.%A S. Josefsson
.%Q SJD
.%T The Base16, Base32, and Base64 Data Encodings
.%I IETF
.%N RFC 4648
.%D October 2006
.%U https://tools.ietf.org/html/rfc4648
.Re
.
.It
.Rs
.%A C. Kalt
.%T Internet Relay Chat: Client Protocol
.%I IETF
.%N RFC 2812
.%D April 2000
.%U https://tools.ietf.org/html/rfc2812
.Re
.
.It
.Rs
.%A William Pitcock
.%A Jilles Tjoelker
.%T IRCv3.1 SASL Authentication
.%I IRCv3 Working Group
.%U https://ircv3.net/specs/extensions/sasl-3.1.html
.Re
.
.It
.Rs
.%A K. Zeilenga, Ed.
.%Q OpenLDAP Foundation
.%T The PLAIN Simple Authentication and Security Layer (SASL) Mechanism
.%I IETF
.%N RFC 4616
.%D August 2006
.%U https://tools.ietf.org/html/rfc4616
.Re
.El
.
.Sh AUTHORS
.An June Bug Aq Mt june@causal.agency
.
.Sh CAVEATS
One instance of
.Nm ,
and therefore one local port,
is required for each server connection.
Alternatively,
the
.Xr calico 1
daemon can be used to dispatch from one local port
to many instances of
.Nm
using Server Name Indication.
.
.Pp
The
.Nm
daemon makes no distinction between channels.
Elevated activity in one channel
may push messages from a quieter channel
out of the buffer.
.
.Sh BUGS
Send mail to
.Aq Mt june@causal.agency
or join
.Li #ascii.town
on
.Li chat.freenode.net .