Merge pull request #1048 from slingamn/documentation_fixes

documentation fixes

CHANGELOG.md

@@ -10,7 +10,7 @@ Since the release of 2.0.0 in March, a number of new communities and organizatio
 * Tighter control over the relationship between account names and nicknames, eliminating the need for extbans
 * Support for sending account verification emails directly from Oragono, including DKIM signatures
 
-Many thanks to [@ajaspers](https://github.com/ajaspers) and [@hhirtz](https://github.com/hhirtz) for contributing patches, to [@ajaspers](https://github.com/ajaspers), [@eklitzke](https://github.com/eklitzke), and [@hhirtz](https://github.com/hhirtz) for contributing code reviews, to [@ajaspers](https://github.com/ajaspers), [@bogdomania](https://github.com/bogdomania), [@clukawski](https://github.com/clukawski), Csibesz, [@csmith](https://github.com/csmith), [@eklitzke](https://github.com/eklitzke), [@nxths](https://github.com/nxths), [@hhirtz](https://github.com/hhirtz), [@jesopo](https://github.com/jesopo), [@jlnt](https://github.com/jlnt), [@justjanne](https://github.com/justjanne), [@jwheare](https://github.com/jwheare), [@k4bek4be](https://github.com/k4bek4be), [@kula](https://github.com/kula), [@kylef](https://github.com/kylef), [@Mitaka8](https://github.com/Mitaka8), [@petteri](https://github.com/petteri), [@PizzaLover2007](https://github.com/PizzaLover2007), [@prawnsalad](https://github.com/prawnsalad), [@RyanSquared](https://github.com/RyanSquared), savoyard, and [@xPaw](https://github.com/xPaw) for reporting issues, and to TODO: TRANSLATORS for contributing translations.
+Many thanks to [@ajaspers](https://github.com/ajaspers) and [@hhirtz](https://github.com/hhirtz) for contributing patches, to [@ajaspers](https://github.com/ajaspers), [@eklitzke](https://github.com/eklitzke), and [@hhirtz](https://github.com/hhirtz) for contributing code reviews, to [@ajaspers](https://github.com/ajaspers), [@bogdomania](https://github.com/bogdomania), [@clukawski](https://github.com/clukawski), Csibesz, [@csmith](https://github.com/csmith), [@eklitzke](https://github.com/eklitzke), [@nxths](https://github.com/nxths), [@hhirtz](https://github.com/hhirtz), [@jesopo](https://github.com/jesopo), [@jlnt](https://github.com/jlnt), [@justjanne](https://github.com/justjanne), [@jwheare](https://github.com/jwheare), [@k4bek4be](https://github.com/k4bek4be), [@KoraggKnightWolf](https://github.com/KoraggKnightWolf), [@kula](https://github.com/kula), [@kylef](https://github.com/kylef), [@Mitaka8](https://github.com/Mitaka8), [@petteri](https://github.com/petteri), [@PizzaLover2007](https://github.com/PizzaLover2007), [@prawnsalad](https://github.com/prawnsalad), [@RyanSquared](https://github.com/RyanSquared), savoyard, and [@xPaw](https://github.com/xPaw) for reporting issues, and to [@bogdomania](https://github.com/bogdomania), [@boppy](https://github.com/boppy), Nuve, stickytoffeepuddingwithcaramel, and [@vegax87](https://github.com/vegax87) for contributing translations.
 
 This release includes changes to the config file format, including one breaking change: support for `server.ip-cloaking.secret-environment-variable` has been removed. (See below for instructions on how to upgrade if you were using this feature.) All other changes to the config file format are backwards compatible and do not require updating before restart.
 
@@ -53,12 +53,15 @@ This release includes a change to the MySQL schema. This change will be applied
 * Fixed some channels not being unregistered during account unregistration (#889)
 * Fixed `/NICKSERV SET` and related commands being unavailable when account registration is disabled (#922, thanks [@PizzaLover2007](https://github.com/PizzaLover2007)!)
 * Fixed `TAGMSG` not being replayed correctly in history (#1044)
+* Fixed incorrect `401 ERR_NOSUCHNICK` responses on `TAGMSG` sent to a service (#1051, thanks [@ajaspers](https://github.com/ajaspers)!)
 * Fixed `301 RPL_AWAY` not being sent in `WHOIS` responses when applicable (#850)
 * `/OPER` with no password no longer disconnects the client (#951)
 * Fixed failure to send extended-join responses after account unregistration (#933, thanks [@jesopo](https://github.com/jesopo)!)
 * Improved validation of channel keys (#1021, thanks [@kylef](https://github.com/kylef)!)
 * Fixed labeling of `421 ERR_UNKNOWNCOMMAND` responses (#994, thanks [@k4bek4be](https://github.com/k4bek4be)!)
 * Fixed incorrect parsing of ident protocol responses (#1002, thanks [@justjanne](https://github.com/justjanne)!)
+* Fixed registration completing after `NICK` and an ident response, without waiting for `USER` (#1057, thanks [@KoraggKnightWolf](https://github.com/KoraggKnightWolf)!)
+* Fixed messages rejected by the `+R` mode being stored in history (#1061, thanks [@KoraggKnightWolf](https://github.com/KoraggKnightWolf)!)
 * Fixed redundant `/INVITE` commands not sending `443 ERR_USERONCHANNEL` (#842, thanks [@hhirtz](https://github.com/hhirtz)!)
 * Fixed `/NICKSERV REGISTER` response displaying `mailto:` out of context (#985, thanks [@eklitzke](https://github.com/eklitzke)!)
 * Fixed HostServ approval and rejection notices being sent from the wrong source (#805)

docs/MANUAL.md

@@ -29,6 +29,7 @@ _Copyright © Daniel Oaks <daniel@danieloaks.net>, Shivaram Lingamneni <slingamn
 - Features
     - User Accounts
         - Nickname reservation
+        - Email verification
     - Channel Registration
     - Language
     - Multiclient ("Bouncer")
@@ -140,7 +141,7 @@ The recommended way to operate oragono as a service on Linux is via systemd. Thi
 The only major distribution that currently packages Oragono is Arch Linux; the aforementioned AUR package includes a systemd unit file. However, it should be fairly straightforward to set up a productionized Oragono on any Linux distribution. Here's a quickstart guide for Debian/Ubuntu:
 
 1. Create a dedicated, unprivileged role user who will own the oragono process and all its associated files: `adduser --system --group oragono`. This user now has a home directory at `/home/oragono`.
-1. Copy the executable binary `oragono`, the config file `ircd.yaml`, the database `ircd.db`, and the self-signed TLS certificate (`tls.crt` and `tls.key`) to `/home/oragono`. Ensure that they are all owned by the new oragono role user: `sudo chown oragono:oragono /home/oragono/*`. Ensure that the configuration file logs to stderr.
+1. Copy the executable binary `oragono`, the config file `ircd.yaml`, the database `ircd.db`, and the self-signed TLS certificate (`fullchain.pem` and `privkey.pem`) to `/home/oragono`. Ensure that they are all owned by the new oragono role user: `sudo chown oragono:oragono /home/oragono/*`. Ensure that the configuration file logs to stderr.
 1. Install our example [oragono.service](https://github.com/oragono/oragono/blob/master/distrib/systemd/oragono.service) file to `/etc/systemd/system/oragono.service`.
 1. Enable and start the new service with the following commands:
     1. `systemctl daemon-reload`
@@ -159,9 +160,9 @@ The other major hurdle for productionizing (but one well worth the effort) is ob
 set -eu
 
 umask 077
-cp /etc/letsencrypt/live/example.com/fullchain.pem /home/oragono/tls.crt
-cp /etc/letsencrypt/live/example.com/privkey.pem /home/oragono/tls.key
-chown oragono:oragono /home/oragono/tls.*
+cp /etc/letsencrypt/live/example.com/fullchain.pem /home/oragono/
+cp /etc/letsencrypt/live/example.com/privkey.pem /home/oragono/
+chown oragono:oragono /home/oragono/*.pem
 # rehash oragono, which will reload the certificates:
 systemctl reload oragono.service
 ````
@@ -219,9 +220,9 @@ Oragono supports several different modes of operation with respect to accounts a
 
 ### Traditional / lenient mode
 
-This is the default mode, and makes Oragono's services act similar to Quakenet's Q bot. In this mode, users cannot own or reserve nicknames. In other words, there is no connection between account names and nicknames. Anyone can use any nickname (as long as it's not already in use by another running client). However, accounts are still useful: they can be used to register channels (see below), and some IRCv3-capable clients (with the `account-tag` or `extended-join` capabilities) may be able to take advantage of them.
+This makes Oragono's services act similar to Quakenet's Q bot. In this mode, users cannot own or reserve nicknames. In other words, there is no connection between account names and nicknames. Anyone can use any nickname (as long as it's not already in use by another running client). However, accounts are still useful: they can be used to register channels (see below), and some IRCv3-capable clients (with the `account-tag` or `extended-join` capabilities) may be able to take advantage of them.
 
-To enable this mode, set the following configs (this is the default mode):
+To enable this mode, set the following configs:
 
 * `accounts.registration.enabled = true`
 * `accounts.authentication-enabled = true`
@@ -229,22 +230,17 @@ To enable this mode, set the following configs (this is the default mode):
 
 ### Nick ownership
 
-This mode makes Oragono's services act like those of a typical IRC network (like Freenode). In this mode, registering an account gives you privileges over the use of that account as a nickname. The server will then help you to enforce control over your nickname(s):
-
-* You can proactively prevent anyone from using your nickname, unless they're already logged into your account
-* Alternately, you can give clients a grace period to log into your account, but if they don't and the grace period expires, the server will change their nickname to something else
-* Alternately, you can forego any proactive enforcement – but if you decide you want to reclaim your nickname from a squatter, you can `/msg Nickserv ghost stolen_nickname` and they'll be disconnected
-* You can associate additional nicknames with your account by changing to it and then issuing `/msg NickServ group`
+In this mode (the default), registering an account gives you privileges over the use of that account as a nickname. The server will then help you to enforce control over your nickname(s). No one will be able to use your nickname unless they are logged into your account.
 
 To enable this mode, set the following configs:
 
 * `accounts.registration.enabled = true`
 * `accounts.authentication-enabled = true`
 * `accounts.nick-reservation.enabled = true`
+* `accounts.nick-reservation.method = strict`
 
 The following additional configs may be of interest:
 
-* `accounts.nick-reservation.method = strict` ; we currently recommend strict nickname enforcement as the default, since we've found that users find it less confusing.
 * `accounts.nick-reservation.force-nick-equals-account = true` ; this allows nicknames to be treated as account names for most purposes, including for controlling access to channels (see the discussion of private channels below)
 
 ### SASL-only mode
@@ -259,12 +255,29 @@ To enable this mode, set the following configs:
 * `accounts.authentication-enabled = true`
 * `accounts.require-sasl.enabled = true`
 * `accounts.nick-reservation.enabled = true`
-
-Additionally, the following configs are recommended:
-
 * `accounts.nick-reservation.method = strict`
 * `accounts.nick-reservation.force-nick-equals-account = true`
 
+### Email verification
+
+By default, account registrations complete immediately and do not require a verification step. However, like other service frameworks, Oragono's NickServ can be configured to require email verification of registrations. The main challenge here is to prevent your emails from being marked as spam, which you can do by configuring [SPF](https://en.wikipedia.org/wiki/Sender_Policy_Framework), [DKIM](https://en.wikipedia.org/wiki/DomainKeys_Identified_Mail), and [DMARC](https://en.wikipedia.org/wiki/DMARC). For example, this configuration (when added to the `accounts.registration` section) enables email verification, with the emails being signed with a DKIM key and sent directly from Oragono:
+
+```yaml
+        enabled-callbacks:
+            - mailto
+
+        callbacks:
+            mailto:
+                sender: "admin@my.network"
+                require-tls: true
+                dkim:
+                    domain: "my.network"
+                    selector: "20200525"
+                    key-file: "dkim-private-20200525.pem"
+```
+
+You must create the corresponding TXT record `20200525._domainkey.my.network` to hold your public key. You can also use an MTA ("relay" or "smarthost") to send the email, in which case DKIM signing can be deferred to the MTA; see the example config for details.
+
 
 ## Channel Registration
 
@@ -318,7 +331,7 @@ Our language and translation functionality is very early, so feel free to let us
 
 Traditionally, every connection to an IRC server is separate must use a different nickname. [Bouncers](https://en.wikipedia.org/wiki/BNC_%28software%29#IRC) are used to work around this, by letting multiple clients connect to a single nickname. With Oragono, if the server is configured to allow it, multiple clients can share a single nickname without needing a bouncer. To use this feature, both connections must authenticate with SASL to the same user account and then use the same nickname during connection registration (while connecting to the server) – once you've logged-in, you can't share another nickname.
 
-To enable this functionality, set `accounts.multiclient.enabled` to `true`. Setting `accounts.multiclient.allowed-by-default` to `true` will allow this for everyone. If `allowed-by-default` is `false` (but `enabled` is still `true`), users can opt in to shared connections using `/msg NickServ SET multiclient on`.
+To enable this functionality, set `accounts.multiclient.enabled` to `true`. Setting `accounts.multiclient.allowed-by-default` to `true` will allow this for everyone. If `allowed-by-default` is `false` (but `enabled` is still `true`), users can opt in to shared connections using `/msg NickServ SET multiclient true`.
 
 You can see a list of your active sessions and their idle times with `/msg NickServ sessions` (network operators can use `/msg NickServ sessions nickname` to see another user's sessions).
 
@@ -428,8 +441,8 @@ Many clients do not have this support. However, you can designate port 6667 as a
 
         ":6697":
             tls:
-                key: tls.key
-                cert: tls.crt
+                cert: fullchain.pem
+                key: privkey.pem
 
     sts:
         enabled: true
@@ -490,9 +503,9 @@ To unset this mode and let anyone speak to you:
 
     /mode dan -R
 
-### +s - Server Notice Masks
+### +s - Server Notice Masks ("snomasks")
 
-This is a special 'list mode'. If you're an IRC operator, this mode lets you see special server notices that get sent out. See the Server Notice Masks section for more information on this mode.
+This is a special 'list mode'. If you're an IRC operator, this mode lets you see special server notices that get sent out. See `/helpop snomasks` (as an operator) for more information on this mode.
 
 ### +Z - TLS
 

irc/config.go

@@ -927,6 +927,10 @@ func LoadConfig(filename string) (config *Config, err error) {
 		config.Accounts.Multiclient.AllowedByDefault = true
 	}
 
+	if config.Accounts.NickReservation.ForceNickEqualsAccount && !config.Accounts.Multiclient.Enabled {
+		return nil, errors.New("force-nick-equals-account requires enabling multiclient as well")
+	}
+
 	// handle guest format, including the legacy key rename-prefix
 	if config.Accounts.NickReservation.GuestFormat == "" {
 		renamePrefix := config.Accounts.NickReservation.RenamePrefix

irc/help.go

@@ -83,6 +83,7 @@ Oragono supports the following server notice masks for operators:
   t  |  Local /STATS usage.
   u  |  Local client account actions.
   x  |  Local X-lines (DLINE/KLINE/etc).
+  v  |  Local vhost changes.
 
 To set a snomask, do this with your nickname: