diff --git a/.goreleaser.yml b/.goreleaser.yml index ace7c597..50a7c63a 100644 --- a/.goreleaser.yml +++ b/.goreleaser.yml @@ -47,7 +47,7 @@ archives: - oragono.motd - default.yaml - traditional.yaml - - docs/* + - docs/MANUAL.md - languages/*.yaml - languages/*.json - languages/*.md diff --git a/DEVELOPING.md b/DEVELOPING.md index b806e8e3..df958280 100644 --- a/DEVELOPING.md +++ b/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 diff --git a/docs/INFO.md b/docs/INFO.md deleted file mode 100644 index 8560431a..00000000 --- a/docs/INFO.md +++ /dev/null @@ -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 :) diff --git a/docs/MANUAL.md b/docs/MANUAL.md index badbf075..54c21b39 100644 --- a/docs/MANUAL.md +++ b/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 -2. `/DLINE ANDKILL`, which bans an IP or CIDR and disconnects clients -3. `/DEFCON`, which can impose emergency restrictions on user activity in response to attacks +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 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) -3. If they are using an account, suspend the account with `/NICKSERV SUSPEND`, 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 +2. Given abusive traffic from a nickname, use `/UBAN INFO ` to find out information about their connection +3. If they are using an account, suspend the account with `/UBAN ADD `, which will disconnect them +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 ` 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. -------------------------------------------------------------------------------------------