diff options
| -rw-r--r-- | calico.1 | 58 | ||||
| -rw-r--r-- | pounce.1 | 154 |
2 files changed, 134 insertions, 78 deletions
diff --git a/calico.1 b/calico.1 index 00a6c12..1c28365 100644 --- a/calico.1 +++ b/calico.1 @@ -1,4 +1,4 @@ -.Dd May 18, 2020 +.Dd May 19, 2020 .Dt CALICO 1 .Os . @@ -26,11 +26,19 @@ Instances of should be configured with .Fl U to bind to UNIX-domain sockets -named by the host they wish to accept connections for in the directory passed to .Nm . . .Pp +Note that +.Nm +is not a proxy. +Incoming connections are passed directly +to instances of +.Xr pounce 1 , +which handle TLS negotiation. +. +.Pp The arguments are as follows: .Bl -tag -width Ds .It Fl H Ar host @@ -82,45 +90,51 @@ The and .Xr pounce 1 services can be started and stopped -completely independently of each other. +independently of each other. . .Sh EXAMPLES +Obtain certificates for +and dispatch to two instances of +.Xr pounce 1 : .Bd -literal -offset indent -pounce -U sockets/foo.example.org foo.conf -pounce -U sockets/bar.example.org bar.conf -calico -H example.org sockets/ +certbot certonly -d oftc.example.org +certbot certonly -d freenode.example.org +pounce -U /var/run/calico -H oftc.example.org oftc.conf +pounce -U /var/run/calico -H freenode.example.org freenode.conf +calico -H example.org /var/run/calico .Ed +.Pp +The two instances can be connected to via +.Li oftc.example.org:6697 +and +.Li freenode.example.org:6697 , +respectively. . .Sh SEE ALSO .Xr pounce 1 . .Sh STANDARDS -The -.Nm -daemon implements the following: -. .Bl -item .It .Rs -.%A E. Rescorla -.%Q Mozilla -.%T The Transport Layer Security (TLS) Protocol Version 1.3 -.%I IETF -.%N RFC 8446 -.%D August 2018 -.%U https://tools.ietf.org/html/rfc8446 -.Re -. -.It -.Rs +.%R RFC 6066 .%A D. Eastlake 3rd .%Q Huawei .%T Transport Layer Security (TLS) Extensions: Extension Definitions .%I IETF -.%N RFC 6066 .%D January 2011 .%U https://tools.ietf.org/html/rfc6066 .Re +. +.It +.Rs +.%R RFC 8446 +.%A E. Rescorla +.%T The Transport Layer Security (TLS) Protocol Version 1.3 +.%I IETF +.%D August 2018 +.%U https://tools.ietf.org/html/rfc8446 +.Re .El . .Sh AUTHORS diff --git a/pounce.1 b/pounce.1 index ef4f242..cf0e10b 100644 --- a/pounce.1 +++ b/pounce.1 @@ -1,4 +1,4 @@ -.Dd May 18, 2020 +.Dd May 19, 2020 .Dt POUNCE 1 .Os . @@ -49,11 +49,39 @@ 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 +The IRCv3.2 .Sy server-time -extension -to know when missed messages were received -and uniquely identify themselves by username. +extension is used to indicate +when messages were originally received. +. +.Pp +One instance of +.Nm +must be configured for each IRC network. +Instances of +.Nm +must either use different local ports with +.Fl P +or different local hosts with +.Fl H +and +.Fl U +to be dispatched from the same port by +.Xr calico 1 . +. +.Pp +TLS certificates can be automatically loaded from +.Pa /usr/local/etc/letsencrypt +(or equivalent) +based on the local host set by +.Fl H . +These certificates can be obtained using +.Xr certbot 8 . +. +.Pp +Clients must uniquely identify themselves to +.Nm +by their IRC username. See .Sx Client Configuration for details. @@ -82,7 +110,7 @@ See If .Fl W is also set, -clients may instead connect +clients may instead authenticate with a server password. . .It Fl C Ar path , Cm local-cert = Ar path @@ -145,7 +173,7 @@ to clients. .It Fl U Ar path , Cm local-path = Ar path Bind to a UNIX-domain socket at .Ar path . -Clients are accepted as sent by +Clients are only accepted as dispatched by .Xr calico 1 . If .Ar path @@ -171,7 +199,7 @@ string must be hashed using If .Fl A is also set, -clients may instead connect +clients may instead authenticate using a TLS client certificate. . .It Fl a Ar user : Ns Ar pass , Cm sasl-plain = Ar user : Ns Ar pass @@ -202,7 +230,7 @@ Authenticate using SASL EXTERNAL, also known as CertFP. The TLS client certificate is loaded with .Fl c . -For more information, see +See .Sx Configuring CertFP . . .It Fl f Ar path , Cm save = Ar path @@ -270,10 +298,24 @@ 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. +in the following colors: +.Pp +.Bl -tag -width Ds -compact +.It red +from +.Nm +to the server +.It green +from the server to +.Nm +.It yellow +from clients to +.Nm +.It blue +from +.Nm +to clients +.El . .It Fl w Ar pass , Cm pass = Ar pass Log in with the server password @@ -330,7 +372,7 @@ If both are used, clients may authenticate with either method. . .Pp -Clients should register with unique usernames, +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 @@ -347,7 +389,7 @@ capability or with usernames beginning with hyphen .Ql - are considered passive -and do not affect away status. +and do not affect automatic away status. . .Pp Pass-through of the following IRCv3 capabilities @@ -501,13 +543,15 @@ The default nickname. .El . .Sh EXAMPLES -Configuration on the command line: +Obtain a certificate and start +.Nm : .Bd -literal -offset indent +certbot certonly -d pounce.example.org pounce -H pounce.example.org -h chat.freenode.net -j '#ascii.town' .Ed . .Pp -Configuration in a file: +Equivalent configuration file: .Bd -literal -offset indent local-host = pounce.example.org host = chat.freenode.net @@ -518,45 +562,55 @@ join = #ascii.town .Xr calico 1 . .Sh STANDARDS -The -.Nm -daemon implements the following: -. .Bl -item .It .Rs -.%A Attila Molnar -.%A James Wheare -.%T IRCv3 Strict Transport Security -.%I IRCv3 Working Group -.%U https://ircv3.net/specs/extensions/sts -.Re -.It -.Rs -.%A Attila Molnar -.%A William Pitcock -.%T IRCv3.2 SASL Authentication -.%I IRCv3 Working Group -.%U https://ircv3.net/specs/extensions/sasl-3.2 -.Re -.It -.Rs +.%R RFC 2812 .%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 +.%R RFC 4616 .%A K. Zeilenga, Ed. .%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 +.%T The Base16, Base32, and Base64 Data Encodings +.%I IETF +.%R RFC 4648 +.%D October 2006 +.%U https://tools.ietf.org/html/rfc4648 +.Re +. +.It +.Rs +.%A Attila Molnar +.%A James Wheare +.%T IRCv3 Strict Transport Security +.%I IRCv3 Working Group +.%U https://ircv3.net/specs/extensions/sts +.Re +. +.It +.Rs +.%A Attila Molnar +.%A William Pitcock +.%T IRCv3.2 SASL Authentication +.%I IRCv3 Working Group +.%U https://ircv3.net/specs/extensions/sasl-3.2 +.Re +. .It .Rs .%A Kevin L. Mitchell @@ -570,15 +624,7 @@ daemon implements the following: .%I IRCv3 Working Group .%U https://ircv3.net/specs/core/capability-negotiation .Re -.It -.Rs -.%A S. Josefsson -.%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 St\('ephan Kochen @@ -646,16 +692,12 @@ should not affect the automatic away status. . .Sh CAVEATS One instance of -.Nm , -and therefore one local port, +.Nm 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 +The .Nm -using Server Name Indication. +daemon must be restarted +if the server connection is lost. . .Pp The |