Clarify or otherwise expand documentation

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