explain use of irc authentication

An overview of nickname management and authentication in IRC is provided
from a new user's perspective, explaining why authentication is
necessary, guiding the user towards how to setup authentication, and
explaining how tools like soju and gamja assist the user.

In particular, OFTC is discussed, as soju and gamja's features, which
rely upon IRC extensions, do not work with it -- this has been a common
pain point for users (according to ~emersion).

1 files changed, 43 insertions, 6 deletions

diff --git a/chat.sr.ht/bouncer-usage.md b/chat.sr.ht/bouncer-usage.md
index e0e42e0..a085935 100644
--- a/chat.sr.ht/bouncer-usage.md
+++ b/chat.sr.ht/bouncer-usage.md
@@ -3,6 +3,8 @@
 For full details, refer to the [soju(1)] man page. Information about common
 use-cases is provided here.
 
+[soju(1)]: https://soju.im/doc/soju.1.html#IRC_SERVICE
+
 ## Connecting with a third-party IRC client
 
 Check out the [quickstart for experienced IRC users][quickstart] for details on
@@ -12,11 +14,10 @@ configuring your own IRC client for use with chat.sr.ht.
 
 ## Managing your IRC networks
 
-The webchat at [https://chat.sr.ht](https://chat.sr.ht) provides a UI for
-managing your bouncer networks. Third-party clients with soju support may detect
-the bouncer and offer similar functionality. If not, you can also message
-BouncerServ to configure soju. Use `/msg BouncerServ help` for a full list of
-supported commands.
+The webchat at [chat.sr.ht] provides a UI for managing your bouncer networks.
+Third-party clients with soju support may detect the bouncer and offer similar
+functionality. If not, you can also message BouncerServ to configure soju. Use
+`/msg BouncerServ help` for a full list of supported commands.
 
 To add a new IRC network via BouncerServ:
 
@@ -26,7 +27,43 @@ To add a new IRC network via BouncerServ:
 
 See [soju(1)] for details on the supported options.
 
-[soju(1)]: https://soju.im/doc/soju.1.html#IRC_SERVICE
+[chat.sr.ht]: https://chat.sr.ht
+
+## Authentication
+
+In IRC, communicating with a user requires knowing their "nickname" ("nick" for
+short).  Traditionally, IRC would allow users to pick any nick they like -- even
+one commonly used by someone else.  Today, in order to "register" a nick so that
+others cannot use it, a system called SASL is used.  chat.sr.ht uses SASL to
+automatically log you in to the networks you use, and prompts you for your login
+details when you first connect to a new network.
+
+SASL can be manually configured for soju(1) using BouncerServ; see the `sasl`
+command (try `help sasl`).
+
+Note that IRC networks are independent with regards to nickname registration;
+you must register your nickname manually for every IRC network you use.  Beware
+that your nickname may be registered by someone else on a network already, and
+that nickname registrations may be inconsistent across the networks you use (a
+nickname may be registered on one network but available on another).
+
+Unfortunately, not all networks support SASL.  There are alternative methods for
+nickname management, which are not recommended but in such cases necessary.  The
+effectively-universal but now-legacy system is NickServ, an IRC bot which can be
+messaged to control it (to try using it, send it the message "help").  Note that
+there is an independent instance of NickServ on every network.  To log in using
+NickServ, you have to message it an "IDENTIFY" command every time you connect to
+a network.  This can be automated using advanced configuration within soju(1)
+(BouncerServ provides the `-connect-command` option within `network` for this).
+CertFP is another commonly-available system, but can be difficult to set up for
+the first time -- see the [libera.chat guide][libera.chat-certfp], and then the
+`certfp` command within BouncerServ.
+
+[libera.chat-certfp]: https://libera.chat/guides/certfp
+
+> [The OFTC network](https://oftc.net) is relatively popular, and currently does
+> not provide SASL support.  This is why chat.sr.ht does not prompt the user for
+> SASL-based login details when connecting to it.
 
 ## Detaching from channels