path: root/pounce.1

.Dd October 26, 2019
.Dt POUNCE 1
.Os
.
.Sh NAME
.Nm pounce
.Nd IRC bouncer
.
.Sh SYNOPSIS
.Nm
.Op Fl NTv
.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 W Ar pass
.Op Fl a Ar auth
.Op Fl h Ar host
.Op Fl j Ar chan
.Op Fl n Ar nick
.Op Fl p Ar port
.Op Fl r Ar real
.Op Fl u Ar user
.Op Fl w Ar pass
.
.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
The arguments are as follows:
.
.Bl -tag -width "-W @file"
.It Fl A Ar away
Set away status to
.Ar away
when no clients are connected.
.
.It Fl C Ar cert
Load TLS certificate from
.Ar cert .
The default path is
.Pa /usr/local/etc/letsencrypt/live/ Ns Ar host Ns Pa /fullchain.pem
where
.Ar host
is set by
.Fl H .
.
.It Fl H Ar host
Bind to local
.Ar host .
The default host is localhost.
.
.It Fl K Ar priv
Load TLS private key from
.Ar priv .
The default path is
.Pa /usr/local/etc/letsencrypt/live/ Ns Ar host Ns Pa /privkey.pem
where
.Ar host
is set by
.Fl H .
.
.It Fl N
Request
.Ql NAMES
for each channel when a client connects.
.
.It Fl P Ar port
Bind to local
.Ar port .
The default port is 6697.
.
.It Fl T
Request
.Ql TOPIC
for each channel when a client connects.
.
.It Fl W Ar pass
Require the password
.Ar pass
to connect.
.
.It Fl W Cm @ Ns Ar file
Set
.Fl W Ar pass
to the first line read from
.Ar file .
.
.It Fl a Ar auth
Authenticate with SASL PLAIN.
.Ar auth
is a colon-separated username and password.
.
.It Fl a Cm @ Ns Ar file
Set
.Fl a Ar auth
to the first line read from
.Ar file .
.
.It Fl h Ar host
Connect to
.Ar host .
.
.It Fl j Ar chan
Join the comma-separated list of
.Ar chan .
.
.It Fl n Ar nick
Set nickname to
.Ar nick .
The default nickname is the user's name.
.
.It Fl p Ar port
Connect to
.Ar port .
The default port is 6697.
.
.It Fl r Ar real
Set realname to
.Ar real .
The default realname is the same as the nickname.
.
.It Fl u Ar user
Set the username to
.Ar user .
The default username is the same as the nickname.
.
.It Fl v
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
Log in with the password
.Ar pass .
.
.It Fl w Cm @ Ns Ar file
Set
.Fl w Ar pass
to the first line read from
.Ar file .
.El
.
.Pp
When using
.Xr certbot 8
to obtain TLS certificates,
is it sufficient to specify the domain with
.Fl H .
.
.Sh ENVIRONMENT
.Bl -tag -width Ds
.It Ev USER
The default nickname.
.El
.
.Sh EXAMPLES
.Bd -literal
.Nm Fl H Li pounce.example.org Fl h Li chat.freenode.net Fl j Li '#ascii.town'
.Ed
.
.Sh STANDARDS
The
.Nm
daemon implements the following:
.
.Bl -item
.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 L. Hardy
.%A E. Brocklesby
.%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 Kevin L. Mitchell
.%A Perry Lorier
.%A Lee Hardy
.%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 St\('ephan Kochen
.%A Alexey Sokolov
.%A Kyle Fuller
.%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 Jilles Tjoelker
.%A William Pitcock
.%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
.
.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
.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.