Merge pull request #1573 from slingamn/faq

update the FAQ to cover some controversial issues

docs/MANUAL.md

@@ -26,7 +26,8 @@ _Copyright © Daniel Oaks <daniel@danieloaks.net>, Shivaram Lingamneni <slingamn
     - [Becoming an operator](#becoming-an-operator)
     - [Rehashing](#rehashing)
     - [Environment variables](#environment-variables)
-    - [Productionizing](#productionizing)
+    - [Productionizing with systemd](#productionizing-with-systemd)
+    - [Using valid TLS certificates](#using-valid-tls-certificates)
     - [Upgrading to a new version of Oragono](#upgrading-to-a-new-version-of-oragono)
 - [Features](#features)
     - [User Accounts](#user-accounts)
@@ -174,7 +175,7 @@ Oragono can also be configured using environment variables, using the following
 However, settings that were overridden using this technique cannot be rehashed --- changing them will require restarting the server.
 
 
-## Productionizing
+## Productionizing with systemd
 
 The recommended way to operate oragono as a service on Linux is via systemd. This provides a standard interface for starting, stopping, and rehashing (via `systemctl reload`) the service. It also captures oragono's loglines (sent to stderr in the default configuration) and writes them to the system journal.
 
@@ -189,6 +190,12 @@ The only major distribution that currently packages Oragono is Arch Linux; the a
     1. `systemctl start oragono.service`
     1. Confirm that the service started correctly with `systemctl status oragono.service`
 
+
+On a non-systemd system, oragono can be configured to log to a file and used [logrotate(8)](https://linux.die.net/man/8/logrotate), since it will reopen its log files (as well as rehashing the config file) upon receiving a SIGHUP. To rehash manually outside the context of log rotation, you can use `killall -HUP oragono` or `pkill -HUP oragono`.
+
+
+## Using valid TLS certificates
+
 The other major hurdle for productionizing (but one well worth the effort) is obtaining valid TLS certificates for your domain, if you haven't already done so:
 
 1. The simplest way to get valid TLS certificates is from [Let's Encrypt](https://letsencrypt.org/) with [Certbot](https://certbot.eff.org/). The correct procedure will depend on whether you are already running a web server on port 80. If you are, follow the guides on the Certbot website; if you aren't, you can use `certbot certonly --standalone --preferred-challenges http -d example.com` (replace `example.com` with your domain).
@@ -211,8 +218,6 @@ Executing this script manually will install the certificates for the first time
 
 If you are using Certbot 0.29.0 or higher, you can also change the ownership of the files under `/etc/letsencrypt` so that the oragono user can read them, as described in the [UnrealIRCd documentation](https://www.unrealircd.org/docs/Setting_up_certbot_for_use_with_UnrealIRCd#Tweaking_permissions_on_the_key_file).
 
-On a non-systemd system, oragono can be configured to log to a file and used [logrotate(8)](https://linux.die.net/man/8/logrotate), since it will reopen its log files (as well as rehashing the config file) upon receiving a SIGHUP. To rehash manually outside the context of log rotation, you can use `killall -HUP oragono` or `pkill -HUP oragono`.
-
 
 ## Upgrading to a new version of Oragono
 
@@ -473,10 +478,8 @@ For channel operators, `/msg ChanServ HOWTOBAN #channel nickname` will provide s
 
 # Frequently Asked Questions
 
-Some troubleshooting, some general questions about the project! This should help answer any sorta queries you have.
 
-
+## How do I submit a suggestion?
-## I have a suggestion
 
 Awesome! We love getting new suggestions for features, ways to improve the server and the tooling around it, everything.
 
@@ -499,6 +502,30 @@ The config file accepts hashed passwords, not plaintext passwords. You must run
 After that, you must rehash or restart Oragono to apply the config change. If a rehash didn't accomplish the desired effects, you might want to try a restart instead.
 
 
+## Why is Oragono ignoring my ident response / USER command?
+
+The default/recommended configuration of Oragono does not query remote ident servers, and furthermore ignores any user/ident sent with the `USER` command. All user/ident fields are set to a constant `~u`. There are a few reasons for this:
+
+1. Remote ident lookups slow down connection initiation and pose privacy and security concerns (since they transmit usernames over the Internet in plaintext).
+2. Ignoring user/ident simplifies bans; in general, a channel ban in Oragono should target either the nickname or the hostname. As a channel operator, `/msg ChanServ HOWTOBAN #channel nick` will recommend a way of banning any given user.
+3. Ident is commonly used to distinguish users connecting from the same trusted shell host or shared bouncer. This is less important with Oragono, which can act as a bouncer itself.
+4. Because of limitations of the IRC protocol, every character of the user/ident field counts against the maximum size of a message that can be sent.
+
+As an operator, you can modify this behavior if desired; see the `check-ident` and `coerce-ident` settings in the config file.
+
+
+## Why can't I change nicknames?
+
+The default/recommended configuration of Oragono does not allow authenticated users to change their nicknames; an authenticated user must use their account name as their nickname. There are a few reasons for this:
+
+1. Assigning a consistent nickname prevents certain "split-brain" scenarios that break Oragono's "multiclient" functionality. In brief, if two clients are connecting to the same account/identity, but only one of them issues a `/NICK` command, and then one of them subsequently loses and regains its connection to the server, they "break apart": they will have separate identities and channel memberships on the network, and it's difficult to bring them back together again.
+2. The use of a consistent nickname reduces the possibility of edge cases in history playback.
+3. The use of a consistent nickname simplifies offline messaging (which is a first-class concept for always-on clients).
+4. Oragono eliminates the cases in conventional IRC servers that necessitate nickname changes. In particular, you can always claim your nickname, even if the server is still waiting for an old client to time out, and you can connect arbitrarily many clients to the same nickname.
+
+As an operator, you can disable this behavior using the `force-nick-equals-account` setting, but this is discouraged because it has no effect on always-on clients; always-on clients must use their account names as their nicknames regardless of this setting.
+
+
 ## How do I make a private channel?
 
 We recommend that server administrators set the following recommended defaults: