mirror of
https://github.com/ergochat/ergo.git
synced 2024-12-22 10:42:52 +01:00
documentation updates
This commit is contained in:
Shivaram Lingamneni
parent
8198690ffd
commit
7728844ac4
@ -47,7 +47,7 @@ archives:
|
||||
- oragono.motd
|
||||
- default.yaml
|
||||
- traditional.yaml
|
||||
- docs/*
|
||||
- docs/MANUAL.md
|
||||
- languages/*.yaml
|
||||
- languages/*.json
|
||||
- languages/*.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
|
||||
|
||||
92
docs/INFO.md
92
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 :)
|
||||
@ -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 <nickname>` to find out information about their connection
|
||||
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, 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.
|
||||
|
||||
|
||||
-------------------------------------------------------------------------------------------
|
||||
|
||||
Loading…
Reference in New Issue
Block a user