documentation updates

.goreleaser.yml

@@ -47,7 +47,7 @@ archives:
       - oragono.motd
       - default.yaml
       - traditional.yaml
-      - docs/*
+      - docs/MANUAL.md
       - languages/*.yaml
       - languages/*.json
       - languages/*.md

DEVELOPING.md

@@ -1,6 +1,6 @@
 # Developing Oragono
 
-This is just a bunch of tips and tricks we keep in mind while developing Oragono. If you wanna help develop as well, they might also be worth keeping in mind!
+This is a guide to modifying Oragono's code. If you're just trying to run your own Oragono, or use one, you shouldn't need to worry about these issues.
 
 
 ## Golang issues

docs/INFO.md

@@ -1,92 +0,0 @@
-# Oragono Information
-
-Here's a bunch of misc info about the Oragono server! This can include questions, plans on
-how I'm going forward, how to properly use features, or why Oragono does/doesn't do
-something.
-
-Essentially, this document acts as a braindump about Oragono while we figure out a better
-place to put all this information.
-
-
-## Accounts and Channels
-
-Most IRC servers out there offer IRC account and channel registration through external
-services such as NickServ and ChanServ. In Oragono, we bundle accounts and channel ownership
-in as a native server feature instead!
-
-Because there's a lot of aspects of accounts/channels that haven't been specified as native
-commands and all yet, Oragono includes the pseudo-clients NickServ and ChanServ to roughly
-mimic the functionality that other IRCds get from services packages, in a user-facing set
-of commands that's familiar to everyone.
-
-The plan is to move more features and functionality (such as channel registration, channel
-permissions and all) over to native commands first and to use the NickServ/ChanServ as
-legacy interfaces to access these functions. However, it's gonna be a while before all of
-this is specified by someone like the IRCv3 WG.
-
-
-## PROXY
-
-The PROXY command, specified by [HAProxy's PROXY v1 specifications](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt),
-allows someone to setup HAProxy in front of Oragono. This allows them to use HAProxy for
-TLS negotiation (allowing older versions of SSL/TLS than Go's inbuilt TLS support does).
-However, it also allows them to update TLS certificates by updating them with HAProxy,
-rather than relying on our `REHASH` command (which is less-well-tested than I'd like
-right now).
-
-This is a toss-up of course – allowing older versions of TLS might be seen as undesired,
-and I wouldn't use the feature myself, but it's useful for real-world installations which
-is why it exists. The command is only allowed from specific hosts which should restrict it
-appropriately.
-
-
-## Server-to-Server Linking (or Federation)
-
-Right now Oragono doesn't support linking multiple servers together. It's certainly planned,
-but it's a fair while away.
-
-When I do add S2S linking to Oragono, I want to use it as a testbed for a new sort of
-linking protocol. Mostly, I want a meshy protocol that minimises the effects of netsplits
-while still ensuring that messages get delivered, and preserves the AP nature of IRC
-reliability (in terms of the CAP theorem), which is something that traditional solutions
-based on the Raft protocol don't do.
-
-Basically, I'm going to continue working on my [DCMI](https://github.com/DanielOaks/dcmi)
-protocol, get that to a point where I'm happy with it and _then_ start looking at S2S
-linking properly. If anyone is interested in server protocols and wants to look at this with
-me, please feel free to reach out!
-
-
-## Rehashing
-
-Rehashing is reloading the config files and TLS certificates. Of course, you can rehash the
-server by connect, opering-up and using the `/REHASH` command. However, similar to other
-IRCds, you can also make the server rehash by sending an appropriate signal to it!
-
-To make the server rehash from the command line, send it a `SIGHUP` signal. In *nix and OSX,
-you can do this by performing the following command:
-
-    killall -HUP oragono
-
-This will make the server rehash its configuration files and TLS certificates, and so can be
-useful if you're automatically updating your TLS certs!
-
-
-## Rejected Features
-
-'Rejected' sounds harsh, but basically these are features I've decided I'm not gonna
-implement in Oragono (at least, not until someone convinces me they're worth doing).
-
-### Force/Auto-Join Channels on Connect
-
-When a user connects, some IRC servers let you force-join them to a given channel. For
-instance, this could be a channel like `#coolnet` for a network named CoolNet, a lobby
-channel, or something similar.
-
-My main objection to having this feature is just that I don't like it that much. It doesn't
-seem nice to forcibly join clients to a channel, and I know I'm always annoyed when networks
-do it to me.
-
-To network operators that want to do this, I'd suggest instead mentioning the channel(s) in
-your MOTD so that your users know the channels exist! If they want to join in, they can do
-it from there :)

docs/MANUAL.md

@@ -142,6 +142,11 @@ If you're using Arch Linux, you can also install the [`oragono` package](https:/
 For further information and a sample docker-compose file see the separate [Docker documentation](https://github.com/oragono/oragono/blob/master/distrib/docker/README.md).
 
 
+## Building from source
+
+You'll need an [up-to-date distribution of the Go language for your OS and architecture](https://golang.org/dl/). Once you have that, just clone the repository and run `make build`. If everything goes well, you should now have an executable named `oragono` in the base directory of the project.
+
+
 ## Becoming an operator
 
 Many administrative actions on an IRC server are performed "in-band" as IRC commands sent from a client. The client in question must be an IRC operator ("oper", "ircop"). The easiest way to become an operator on your new Oragono instance is first to pick a strong, secure password, then "hash" it using the `oragono genpasswd` command (run `oragono genpasswd` from the command line, then enter your password twice), then copy the resulting hash into the `opers` section of your `ircd.yaml` file. Then you can become an operator by issuing the IRC command: `/oper admin mysecretpassword`.
@@ -440,21 +445,20 @@ 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 three principal tools for 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:
 
-1. `/NICKSERV SUSPEND`, which disables a user account and disconnects all associated clients
+1. `/UBAN`, which can disable user accounts and/or ban offending IPs and networks
-2. `/DLINE ANDKILL`, which bans an IP or CIDR and disconnects clients
+2. `/DEFCON`, which can impose emergency restrictions on user activity in response to attacks
-3. `/DEFCON`, which can impose emergency restrictions on user activity in response to attacks
 
 See the `/HELP` (or `/HELPOP`) entries for these commands for more information, but here's a rough workflow for mitigating spam or other attacks:
 
 1. Subscribe to the `a` snomask to monitor for abusive registration attempts (this is set automatically in the default operator config, but can be added manually with `/mode mynick +s u`)
-2. Given abusive traffic from a nickname, identify whether they are using an account (this should be displayed in `/WHOIS` output)
+2. Given abusive traffic from a nickname, use `/UBAN INFO <nickname>` to find out information about their connection
-3. If they are using an account, suspend the account with `/NICKSERV SUSPEND`, which will disconnect them
+3. If they are using an account, suspend the account with `/UBAN ADD <account>`, which will disconnect them
-4. If they are not using an account, or if they're spamming new registrations from an IP, determine the IP (either from `/WHOIS` or from account registration notices) and temporarily `/DLINE` their IP
+4. If they are not using an account, or if they're spamming new registrations from an IP, you can add a temporary ban on their IP/network with `/UBAN ADD <ip | network>`
 5. When facing a flood of abusive registrations that cannot be stemmed with `/DLINE`, use `/DEFCON 4` to temporarily restrict registrations. (At `/DEFCON 2`, all new connections to the server will require SASL, but this will likely be disruptive to legitimate users as well.)
 
-For channel operators, as opposed to server operators, most traditional moderation tools should be effective. In particular, bans on cloaked hostnames (e.g., `/mode #chan +b *!*@98rgwnst3dahu.my.network`) should work as expected. With `force-nick-equals-account` enabled, channel operators can also ban nicknames (with `/mode #chan +b nick`, which Oragono automatically expands to `/mode #chan +b nick!*@*` as a way of banning an account.)
+For channel operators, `/msg ChanServ HOWTOBAN #channel nickname` will provide similar information about the best way to ban a user from a channel.
 
 
 -------------------------------------------------------------------------------------------