Merge pull request #1689 from slingamn/notice

add a FAQ entry for global notices

README.md

@@ -41,6 +41,11 @@ If you want to take a look at a running Ergo instance or test some client code,
 * [IRCv3 support](https://ircv3.net/software/servers.html)
 * a focus on developing with [specifications](https://ergo.chat/specs.html)
 
+For more detailed information on Ergo's functionality, see:
+
+* [MANUAL.md, the operator manual](https://github.com/ergochat/ergo/blob/stable/docs/MANUAL.md)
+* [USERGUIDE.md, the guide for end users](https://github.com/ergochat/ergo/blob/stable/docs/USERGUIDE.md)
+
 ## Quick start guide
 
 Download the latest release from this page: https://github.com/ergochat/ergo/releases/latest
@@ -54,7 +59,7 @@ ergo mkcerts
 ergo run     # server should be ready to go!
 ```
 
-**Note:** See the [productionizing guide in our manual](https://github.com/ergochat/ergo/blob/master/docs/MANUAL.md#productionizing-with-systemd) for recommendations on how to run a production network, including obtaining valid TLS certificates.
+**Note:** See the [productionizing guide in our manual](https://github.com/ergochat/ergo/blob/stable/docs/MANUAL.md#productionizing-with-systemd) for recommendations on how to run a production network, including obtaining valid TLS certificates.
 
 ### Platform Packages
 
@@ -76,7 +81,7 @@ You can also install this repo and use that instead! However, keep some things i
 
 The `master` branch _should_ usually be stable, but may contain database changes that either have not been finalised or not had database upgrade code written yet. Don't run `master` on a live production network.
 
-The `stable` branch contains the latest release. You can run this for a production version without any trouble.
+The `stable` branch contains the latest release, suitable for use in production.
 
 #### Building
 
@@ -104,7 +109,7 @@ With this, you receive a blob of text which you can plug into your configuration
 
 ### Nickname and channel registration
 
-Ergo relies heavily on user accounts to enable its distinctive features (such as allowing multiple clients per nickname). As a user, you can register your current nickname as an account using `/msg NickServ register <password>`. Once you have done so, you should [enable SASL in your clients](https://freenode.net/kb/answer/sasl), ensuring that you will be automatically logged into your account on each connection. This will prevent [problems claiming your registered nickname](https://github.com/ergochat/ergo/blob/master/docs/MANUAL.md#nick-equals-account).
+Ergo relies heavily on user accounts to enable its distinctive features (such as allowing multiple clients per nickname). As a user, you can register your current nickname as an account using `/msg NickServ register <password>`. Once you have done so, you should [enable SASL in your clients](https://libera.chat/guides/sasl), ensuring that you will be automatically logged into your account on each connection. This will prevent [problems claiming your registered nickname](https://github.com/ergochat/ergo/blob/master/docs/MANUAL.md#nick-equals-account).
 
 Once you have registered your nickname, you can use it to register channels:
 

docs/MANUAL.md

@@ -191,7 +191,7 @@ The only major distribution that currently packages Ergo is Arch Linux; the afor
     1. Confirm that the service started correctly with `systemctl status ergo.service`
 
 
-On a non-systemd system, ergo 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 ergo` or `pkill -HUP ergo`.
+On a non-systemd system, ergo 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 ergo` or `pkill -HUP ergo`. See [distrib/init](https://github.com/ergochat/ergo/tree/master/distrib/init) for init scripts and related tools for non-systemd systems.
 
 
 ## Using valid TLS certificates
@@ -257,7 +257,7 @@ If you want to use a TLS client certificate instead of a password to authenticat
 
     /NS REGISTER *
 
-Once you've registered, you'll need to set up SASL to login. One of the more complete SASL instruction pages is Freenode's page [here](https://freenode.net/kb/answer/sasl). Open up that page, find your IRC client and then setup SASL with your chosen username and password!
+Once you've registered, you'll need to set up SASL to login. One of the more complete SASL instruction pages is libera.chat's page [here](https://libera.chat/guides/sasl). Open up that page, find your IRC client and then setup SASL with your chosen username and password!
 
 If your client doesn't support SASL, you can typically use the "server password" (`PASS`) field in your client to log into your account automatically when connecting. Set the server password to `accountname:accountpassword`, where `accountname` is your account name and `accountpassword` is your account password.
 
@@ -273,7 +273,7 @@ In this mode (the default), registering an account gives you privileges over the
 1. You must use your nickname, i.e., if you are logged into your account, then the server will require you to use your account name as your nickname
 1. If you unregister your account, your nickname will be permanently unreclaimable (thus preventing people from impersonating you)
 
-In this mode, it is very important that end users authenticate to their accounts as part of the initial IRC handshake (traditionally referred to as "connection registration"); otherwise they will not be able to use their registered nicknames. The preferred mechanism for this is [SASL](https://freenode.net/kb/answer/sasl), which is supported by most modern clients. As a fallback, this can also be done via the `PASS` (server password) command; set the "server password" field of the client to `AzureDiamond:hunter2`, where `AzureDiamond` is the account name and `hunter2` is the account password.
+In this mode, it is very important that end users authenticate to their accounts as part of the initial IRC handshake (traditionally referred to as "connection registration"); otherwise they will not be able to use their registered nicknames. The preferred mechanism for this is [SASL](https://libera.chat/guides/sasl), which is supported by most modern clients. As a fallback, this can also be done via the `PASS` (server password) command; set the "server password" field of the client to `AzureDiamond:hunter2`, where `AzureDiamond` is the account name and `hunter2` is the account password.
 
 As an end user, if you want to change your nickname, you can register a new account and transfer any channel ownerships to it using `/msg ChanServ transfer`.
 
@@ -336,7 +336,9 @@ By default, account registrations complete immediately and do not require a veri
                 key-file: "dkim.pem"
 ```
 
-You must create the corresponding TXT record `20200229._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.
+You must create the corresponding TXT record `20200229._domainkey.my.network` to hold your public key.
+
+You can also use an external SMTP server ("MTA", "relay", or "smarthost") to send the email, in which case DKIM signing can be deferred to that server; see the `mta` section of the example config for details.
 
 
 ## Channel Registration
@@ -544,6 +546,12 @@ Under these circumstances, users can follow the following steps:
 
 Similarly, for a public channel (one without `+i`), users can ban nick/account names with `/mode #example +b bob`. (To restrict the channel to users with valid accounts, set it to registered-only with `/mode #example +R`.)
 
+
+## How do I send an announcement to all connected users?
+
+Ergo supports a simplified form of the "global notice" or "wallops" capabilities found in other ircds. With the `massmessage` operator capability, you can `/NOTICE $$* text of your announcement`, and it will be sent to all connected users. If you have human-readable hostnames enabled (in the default/recommended configuration they are not), you can also `/NOTICE $#wild*card.host.name`.
+
+
 -------------------------------------------------------------------------------------------
 
 

docs/USERGUIDE.md

@@ -72,7 +72,7 @@ Although (as in other IRC systems) basic chat functionality is available without
 
 This registers your current nickname as your account name, with the password `mySecretPassword` (replace this with your own secret password!)
 
-Once you have registered your account, you must configure SASL in your client, so that you will be logged in automatically on each connection. [Freenode's SASL guide](https://freenode.net/kb/answer/sasl) covers most popular clients.
+Once you have registered your account, you must configure SASL in your client, so that you will be logged in automatically on each connection. [libera.chat's SASL guide](https://libera.chat/guides/sasl) covers most popular clients.
 
 If your client doesn't support SASL, you can typically use the "server password" (`PASS`) field in your client to log into your account automatically when connecting. Set the server password to `accountname:accountpassword`, where `accountname` is your account name and `accountpassword` is your account password.