document charybdis ircd.conf settings

docs/ircserver.md

@@ -30,3 +30,81 @@ Once that was added, `charybdis` could be installed:
 ```
 sudo apt-get install charybdis
 ```
+
+## Configuring charybdis
+
+We first needed to set up SSL certs, which are good for local users who want to use SSL, but also will be important if and when we allow linked tilde.club IRC servers.
+
+```
+sudo /usr/bin/charybdis-genssl
+```
+
+I'm not sure if it's critical, but I set the cert's common name to the same name I chose for the IRC server (`irc.tilde.club`); I answered the rest of the questions logically (`US`, `DC`, `Washington`, `tilde.club` for the org name, `delfuego@tilde.club` for the contact email).
+
+The next step was to edit the `/etc/charybdis/ircd.conf` file. There are a bunch of settings here, organized into sections; these are the important ones.
+
+### serverinfo section
+
+* **name**: the same name you used above for the common name of the SSL cert [`irc.tilde.club`]
+* **sid**: a unique identifier, two digits and a character; these distinguish networked servers from each other
+* **description**: simple
+* **network_name**: I actually don't think this matters [`tilde.club`]
+* **network_desc**: I also don't think this matters [`your very own network!`]
+* **hub**: determines whether servers can connect at all [`yes`]
+* **ssl_private_key**: location of the private key you generated above [`/etc/charybdis/ssl.key`]
+* **ssl_cert**: location of the SSL cert [`/etc/charybdis/ssl.cert`]
+* **ssl_dh_params**: location of the SSL Diffie-Hellman parameters file [`/etc/charybdis/dh.pem`]
+
+### admin section
+
+This info is reported when an IRC user issues the `/INFO` command, so you might want it to be accurate.
+
+### log section
+
+The defaults here are meaningless, since they're relative paths and I can't figure out what they're relative *to*. So I changed all these to absolute paths, such as:
+
+* **fname_userlog**: `/var/log/charybdis/userlog`
+
+Another important note: it appears that the file has to exist and be writeable by charybdis in order for it to be used, so for each log file you enable, the following needs to be done:
+
+```
+sudo touch /var/log/charybdis/userlog
+sudo chown charybdis.charybdis /var/log/charybdis/userlog
+sudo chmod 644 /var/log/charybdis/userlog
+```
+
+Finally, the `serverlog` file is the relevant one for debugging server-to-server connections, so that was an important one to enable.
+
+### listen section
+
+* **port**: port 6667 is the typical IRC server port [`5000, 6665 .. 6669`]
+* **sslport**: port 6697 is the typical IRC SSL server port [`6697`]
+
+### auth section
+
+There can be multiple `auth` sections, but there can't be sections that have identical `user` entries.
+
+* **user**: the mask for users allowed to connect [`*@172.30.0.0/16`]
+* **class**: the class that matching users are put into [`users`]
+
+### operator section
+
+Any users who should be able to elevate with `/OPER` need a section here; these sections are different in that the section head includes the IRC nickname of the user (e.g., `operator "ubuntu" {`).
+
+* *header*: see above, you need to include the nickname in the header
+* **user**: the full hostmask of the user [`delfuego@172.30.0.176`]
+* **password**: the password the user needs to use after issuing `/OPER`; it can be encrypted using `mkpasswd` or left unencrypted
+* **flags**: either `encrypted` if the password is encrypted, or `~encrypted` if it isn't [`encrypted`]
+
+### connect section
+
+This section is only needed if you're allowing other servers to connect and/or connecting to other servers. It's like the `operator` section in that the header includes an additional string, the name of the server to which you're connecting.
+
+* *header*: see above, this needs to be the exact name -- as in, the `name` in the `serverinfo` section -- of the server you're connecting to (or is connecting to you)
+* **host**: the IP address of the remote server
+* **send_password**: this is the password you'll send to the remote server (configured as that server's `accept_password`)
+* **accept_password**: this is the password you'll accept from the remote server (configured as that server's `send_password`)
+* **port**: the port you'll connect to on the remote server
+* **hub_mask**: the mask of hosts that a hub can introduce to each other [`*`]
+* **class**: [`server`]
+* **flags**: various flags for server-to-server behaviors [`compressed, topicburst, ssl`] *There's also an `autoconn` flag, and one of the two servers should have it enabled; I think it's good practice for us to expect the remote server to autoconnect to us, not vice-versa.*