final documentation updates for 2.5.0

.goreleaser.yml

@@ -48,6 +48,7 @@ archives:
       - default.yaml
       - traditional.yaml
       - docs/MANUAL.md
+      - docs/USERGUIDE.md
       - languages/*.yaml
       - languages/*.json
       - languages/*.md

CHANGELOG.md

@@ -1,9 +1,9 @@
 # Changelog
 All notable changes to Oragono will be documented in this file.
 
-## [2.5.0-rc1] - 2021-01-24
+## [2.5.0] - 2021-01-31
 
-We're pleased to be publishing the release candidate for 2.5.0 (the official release should follow in a week or so).
+We're pleased to announce Oragono 2.5.0, a new stable release.
 
 This release includes enhancements based on the needs of real-world operators, as well as bug fixes. Highlights include:
 

README

@@ -7,14 +7,19 @@
 
 -----------------------------------------------------------------------------------------------
 
-Oragono is a modern IRC server written in Go. It's designed to be simple to setup
+Oragono is a modern IRC server written in Go. Its core design principles are:
-and use, and to provide the majority of features that IRC users expect today.
 
-It includes features such as UTF-8 nicks and channel names, client accounts and SASL, and other
+* Being simple to set up and use
-assorted IRCv3 support.
+* Combining the features of an ircd, a services framework, and a bouncer:
+  * Integrated account management
+  * History storage
+  * Bouncer functionality
+* Bleeding-edge IRCv3 support
+* Highly customizable via a rehashable (runtime-reloadable) YAML config
 
                                      https://oragono.io/
                               https://github.com/oragono/oragono
+                                     #oragono on Freenode
 
 -----------------------------------------------------------------------------------------------
 
@@ -25,33 +30,30 @@ Copy the example config file to ircd.yaml with a command like:
 
     $ cp default.yaml ircd.yaml
 
-Modify the config file as you like.
+Modify the config file as needed (the recommendations at the top may be helpful).
 
 To generate passwords for opers and connect passwords, you can use this command:
 
     $ oragono genpasswd
 
-Run these commands in order -- these will setup each section of the server:
+If you need to generate self-signed TLS certificates, use this command:
 
     $ oragono mkcerts
+
+You are now ready to start Oragono!
+
     $ oragono run
 
-And you should now be running Oragono!
+For further instructions, consult the manual. A copy of the manual should be
-
+included in your release under `docs/MANUAL.md`. Or you can view it on the
+Web: https://oragono.io/manual.html
 
 === Updating ===
 
-If you're updating from a previous version of Oragono, checkout the CHANGELOG for a shortlist
+If you're updating from a previous version of Oragono, check out the CHANGELOG for a list
 of important changes you'll want to take a look at. The change log details config changes,
 fixes, new features and anything else you'll want to be aware of!
 
-If there's been a database update, you can run this command to upgrade it manually:
-
-    $ oragono upgradedb
-
-Otherwise, just starting the server will run an automagic backup and upgrade.
-
-
 === Credits ===
 
 * Jeremy Latt (2012-2014)

README.md

@@ -38,7 +38,7 @@ If you want to take a look at a running Oragono instance or test some client cod
 * ident lookups for usernames
 * automated client connection limits
 * passwords stored with [bcrypt](https://godoc.org/golang.org/x/crypto)
-* banning ips/nets and masks with `KLINE` and `DLINE`
+* `UBAN`, a unified ban system that can target IPs, networks, masks, and registered accounts (`KLINE` and `DLINE` are also supported)
 * [IRCv3 support](https://ircv3.net/software/servers.html)
 * a focus on developing with [specifications](https://oragono.io/specs.html)
 

docs/MANUAL.md

@@ -252,7 +252,9 @@ 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 setup SASL to login (or use NickServ IDENTIFY). 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 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!
+
+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.
 
 ## Account/Nick Modes
 
@@ -397,7 +399,7 @@ Oragono supports two methods of storing history, an in-memory buffer with a conf
 
 Unfortunately, client support for history playback is still patchy. In descending order of support:
 
-1. The [IRCv3 chathistory specification](https://github.com/ircv3/ircv3-specifications/pull/393/) offers the most fine-grained control over history replay. It is supported by [Kiwi IRC](https://github.com/kiwiirc/kiwiirc), and hopefully other clients soon.
+1. The [IRCv3 chathistory specification](https://ircv3.net/specs/extensions/chathistory) offers the most fine-grained control over history replay. It is supported by [Kiwi IRC](https://github.com/kiwiirc/kiwiirc), and hopefully other clients soon.
 1. We emulate the [ZNC playback module](https://wiki.znc.in/Playback) for clients that support it. You may need to enable support for it explicitly in your client (see the "ZNC" section below).
 1. If you set your client to always-on (see the previous section for details), you can set a "device ID" for each device you use. Oragono will then remember the last time your device was present on the server, and each time you sign on, it will attempt to replay exactly those messages you missed. There are a few ways to set your device ID when connecting:
     - You can add it to your SASL username with an `@`, e.g., if your SASL username is `alice` you can send `alice@phone`
@@ -445,7 +447,12 @@ Setting `server.ip-cloaking.num-bits` to 0 gives users cloaks that don't depend
 
 ## Moderation
 
-Oragono's multiclient and always-on features mean that moderation (at the server operator level) requires different techniques than a traditional IRC network. Server operators have two principal tools for moderation:
+Oragono shares some server operator moderation tools with other ircds. In particular:
+
+1. `/SAMODE` can be used to grant or remove channel privileges. For example, to create an operator in a channel that has no operators: `/SAMODE #channel +o nickname`
+2. `/SAJOIN` lets operators join channels despite restrictions, or forcibly join another user to a channel. For example, `/SAJOIN #channel` or `/SAJOIN nickname #channel`.
+
+However, Oragono's multiclient and always-on features mean that abuse prevention (at the server operator level) requires different techniques than a traditional IRC network. Server operators have two principal tools for abuse prevention:
 
 1. `/UBAN`, which can disable user accounts and/or ban offending IPs and networks
 2. `/DEFCON`, which can impose emergency restrictions on user activity in response to attacks
@@ -481,21 +488,16 @@ There are two ways to make suggestions, either:
 
 ## Why can't I oper?
 
-If you try to oper unsuccessfully, Oragono will disconnect you from the network. Here's some important things to try if you find yourself unable to oper:
+If you try to oper unsuccessfully, Oragono will disconnect you from the network. If you're unable to oper, here are some things to double-check:
 
-1. Have you generated the config-file password blob with `oragono genpasswd`?
+1. Did you correctly generate the hashed password with `oragono genpasswd`?
-2. Have you restarted Oragono to make sure the new password has taken effect?
+1. Did you add the password hash to the correct config file, then save the file?
-3. If all else fails, can you get raw protocol output from Oragono for evaluation?
+1. Did you rehash or restart Oragono after saving the file?
 
-So, first off you'll want to make sure you've stored the password correctly. In the config file, all passwords are bcrypted. Basically, you run `oragono genpasswd`, type your actual password in, and then receive a config file blob back. Put that blob into the config file, and then use the actual password in your IRC client.
+The config file accepts hashed passwords, not plaintext passwords. You must run `oragono genpasswd`, type your actual password in, and then receive a hashed blob back (it will look like `$2a$04$GvCFlShLZQjId3dARzwOWu9Nvq6lndXINw2Sdm6mUcwxhtx1U/hIm`). Enter that into the relevant `opers` block in your config file, then save the file.
 
-After that, try restarting Oragono to see if that improves things. Even if you've already done so or already rehashed, a proper restart can sometimes help things. Make sure your config file is saved before restarting the server.
+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.
 
-If both of those have failed, it might be worth getting us to look at the raw lines and see what's up.
-
-If you're familiar with getting this output through your client (e.g. in weechat it's `/server raw`) then you can do so that way, or use [ircdog](https://github.com/goshuirc/ircdog).
-
-Otherwise, in the Oragono config file, you'll want to enable raw line logging by removing `-userinput -useroutput` under the `logging` section. Once you start up your server, connect, fail to oper and get disconnected, you'll see a bunch of input/output lines in Ora's log file. Remove your password from those logs and pass them our way.
 
 ## How do I make a private channel?
 
@@ -504,7 +506,7 @@ We recommend that server administrators set the following recommended defaults:
 1. `nick-reservation-method: strict`
 1. `force-nick-equals-account: true`
 
-These settings imply that any registered account name can be treated as synonymous with a nickname; anyone using the nickname is necessarily logged into the account, and anyone logged intot he account is necessarily using the nickname.
+These settings imply that any registered account name can be treated as synonymous with a nickname; anyone using the nickname is necessarily logged into the account, and anyone logged into the account is necessarily using the nickname.
 
 Under these circumstances, users can follow the following steps:
 

docs/USERGUIDE.md

@@ -0,0 +1,117 @@
+
+          ▄▄▄   ▄▄▄·  ▄▄ •        ▐ ▄       
+    ▪     ▀▄ █·▐█ ▀█ ▐█ ▀ ▪▪     •█▌▐█▪     
+     ▄█▀▄ ▐▀▀▄ ▄█▀▀█ ▄█ ▀█▄ ▄█▀▄▪▐█▐▐▌ ▄█▀▄ 
+    ▐█▌.▐▌▐█•█▌▐█ ▪▐▌▐█▄▪▐█▐█▌ ▐▌██▐█▌▐█▌.▐▌
+     ▀█▄▀▪.▀  ▀ ▀  ▀ ·▀▀▀▀  ▀█▄▀ ▀▀ █▪ ▀█▄▀▪
+
+            Oragono IRCd User Guide
+              https://oragono.io/
+
+_Copyright © Daniel Oaks <daniel@danieloaks.net>, Shivaram Lingamneni <slingamn@cs.stanford.edu>_
+
+
+--------------------------------------------------------------------------------------------
+
+
+ Table of Contents
+
+- [Introduction](#introduction)
+- [About IRC](#about-irc)
+- [How Oragono is different](#how-oragono-is-different)
+- [Account registration](#account-registration)
+- [Channel registration](#channel-registration)
+- [Always-on](#always-on)
+- [History](#history)
+
+--------------------------------------------------------------------------------------------
+
+
+# Introduction
+
+Welcome to Oragono, a modern IRC server!
+
+This guide is for end users of Oragono (people using Oragono to chat). If you're installing your own Oragono instance, you should consult the official manual instead (a copy should be bundled with your release, in the `docs/` directory).
+
+This guide assumes that Oragono is in its default or recommended configuration; Oragono server administrators can change settings to make the server behave differently. If something isn't working as expected, ask your server administrator for help.
+
+# About IRC
+
+Before continuing, you should be familiar with basic features of the IRC platform. If you're comfortable with IRC, you can skip this section.
+
+[IRC](https://en.wikipedia.org/wiki/Internet_Relay_Chat) is a chat platform invented in 1988, which makes it older than the World Wide Web! At its most basic level, IRC is a chat system composed of chat rooms; these are called "channels" and their names begin with a `#` character (this is actually the origin of the [hashtag](https://www.cmu.edu/homepage/computing/2014/summer/originstory.shtml)!). As a user, you "join" the channels you're interested in, enabling you to participate in those discussions.
+
+Here are some guides covering the basics of IRC:
+
+* [Fedora Magazine: Beginner's Guide to IRC](https://fedoramagazine.org/beginners-guide-irc/)
+* [IRCHelp's IRC Tutorial](https://www.irchelp.org/faq/irctutorial.html) (in particular, section 3, "Beyond the Basics")
+
+# How Oragono is different
+
+Oragono differs in many ways from conventional IRC servers. If you're *not* familiar with other IRC servers, you may want to skip this section. Here are some of the most salient differences:
+
+* Oragono integrates a "bouncer" into the server. In particular:
+    * Oragono stores message history for later retrieval.
+    * You can be "present" on the server (joined to channels, able to receive DMs) without having an active client connection to the server.
+    * Conversely, you can use multiple clients to view / control the same presence (nickname) on the server, as long as you authenticate with SASL when connecting.
+* Oragono integrates "services" into the server.  In particular:
+    * Nicknames are strictly reserved: once you've registered your nickname, you must log in in order to use it. Consequently, SASL is more important when using Oragono than in other systems.
+    * All properties of registered channels are protected without the need for `ChanServ` to be joined to the channel.
+* Oragono "cloaks", i.e., cryptographically scrambles, end user IPs so that they are not displayed publicly.
+* By default, the user/ident field is inoperative in Oragono: it is always set to `~u`, regardless of the `USER` command or the client's support for identd. This is because it is not in general a reliable or trustworthy way to distinguish users coming from the same IP. Oragono's integrated bouncer features should reduce the need for shared shell hosts and hosted bouncers (one of the main remaining use cases for identd).
+* By default, Oragono is only accessible via TLS.
+
+# Account registration
+
+Although (as in other IRC systems) basic chat functionality is available without creating an account, most of Oragono's features require an account. You can create an account by sending a direct message to `NickServ`. (In IRC jargon, `NickServ` is a "network service", but if you're not familiar with the concept you can just think of it as a bot or a text user interface.) In a typical client, this will be:
+
+```
+/msg NickServ register mySecretPassword validEmailAddress@example.com
+```
+
+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.
+
+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.
+
+# Channel registration
+
+Once you've registered your nickname, you can use it to register channels. By default, channels are ephemeral; they go away when there are no longer any users in the channel, or when the server is restarted. Registering a channel gives you permanent control over it, and ensures that its settings will persist. To register a channel, send a message to `ChanServ`:
+
+```
+/msg ChanServ register #myChannel
+```
+
+You must already be an operator (have the `+o` channel mode --- your client may display this as an `@` next to your nickname). If you're not a channel operator in the channel you want to register, ask your server administrator for help.
+
+# Always-on
+
+By default, if you lose your connection to the IRC server, you are no longer present on the server; other users will see that you have "quit", you will no longer appear in channel lists, and you will not be able to receive direct messages. Oragono supports "always-on clients", where you remain on the server even when you are disconnected. To enable this, you can send a message to `NickServ`:
+
+```
+/msg NickServ set always-on true
+```
+
+# History
+
+Oragono stores message history on the server side (typically not an unlimited amount --- consult your server's FAQ, or your server administrator, to find out how much is being stored and how long it's being retained).
+
+1. The [IRCv3 chathistory specification](https://ircv3.net/specs/extensions/chathistory) offers the most fine-grained control over history replay. It is supported by [Kiwi IRC](https://github.com/kiwiirc/kiwiirc), and hopefully other clients soon.
+1. We emulate the [ZNC playback module](https://wiki.znc.in/Playback) for clients that support it. You may need to enable support for it explicitly in your client. For example, in [Textual](https://www.codeux.com/textual/), go to "Server properties", select "Vendor specific", uncheck "Do not automatically join channels on connect", and check "Only play back messages you missed". ZNC's wiki page covers other common clients (although if the feature is only supported via a script or third-party extension, the following option may be easier).
+1. If you set your client to always-on (see the previous section for details), you can set a "device ID" for each device you use. Oragono will then remember the last time your device was present on the server, and each time you sign on, it will attempt to replay exactly those messages you missed. There are a few ways to set your device ID when connecting:
+    - You can add it to your SASL username with an `@`, e.g., if your SASL username is `alice` you can send `alice@phone`
+    - You can add it in a similar way to your IRC protocol username ("ident"), e.g., `alice@phone`
+    - If login to user accounts via the `PASS` command is enabled on the server, you can provide it there, e.g., by sending `alice@phone:hunter2` as the server password
+1. If you only have one device, you can set your client to be always-on and furthermore `/msg NickServ set autoreplay-missed true`. This will replay missed messages, with the caveat that you must be connecting with at most one client at a time.
+1. You can manually request history using `/history #channel 1h` (the parameter is either a message count or a time duration). (Depending on your client, you may need to use `/QUOTE history` instead.)
+1. You can autoreplay a fixed number of lines (e.g., 25) each time you join a channel using `/msg NickServ set autoreplay-lines 25`.
+
+# Private channels
+
+If you have registered a channel, you can make it private. The best way to do this is with the `+i` ("invite-only") mode:
+
+1. Set your channel to be invite-only (`/mode #example +i`)
+1. Identify the users you want to be able to access the channel. Ensure that they have registered their accounts (you should be able to see their registration status if you `/WHOIS` their nicknames).
+1. Add the desired nick/account names to the invite exception list (`/mode #example +I alice`)
+1. If you want to grant a persistent channel privilege to a user, you can do it with `CS AMODE` (`/msg ChanServ AMODE #example +o bob`)