From 725bb7213d26c040a0b76d3d793bc09c58eea6b0 Mon Sep 17 00:00:00 2001 From: Shivaram Lingamneni Date: Sun, 13 Jun 2021 13:50:58 -0400 Subject: [PATCH 1/5] add a FAQ entry for global notices --- docs/MANUAL.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/MANUAL.md b/docs/MANUAL.md index 122aeb4d..d570ba66 100644 --- a/docs/MANUAL.md +++ b/docs/MANUAL.md @@ -544,6 +544,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`. + + ------------------------------------------------------------------------------------------- From 2f5484a6736cbfd07a1b096c85253db2864c65f0 Mon Sep 17 00:00:00 2001 From: Shivaram Lingamneni Date: Sun, 13 Jun 2021 14:15:03 -0400 Subject: [PATCH 2/5] clarify mta configuration in manual --- docs/MANUAL.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/MANUAL.md b/docs/MANUAL.md index d570ba66..4d7c29ba 100644 --- a/docs/MANUAL.md +++ b/docs/MANUAL.md @@ -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 From c53097000bbfd7fad7f2f369cf3293309045e68a Mon Sep 17 00:00:00 2001 From: Shivaram Lingamneni Date: Sun, 13 Jun 2021 15:57:26 -0400 Subject: [PATCH 3/5] fix remaining references to Freenode in documentation --- README.md | 2 +- docs/MANUAL.md | 4 ++-- docs/USERGUIDE.md | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 91124090..eb9e714d 100644 --- a/README.md +++ b/README.md @@ -104,7 +104,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 `. 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 `. 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: diff --git a/docs/MANUAL.md b/docs/MANUAL.md index 4d7c29ba..d0828df3 100644 --- a/docs/MANUAL.md +++ b/docs/MANUAL.md @@ -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`. diff --git a/docs/USERGUIDE.md b/docs/USERGUIDE.md index e09f901a..75a03ddf 100644 --- a/docs/USERGUIDE.md +++ b/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. From 29982e3ffe0f92ea4861695ce4e9da9071621bc1 Mon Sep 17 00:00:00 2001 From: Shivaram Lingamneni Date: Tue, 15 Jun 2021 14:21:27 -0400 Subject: [PATCH 4/5] mention new init script in manual --- docs/MANUAL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/MANUAL.md b/docs/MANUAL.md index d0828df3..82cb04b8 100644 --- a/docs/MANUAL.md +++ b/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 From ece82b44fb9ecdc74ca44b8b2821eccaa83a1fed Mon Sep 17 00:00:00 2001 From: Shivaram Lingamneni Date: Tue, 15 Jun 2021 19:45:29 -0400 Subject: [PATCH 5/5] add links in README.md to manual/userguide --- README.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index eb9e714d..61c02d44 100644 --- a/README.md +++ b/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