1 __ __ ______ ___ ______ ___ 2 __/ // /_/ ____/ __ \/ ____/ __ \ 3 /_ // __/ __/ / /_/ / / __/ / / / 4 /_ // __/ /___/ _, _/ /_/ / /_/ / 5 /_//_/ /_____/_/ |_|\____/\____/ 6 7 Ergo IRCd Manual 8 https://ergo.chat/ 9 10 11_Copyright © Daniel Oaks <daniel@danieloaks.net>, Shivaram Lingamneni <slingamn@cs.stanford.edu>_ 12 13 14-------------------------------------------------------------------------------------------- 15 16 17 Table of Contents 18 19- [Introduction](#introduction) 20 - [Project Basics](#project-basics) 21 - [Scalability](#scalability) 22- [Installing](#installing) 23 - [Windows](#windows) 24 - [macOS / Linux / Raspberry Pi](#macos--linux--raspberry-pi) 25 - [Docker](#docker) 26 - [Becoming an operator](#becoming-an-operator) 27 - [Rehashing](#rehashing) 28 - [Environment variables](#environment-variables) 29 - [Productionizing with systemd](#productionizing-with-systemd) 30 - [Using valid TLS certificates](#using-valid-tls-certificates) 31 - [Upgrading to a new version of Ergo](#upgrading-to-a-new-version-of-ergo) 32- [Features](#features) 33 - [User Accounts](#user-accounts) 34 - [Account/Nick Modes](#accountnick-modes) 35 - [Nick equals account](#nick-equals-account) 36 - [Lenient nick reservation](#lenient-nick-reservation) 37 - [No nick reservation](#no-nick-reservation) 38 - [SASL-only mode](#sasl-only-mode) 39 - [Email verification](#email-verification) 40 - [Channel Registration](#channel-registration) 41 - [Language](#language) 42 - [Multiclient ("Bouncer")](#multiclient-bouncer) 43 - [History](#history) 44 - [Persistent history with MySQL](#persistent-history-with-mysql) 45 - [IP cloaking](#ip-cloaking) 46 - [Moderation](#moderation) 47- [Frequently Asked Questions](#frequently-asked-questions) 48- [IRC over TLS](#irc-over-tls) 49 - [Redirect from plaintext to TLS](#how-can-i-redirect-users-from-plaintext-to-tls) 50 - [Reverse proxies](#reverse-proxies) 51 - [Client certificates](#client-certificates) 52 - [SNI](#sni) 53- [Modes](#modes) 54 - [User Modes](#user-modes) 55 - [Channel Modes](#channel-modes) 56 - [Channel Prefixes](#channel-prefixes) 57- [Commands](#commands) 58- [Working with other software](#working-with-other-software) 59 - [Kiwi IRC and Gamja](#kiwi-irc-and-gamja) 60 - [Migrating from Anope or Atheme](#migrating-from-anope-or-atheme) 61 - [HOPM](#hopm) 62 - [Tor](#tor) 63 - [ZNC](#znc) 64 - [External authentication systems](#external-authentication-systems) 65 - [DNSBLs and other IP checking systems](#dnsbls-and-other-ip-checking-systems) 66- [Acknowledgements](#acknowledgements) 67 68-------------------------------------------------------------------------------------------- 69 70 71# Introduction 72 73This document goes over the Ergo IRC server, how to get it running and how to use it once it is up and running! 74 75If you have any suggestions, issues or questions, feel free to submit an issue on our [GitHub repo](https://github.com/ergochat/ergo) or ask in our channel [`#ergo` on irc.ergo.chat](ircs://irc.ergo.chat:6697/#ergo) or [`#ergo` on irc.libera.chat](ircs://irc.libera.chat:6697/#ergo). 76 77 78## Project Basics 79 80Ergo is an ircd written "from scratch" in the [Go](https://en.wikipedia.org/wiki/Go_%28programming_language%29) language, i.e., it [shares no code](https://github.com/grawity/irc-docs/blob/master/family-tree.txt) with the original ircd implementation or any other major ircd. It began as [ergonomadic](https://github.com/jlatt/ergonomadic), which was developed by Jeremy Latt between 2012 and 2014. In 2016, Daniel Oaks forked the project under the name Oragono, in order to prototype [IRCv3](https://ircv3.net/) features and for use as a reference implementation of the [Modern IRC specification](https://modern.ircdocs.horse). Oragono 1.0.0 was released in February 2019; the project switched to its current name of Ergo in June 2021. 81 82Ergo's core design goals are: 83 84* Being simple to set up and use 85* Combining the features of an ircd, a services framework, and a bouncer (integrated account management, history storage, and bouncer functionality) 86* Bleeding-edge [IRCv3 support](http://ircv3.net/software/servers.html), suitable for use as an IRCv3 reference implementation 87* High customizability via a rehashable (i.e., reloadable at runtime) YAML config 88 89In addition to its unique features (integrated services and bouncer, comprehensive internationalization), Ergo also strives for feature parity with other major servers. Ergo is a mature project with multiple communities using it as a day-to-day chat server --- we encourage you to consider it for your organization or community! 90 91## Scalability 92 93We believe Ergo should scale comfortably to 10,000 clients and 2,000 clients per channel, making it suitable for small to medium-sized teams and communities. Ergo does not currently support server-to-server linking (federation), meaning that all clients must connect to the same instance. However, since Ergo is implemented in Go, it is reasonably effective at distributing work across multiple cores on a single server; in other words, it should "scale up" rather than "scaling out". (Horizontal scalability is [planned](https://github.com/ergochat/ergo/issues/1532) but is not scheduled for development in the near term.) 94 95Even though it runs as a single instance, Ergo can be deployed for high availability (i.e., with no single point of failure) using Kubernetes. This technique uses a k8s [LoadBalancer](https://kubernetes.io/docs/tasks/access-application-cluster/create-external-load-balancer/) to receive external traffic and a [Volume](https://kubernetes.io/docs/concepts/storage/volumes/) to store the embedded database file. See [Hashbang's implementation](https://github.com/hashbang/gitops/tree/master/ircd) for a "worked example". 96 97If you're interested in deploying Ergo at scale or for high availability, or want performance tuning advice, come find us on [`#ergo` on Libera](ircs://irc.libera.chat:6697/#ergo), we're very interested in what our software can do! 98 99 100-------------------------------------------------------------------------------------------- 101 102 103# Installing 104 105In this section, we'll explain how to install and use the Ergo IRC server. 106 107 108## Windows 109 110To get started with Ergo on Windows: 111 1121. Make sure you have the [latest release](https://github.com/ergochat/ergo/releases/latest) downloaded. 1131. Extract the zip file to a folder. 1141. Copy and rename `default.yaml` to `ircd.yaml`. 1151. Open up `ircd.yaml` using any text editor, and then save it once you're happy. 1161. Open up a `cmd.exe` window, then `cd` to where you have Ergo extracted. 1171. Run `ergo mkcerts` if you want to generate new self-signed SSL/TLS certificates (note that you can't enable STS if you use self-signed certs). 118 119To start the server, type `ergo run` and hit enter, and the server should start! 120 121 122## macOS / Linux / Raspberry Pi 123 124To get started with Ergo on macOS, Linux, or on a Raspberry Pi: 125 1261. Make sure you have the [latest release](https://github.com/ergochat/ergo/releases/latest) for your OS/distro downloaded. 1271. Extract the tar.gz file to a folder. 1281. Copy and rename `default.yaml` to `ircd.yaml`. 1291. Open up `ircd.yaml` using any text editor, and then save it once you're happy. 1301. Open up a Terminal window, then `cd` to where you have Ergo extracted. 1311. Run `./ergo mkcerts` if you want to generate new self-signed SSL/TLS certificates (note that you can't enable STS if you use self-signed certs). 132 133To start the server, type `./ergo run` and hit enter, and the server should be ready to use! 134 135 136## Docker 137 1381. Pull the latest version of Ergo: `docker pull oragono/oragono:latest` 1391. Create a volume for persistent data: `docker volume create oragono-data` 1401. Run the container, exposing the default ports: `docker run -d --name oragono -v oragono-data:/ircd-data -p 6667:6667 -p 6697:6697 oragono/oragono:latest` 141 142For further information and a sample docker-compose file see the separate [Docker documentation](https://github.com/oragono/oragono/blob/master/distrib/docker/README.md). 143 144 145## Building from source 146 147You'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 `ergo` in the base directory of the project. 148 149 150## Becoming an operator 151 152Many 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 Ergo instance is first to pick a strong, secure password, then "hash" it using the `ergo genpasswd` command (run `ergo 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`. 153 154The operator defined in the default configuration file is named `admin` and has full administrative privileges on the server; see the `oper-classes` and `opers` blocks for information on how to define additional operators, or less privileged operators. 155 156 157## Rehashing 158 159The primary way of configuring Ergo is by modifying the configuration file. Most changes to the configuration file can be applied at runtime by "rehashing", i.e., reloading the configuration file without restarting the server process. This has the advantage of not disconnecting users. There are two ways to rehash Ergo: 160 1611. If you are an operator with the `rehash` capability, you can issue the `/REHASH` command (you may have to `/quote rehash`, depending on your client) 1621. You can send the `SIGHUP` signal to Ergo, e.g., via `killall -HUP ergo` 163 164Rehashing also reloads TLS certificates and the MOTD. Some configuration settings cannot be altered by rehash. You can monitor either the response to the `/REHASH` command, or the server logs, to see if your rehash was successful. 165 166 167## Environment variables 168 169Ergo can also be configured using environment variables, using the following technique: 170 1711. Find the "path" of the config variable you want to override in the YAML file, e.g., `server.websockets.allowed-origins` 1721. Convert each path component from "kebab case" to "screaming snake case", e.g., `SERVER`, `WEBSOCKETS`, and `ALLOWED_ORIGINS`. 1731. Prepend `ORAGONO` to the components, then join them all together using `__` as the separator, e.g., `ORAGONO__SERVER__WEBSOCKETS__ALLOWED_ORIGINS`. 1741. Set the environment variable of this name to a JSON (or YAML) value that will be deserialized into this config field, e.g., `export ORAGONO__SERVER__WEBSOCKETS__ALLOWED_ORIGINS='["https://irc.example.com", "https://chat.example.com"]'` 175 176However, settings that were overridden using this technique cannot be rehashed --- changing them will require restarting the server. 177 178 179## Productionizing with systemd 180 181The recommended way to operate ergo as a service on Linux is via systemd. This provides a standard interface for starting, stopping, and rehashing (via `systemctl reload`) the service. It also captures ergo's loglines (sent to stderr in the default configuration) and writes them to the system journal. 182 183The only major distribution that currently packages Ergo is Arch Linux; the aforementioned AUR package includes a systemd unit file. However, it should be fairly straightforward to set up a productionized Ergo on any Linux distribution. Here's a quickstart guide for Debian/Ubuntu: 184 1851. Create a dedicated, unprivileged role user who will own the ergo process and all its associated files: `adduser --system --group ergo`. This user now has a home directory at `/home/ergo`. To prevent other users from viewing Ergo's configuration file, database, and certificates, restrict the permissions on the home directory: `chmod 0700 /home/ergo`. 1861. Copy the executable binary `ergo`, the config file `ircd.yaml`, the database `ircd.db`, and the self-signed TLS certificate (`fullchain.pem` and `privkey.pem`) to `/home/ergo`. (If you don't have an `ircd.db`, it will be auto-created as `/home/ergo/ircd.db` on first launch.) Ensure that they are all owned by the new ergo role user: `sudo chown ergo:ergo /home/ergo/*`. Ensure that the configuration file logs to stderr. 1871. Install our example [ergo.service](https://github.com/ergochat/ergo/blob/stable/distrib/systemd/ergo.service) file to `/etc/systemd/system/ergo.service`. 1881. Enable and start the new service with the following commands: 189 1. `systemctl daemon-reload` 190 1. `systemctl enable ergo.service` 191 1. `systemctl start ergo.service` 192 1. Confirm that the service started correctly with `systemctl status ergo.service` 193 194 195On 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. 196 197 198## Using valid TLS certificates 199 200The other major hurdle for productionizing (but one well worth the effort) is obtaining valid TLS certificates for your domain, if you haven't already done so: 201 2021. The simplest way to get valid TLS certificates is from [Let's Encrypt](https://letsencrypt.org/) with [Certbot](https://certbot.eff.org/). The correct procedure will depend on whether you are already running a web server on port 80. If you are, follow the guides on the Certbot website; if you aren't, you can use `certbot certonly --standalone --preferred-challenges http -d example.com` (replace `example.com` with your domain). 2031. At this point, you should have certificates available at `/etc/letsencrypt/live/example.com` (replacing `example.com` with your domain). You should serve `fullchain.pem` as the certificate and `privkey.pem` as its private key. However, these files are owned by root and the private key is not readable by the ergo role user, so you won't be able to use them directly in their current locations. You can write a post-renewal hook for certbot to make copies of these certificates accessible to the ergo role user. For example, install the following script as `/etc/letsencrypt/renewal-hooks/post/install-ergo-certificates`, again replacing `example.com` with your domain name, and chmod it 0755: 204 205````bash 206#!/bin/bash 207 208set -eu 209 210umask 077 211cp /etc/letsencrypt/live/example.com/fullchain.pem /home/ergo/ 212cp /etc/letsencrypt/live/example.com/privkey.pem /home/ergo/ 213chown ergo:ergo /home/ergo/*.pem 214# rehash ergo, which will reload the certificates: 215systemctl reload ergo.service 216```` 217 218Executing this script manually will install the certificates for the first time and perform a rehash, enabling them. 219 220If you are using Certbot 0.29.0 or higher, you can also change the ownership of the files under `/etc/letsencrypt` so that the ergo user can read them, as described in the [UnrealIRCd documentation](https://www.unrealircd.org/docs/Setting_up_certbot_for_use_with_UnrealIRCd#Tweaking_permissions_on_the_key_file). 221 222 223## Upgrading to a new version of Ergo 224 225As long as you are using official releases or release candidates of Ergo, any backwards-incompatible changes should be described in the changelog. 226 227In general, the config file format should be fully backwards and forwards compatible. Unless otherwise noted, no config file changes should be necessary when upgrading Ergo. However, the "config changes" section of the changelog will typically describe new sections that can be added to your config to enable new functionality, as well as changes in the recommended values of certain fields. 228 229The database is versioned; upgrades that involve incompatible changes to the database require updating the database. If you have `datastore.autoupgrade` enabled in your config, the database will be backed up and upgraded when you restart your server when required. Otherwise, you can apply upgrades manually: 230 2311. Stop your server 2321. Make a backup of your database file 2331. Run `ergo upgradedb` (from the same working directory and with the same arguments that you would use when running `ergo run`) 2341. Start the server again 235 236If you want to run our master branch as opposed to our releases, come find us in our channel and we can guide you around any potential pitfalls. 237 238 239-------------------------------------------------------------------------------------------- 240 241 242# Features 243 244In this section, we'll explain and go through using various features of the Ergo IRC server. 245 246 247## User Accounts 248 249In most IRC servers you can use `NickServ` to register an account. You can do the same thing with Ergo, by default, with no other software needed! 250 251To register an account, use: 252 253 /NS REGISTER <password> 254 255or 256 257 /msg nickserv register <password> 258 259This is the way to go if you want to use a regular password. `<password>` is your password, your current nickname will become your username. Your password cannot contain spaces, but make sure to use a strong one anyway. 260 261If you want to use a TLS client certificate instead of a password to authenticate (`SASL EXTERNAL`), then you can use the command below to do so. (If you're not sure what this is, don't worry – just use the above password method to register an account.) 262 263 /NS REGISTER * 264 265Once 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! 266 267If 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. 268 269## Account/Nick Modes 270 271Ergo supports several different modes of operation with respect to accounts and nicknames. 272 273### Nick equals account 274 275In this mode (the default), registering an account gives you privileges over the use of the account name as a nickname. The server will then enforce several invariants with regard to your nickname: 276 2771. Only you can use your nickname, i.e., clients cannot use your nickname unless they are logged into your account 2781. 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 2791. If you unregister your account, your nickname will be permanently unreclaimable (thus preventing people from impersonating you) 280 281In 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. 282 283As 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`. 284 285To enable this mode as the server operator, set the following configs (note that they are already set in `default.yaml`): 286 287* `accounts.registration.enabled = true` 288* `accounts.authentication-enabled = true` 289* `accounts.nick-reservation.enabled = true` 290* `accounts.nick-reservation.method = strict` 291* `accounts.nick-reservation.allow-custom-enforcement = false` 292* `accounts.nick-reservation.force-nick-equals-account = true` 293 294### Lenient nick reservation 295 296In this mode (implemented in the `traditional.yaml` config file example), nickname reservation is available, but end users must opt into it using `/msg NickServ set enforce strict`. Moreover, you need not use your nickname; even while logged in to your account, you can change nicknames to anything that is not reserved by another user. You can reserve some of your alternate nicknames using `/msg NickServ group`. 297 298To enable this mode as the server operator, set the following configs (they are set in `traditional.yaml`): 299 300* `accounts.registration.enabled = true` 301* `accounts.authentication-enabled = true` 302* `accounts.nick-reservation.enabled = true` 303* `accounts.nick-reservation.method = optional` 304* `accounts.nick-reservation.allow-custom-enforcement = true` 305* `accounts.nick-reservation.force-nick-equals-account = false` 306 307### No nick reservation 308 309This makes Ergo's services act similar to Quakenet's Q bot. In this mode, users cannot own or reserve nicknames. In other words, there is no connection between account names and nicknames. Anyone can use any nickname (as long as it's not already in use by another running client). However, accounts are still useful: they can be used to register channels (see below), and some IRCv3-capable clients (with the `account-tag` or `extended-join` capabilities) may be able to take advantage of them. 310 311To enable this mode, set the following configs: 312 313* `accounts.registration.enabled = true` 314* `accounts.authentication-enabled = true` 315* `accounts.nick-reservation.enabled = false` 316 317### SASL-only mode 318 319This mode is comparable to Slack, Mattermost, or similar products intended as internal chat servers for an organization or team. In this mode, clients cannot connect to the server unless they log in with SASL as part of the initial handshake. This allows Ergo to be deployed facing the public Internet, with fine-grained control over who can log in. 320 321In this mode, clients must not be allowed to register their own accounts, so user-initiated account registration must be disabled. Accordingly, an operator must do the initial account creation, using the `SAREGISTER` command of NickServ. (For more details, `/msg NickServ help saregister`.) To bootstrap this process, you can make an initial connection from localhost, which is exempt (by default) from the requirement, or temporarily add your own IP to the exemption list. You can also use a more permissive configuration for bootstrapping, then switch to this one once you have your account. Another possibility is permanently exempting an internal network, e.g., `10.0.0.0/8`, that only trusted people can access. 322 323To enable this mode, use the configs from the "nick equals account" section (i.e., start from `default.yaml`) and make these modifications: 324 325* `accounts.registration.enabled = false` 326* `accounts.require-sasl.enabled = true` 327 328## Email verification 329 330By default, account registrations complete immediately and do not require a verification step. However, like other service frameworks, Ergo's NickServ can be configured to require email verification of registrations. The main challenge here is to prevent your emails from being marked as spam, which you can do by configuring [SPF](https://en.wikipedia.org/wiki/Sender_Policy_Framework), [DKIM](https://en.wikipedia.org/wiki/DomainKeys_Identified_Mail), and [DMARC](https://en.wikipedia.org/wiki/DMARC). For example, this configuration (when added to the `accounts.registration` section) enables email verification, with the emails being signed with a DKIM key and sent directly from Ergo: 331 332```yaml 333 email-verification: 334 enabled: true 335 sender: "admin@my.network" 336 require-tls: true 337 helo-domain: "my.network" # defaults to server name if unset 338 dkim: 339 domain: "my.network" 340 selector: "20200229" 341 key-file: "dkim.pem" 342``` 343 344You must create the corresponding TXT record `20200229._domainkey.my.network` to hold your public key. 345 346You 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. 347 348 349## Channel Registration 350 351Once you've registered an account, you can also register channels. If you own a channel, you'l be opped whenever you join it, and the topic/modes will be remembered and re-applied whenever anyone rejoins the channel. 352 353To register a channel, make sure you're joined to it and logged into your account. If both those are true, you can send this command to register your account: 354 355 /CS REGISTER #channelname 356 357For example, `/CS REGISTER #channel` will register the channel `#channel` to my account. If you have a registered channel, you can use `/CS OP #channel` to regain ops in it. Right now, the options for a registered channel are pretty sparse, but we'll add more as we go along. 358 359If your friends have registered accounts, you can automatically grant them operator permissions when they join the channel. For more details, see `/CS HELP AMODE`. 360 361 362## Language 363 364Ergo supports multiple languages! Specifically, once you connect you're able to get server messages in other languages (messages from other users will still be in their original languages, though). 365 366To see which languages are supported, run this command: 367 368 /QUOTE CAP LS 302 369 370In the resulting text, you should see a token that looks something like this: 371 372 draft/languages=11,en,~ro,~tr-TR,~el,~fr-FR,~pl,~pt-BR,~zh-CN,~en-AU,~es,~no 373 374That's the list of languages we support. For the token above, the supported languages are: 375 376- `en`: English 377- `en-AU`: Australian English 378- `el`: Greek 379- `es`: Spanish 380- `fr-FR`: French 381- `no`: Norwegian 382- `pl`: Polish 383- `pt-BR`: Brazilian Portugese 384- `ro`: Romanian 385- `tr-TR`: Turkish 386- `zh-CN`: Chinese 387 388To change to a specific language, you can use the `LANGUAGE` command like this: 389 390 /LANGUAGE ro zh-CN 391 392The above will change the server language to Romanian, with a fallback to Chinese. English will always be the final fallback, if there's a line that is not translated. Substitute any of the other language codes in to select other languages, and run `/LANGUAGE en` to get back to standard English. 393 394Our language and translation functionality is very early, so feel free to let us know if there are any troubles with it! If you know another language and you'd like to contribute, we've got a CrowdIn project here: [https://crowdin.com/project/oragono](https://crowdin.com/project/oragono) 395 396 397## Multiclient ("Bouncer") 398 399Traditionally, every connection to an IRC server is separate must use a different nickname. [Bouncers](https://en.wikipedia.org/wiki/BNC_%28software%29#IRC) are used to work around this, by letting multiple clients connect to a single nickname. With Ergo, if the server is configured to allow it, multiple clients can share a single nickname without needing a bouncer. To use this feature, both connections must authenticate with SASL to the same user account and then use the same nickname during connection registration (while connecting to the server) – once you've logged-in, you can't share another nickname. 400 401To enable this functionality, set `accounts.multiclient.enabled` to `true`. Setting `accounts.multiclient.allowed-by-default` to `true` will allow this for everyone. If `allowed-by-default` is `false` (but `enabled` is still `true`), users can opt in to shared connections using `/msg NickServ SET multiclient true`. 402 403You can see a list of your active sessions and their idle times with `/msg NickServ sessions` (network operators can use `/msg NickServ sessions nickname` to see another user's sessions). 404 405Ergo now supports "always-on clients" that remain present on the server (holding their nickname, subscribed to channels, able to receive DMs, etc.) even when no actual clients are connected. To enable this as a server operator, set `accounts.multiclient.always-on` to either `opt-in`, `opt-out`, or `mandatory`. To enable or disable it as a client (if the server setting is `opt-in` or `opt-out` respectively), use `/msg NickServ set always-on true` (or `false`). 406 407 408## History 409 410Ergo supports two methods of storing history, an in-memory buffer with a configurable maximum number of messages, and persistent history stored in MySQL (with no fixed limits on message capacity). To enable in-memory history, configure `history.enabled` and associated settings in the `history` section. To enable persistent history, enter your MySQL server information in `datastore.mysql` and then enable persistent history storage in `history.persistent`. 411 412Unfortunately, client support for history playback is still patchy. In descending order of support: 413 4141. 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. 4151. 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). 4161. 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. Ergo 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: 417 - You can add it to your SASL username with an `@`, e.g., if your SASL username is `alice` you can send `alice@phone` 418 - You can add it in a similar way to your IRC protocol username ("ident"), e.g., `alice@phone` 419 - 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 4201. 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. 4211. 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.) 4221. You can autoreplay a fixed number of lines (e.g., 25) each time you join a channel using `/msg NickServ set autoreplay-lines 25`. 423 424 425## Persistent history with MySQL 426 427On most Linux and POSIX systems, it's straightforward to set up MySQL (or MariaDB) as a backend for persistent history. This increases the amount of history that can be stored, and ensures that message data will be retained on server restart (you can still use the configuration options to set a time limit for retention). Here's a quick start guide for Ubuntu based on [Digital Ocean's documentation](https://www.digitalocean.com/community/tutorials/how-to-install-mysql-on-ubuntu-20-04): 428 4291. Install the `mysql-server` package 4301. Run `mysql_secure_installation` as root; this corrects some insecure package defaults 4311. Connect to your new MySQL server as root with `mysql --user root` 4321. In the MySQL prompt, create a new `ergo` user (substitute a strong password of your own for `hunter2`): `CREATE USER 'ergo'@'localhost' IDENTIFIED BY 'hunter2';` 4331. Create the database that history will be stored in: `CREATE DATABASE ergo_history;` 4341. Grant privileges on the database to the new user: `GRANT ALL PRIVILEGES ON ergo_history.* to 'ergo'@'localhost';` 4351. Enable persistent history in your Ergo config file. At a minimum, you must set `history.persistent.enabled = true`. You may want to modify the other options under `history.persistent` and `history`. 4361. Configure Ergo to talk to MySQL (again, substitute the strong password you chose previously for `hunter2`): 437 438```yaml 439 mysql: 440 enabled: true 441 socket-path: "/var/run/mysqld/mysqld.sock" 442 user: "ergo" 443 password: "hunter2" 444 history-database: "ergo_history" 445 timeout: 3s 446``` 447 448 449## IP cloaking 450 451Unlike many other chat and web platforms, IRC traditionally exposes the user's IP and hostname information to other users. This is in part because channel owners and operators (who have privileges over a single channel, but not over the server as a whole) need to be able to ban spammers and abusers from their channels, including via hostnames in cases where the abuser tries to evade the ban. 452 453IP cloaking is a way of balancing these concerns about abuse with concerns about user privacy. With cloaking, the user's IP address is deterministically "scrambled", typically via a cryptographic [MAC](https://en.wikipedia.org/wiki/Message_authentication_code), to form a "cloaked" hostname that replaces the usual reverse-DNS-based hostname. Users cannot reverse the scrambling to learn each other's IPs, but can ban a scrambled address the same way they would ban a regular hostname. 454 455Ergo supports cloaking, which is enabled by default (via the `server.ip-cloaking` section of the config). However, Ergo's cloaking behavior differs from other IRC software. Rather than scrambling each of the 4 bytes of the IPv4 address (or each 2-byte pair of the 8 such pairs of the IPv6 address) separately, the server administrator configures a CIDR length (essentially, a fixed number of most-significant-bits of the address). The CIDR (i.e., only the most significant portion of the address) is then scrambled atomically to produce the cloaked hostname. This errs on the side of user privacy, since knowing the cloaked hostname for one CIDR tells you nothing about the cloaked hostnames of other CIDRs --- the scheme reveals only whether two users are coming from the same CIDR. We suggest using 32-bit CIDRs for IPv4 (i.e., the whole address) and 64-bit CIDRs for IPv6, since these are the typical assignments made by ISPs to individual customers. 456 457Setting `server.ip-cloaking.num-bits` to 0 gives users cloaks that don't depend on their IP address information at all, which is an option for deployments where privacy is a more pressing concern than abuse. Holders of registered accounts can also use the vhost system (for details, `/msg HostServ HELP`.) 458 459 460## Moderation 461 462Ergo shares some server operator moderation tools with other ircds. In particular: 463 4641. `/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` 4652. `/SAJOIN` lets operators join channels despite restrictions, or forcibly join another user to a channel. For example, `/SAJOIN #channel` or `/SAJOIN nickname #channel`. 466 467However, Ergo'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: 468 4691. `/UBAN`, which can disable user accounts and/or ban offending IPs and networks 4702. `/DEFCON`, which can impose emergency restrictions on user activity in response to attacks 471 472See the `/HELP` (or `/HELPOP`) entries for these commands for more information, but here's a rough workflow for mitigating spam or other attacks: 473 4741. 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`) 4752. Given abusive traffic from a nickname, use `/UBAN INFO <nickname>` to find out information about their connection 4763. If they are using an account, suspend the account with `/UBAN ADD <account>`, which will disconnect them 4774. 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>` 4785. 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.) 479 480For channel operators, `/msg ChanServ HOWTOBAN #channel nickname` will provide similar information about the best way to ban a user from a channel. 481 482 483------------------------------------------------------------------------------------------- 484 485 486# Frequently Asked Questions 487 488 489## How do I submit a suggestion? 490 491Awesome! We love getting new suggestions for features, ways to improve the server and the tooling around it, everything. 492 493There are two ways to make suggestions, either: 494 495- Submit an issue on our [bug tracker](https://github.com/ergochat/ergo/issues). 496- Talk to us in the `#ergo` channel on irc.ergo.chat or irc.libera.chat. 497 498 499## Why can't I oper? 500 501If you try to oper unsuccessfully, Ergo will disconnect you from the network. If you're unable to oper, here are some things to double-check: 502 5031. Did you correctly generate the hashed password with `ergo genpasswd`? 5041. Did you add the password hash to the correct config file, then save the file? 5051. Did you rehash or restart Ergo after saving the file? 506 507The config file accepts hashed passwords, not plaintext passwords. You must run `ergo 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. 508 509After that, you must rehash or restart Ergo to apply the config change. If a rehash didn't accomplish the desired effects, you might want to try a restart instead. 510 511 512## Why is Ergo ignoring my ident response / USER command? 513 514The default/recommended configuration of Ergo does not query remote ident servers, and furthermore ignores any user/ident sent with the `USER` command. All user/ident fields are set to a constant `~u`. There are a few reasons for this: 515 5161. Remote ident lookups slow down connection initiation and pose privacy and security concerns (since they transmit usernames over the Internet in plaintext). 5172. Ignoring user/ident simplifies bans; in general, a channel ban in Ergo should target either the nickname or the hostname. As a channel operator, `/msg ChanServ HOWTOBAN #channel nick` will recommend a way of banning any given user. 5183. Ident is commonly used to distinguish users connecting from the same trusted shell host or shared bouncer. This is less important with Ergo, which can act as a bouncer itself. 5194. Because of limitations of the IRC protocol, every character of the user/ident field counts against the maximum size of a message that can be sent. 520 521As an operator, you can modify this behavior if desired; see the `check-ident` and `coerce-ident` settings in the config file. 522 523 524## Why can't I change nicknames? 525 526The default/recommended configuration of Ergo does not allow authenticated users to change their nicknames; an authenticated user must use their account name as their nickname. There are a few reasons for this: 527 5281. Assigning a consistent nickname prevents certain "split-brain" scenarios that break Ergo's "multiclient" functionality. In brief, if two clients are connecting to the same account/identity, but only one of them issues a `/NICK` command, and then one of them subsequently loses and regains its connection to the server, they "break apart": they will have separate identities and channel memberships on the network, and it's difficult to bring them back together again. 5292. The use of a consistent nickname reduces the possibility of edge cases in history playback. 5303. The use of a consistent nickname simplifies offline messaging (which is a first-class concept for always-on clients). 5314. Ergo eliminates the cases in conventional IRC servers that necessitate nickname changes. In particular, you can always claim your nickname, even if the server is still waiting for an old client to time out, and you can connect arbitrarily many clients to the same nickname. 532 533As an operator, you can disable this behavior using the `force-nick-equals-account` setting, but this is discouraged because it has no effect on always-on clients; always-on clients must use their account names as their nicknames regardless of this setting. 534 535 536## How do I make a private channel? 537 538We recommend that server administrators set the following recommended defaults: 539 5401. `nick-reservation-method: strict` 5411. `force-nick-equals-account: true` 542 543These 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. 544 545Under these circumstances, users can follow the following steps: 546 5471. Register a channel (`/msg ChanServ register #example`) 5481. Set it to be invite-only (`/mode #example +i`) 5491. Add the desired nick/account names to the invite exception list (`/mode #example +I alice`) 5501. Anyone with persistent half-operator status or higher will also be able to join without an invite (`/msg ChanServ amode #example +h alice`) 551 552Similarly, 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`.) 553 554 555## How do I send an announcement to all connected users? 556 557Ergo 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`. 558 559 560------------------------------------------------------------------------------------------- 561 562 563# IRC over TLS 564 565IRC has traditionally been available over both plaintext (on port 6667) and SSL/TLS (on port 6697). We recommend that you make your server available exclusively via TLS, since exposing plaintext access allows for unauthorized interception or modification of user data or passwords. The default config file no longer exposes a plaintext port, so if you haven't modified your `listeners` section, you're good to go. 566 567For a quickstart guide to obtaining valid TLS certificates from Let's Encrypt, see the "productionizing" section of the manual above. 568 569## How can I "redirect" users from plaintext to TLS? 570 571The [STS specification](https://ircv3.net/specs/extensions/sts) can be used to redirect clients from plaintext to TLS automatically. If you set `server.sts.enabled` to `true`, clients with specific support for STS that connect in plaintext will disconnect and reconnect over TLS. To use STS, you must be using certificates issued by a generally recognized certificate authority, such as Let's Encrypt. 572 573Many clients do not have this support. However, you can designate port 6667 as an "STS-only" listener: any client that connects to such a listener will receive both the machine-readable STS policy and a human-readable message instructing them to reconnect over TLS, and will then be disconnected by the server before they can send or receive any chat data. Here is an example of how to configure this behavior: 574 575```yaml 576 listeners: 577 ":6667": 578 sts-only: true 579 580 # These are loopback-only plaintext listeners on port 6668: 581 "127.0.0.1:6668": # (loopback ipv4, localhost-only) 582 "[::1]:6668": # (loopback ipv6, localhost-only) 583 584 ":6697": 585 tls: 586 cert: fullchain.pem 587 key: privkey.pem 588 589 sts: 590 enabled: true 591 592 # how long clients should be forced to use TLS for. 593 duration: 1mo2d5m 594``` 595 596## Reverse proxies 597 598Ergo supports the use of reverse proxies (such as nginx, or a Kubernetes [LoadBalancer](https://kubernetes.io/docs/concepts/services-networking/service/#loadbalancer)) that sit between it and the client. In these deployments, the [PROXY protocol](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt) is used to pass the end user's IP through to Ergo. These proxies can be used to terminate TLS externally to Ergo, e.g., if you need to support versions of the TLS protocol that are not implemented natively by Go, or if you want to consolidate your certificate management into a single nginx instance. 599 600The first step is to add the reverse proxy's IP to `proxy-allowed-from` and `ip-limits.exempted`. (Use `localhost` to exempt all loopback IPs and Unix domain sockets.) 601 602After that, there are two possibilities: 603 604* If you're using a proxy like nginx or stunnel that terminates TLS, then forwards a PROXY v1 (ASCII) header ahead of a plaintext connection, no further Ergo configuration is required. You need only configure your proxy to send the PROXY header. Here's an [example nginx config](https://github.com/ergochat/testnet.ergo.chat/blob/master/nginx_stream.conf). 605* If you're using a cloud load balancer that either sends a PROXY v1 header ahead of unterminated TLS (like [DigitalOcean](https://www.digitalocean.com/docs/networking/load-balancers/#proxy-protocol)) or sends a PROXY v2 (binary) header (like the [AWS "Network Load Balancer"](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/load-balancer-target-groups.html#proxy-protocol)), Ergo must be configured to expect a PROXY header ahead of the connection. Add `proxy: true` to the listener config block, e.g., 606 607```yaml 608 ":6697": 609 tls: 610 cert: fullchain.pem 611 key: privkey.pem 612 proxy: true 613``` 614 615 616## Client certificates 617 618Ergo supports authenticating to user accounts via TLS client certificates. The end user must enable the client certificate in their client and also enable SASL with the `EXTERNAL` method. To register an account using only a client certificate for authentication, connect with the client certificate and use `/NS REGISTER *` (or `/NS REGISTER * email@example.com` if email verification is enabled on the server). To add a client certificate to an existing account, obtain the SHA-256 fingerprint of the certificate (either by connecting with it and looking at your own `/WHOIS` response, in particular the `276 RPL_WHOISCERTFP` line, or using the openssl command `openssl x509 -noout -fingerprint -sha256 -in example_client_cert.pem`), then use the `/NS CERT` command). 619 620Client certificates are not supported over websockets due to a [Chrome bug](https://bugs.chromium.org/p/chromium/issues/detail?id=329884). 621 622## SNI 623 624Ergo supports [SNI](https://en.wikipedia.org/wiki/Server_Name_Indication); this is useful if you have multiple domain names for your server, with different certificates covering different domain names. Configure your TLS listener like this: 625 626```yaml 627 ":6697": 628 tls-certificates: 629 - 630 cert: cert1.pem 631 key: key1.pem 632 - 633 cert: cert2.pem 634 key: key2.pem 635``` 636 637If multiple certificates are applicable, or the client does not send SNI, the server will offer the first applicable certificate in the list. 638 639-------------------------------------------------------------------------------------------- 640 641 642# Modes 643 644On IRC, you can set modes on users and on channels. Modes are basically extra information that changes how users and channels work. 645 646In this section, we give an overview of the modes Ergo supports. 647 648 649## User Modes 650 651These are the modes which can be set on you when you're connected. 652 653### +i - Invisible 654 655If this mode is set, you're marked as 'invisible'. This means that your channels won't be shown when users `/WHOIS` you (except for IRC operators, they can see all the channels you're in). 656 657To set this mode on yourself: 658 659 /mode dan +i 660 661### +o - Operator 662 663If this mode is set, you're marked as an 'IRC Operator'. This means that you're an admin of some sort on the server and have some special powers regular users don't have. To set this mode, you authenticate (oper-up) using the `/OPER` command. 664 665### +R - Registered-Only 666 667If this mode is set, you'll only receive messages from other users if they're logged into an account. If a user who isn't logged-in messages you, you won't see their message. 668 669To set this mode on yourself: 670 671 /mode dan +R 672 673To unset this mode and let anyone speak to you: 674 675 /mode dan -R 676 677### +s - Server Notice Masks ("snomasks") 678 679This is a special 'list mode'. If you're an IRC operator, this mode lets you see special server notices that get sent out. See `/helpop snomasks` (as an operator) for more information on this mode. 680 681### +Z - TLS 682 683This mode is automatically set if you're connecting using SSL/TLS. There's no way to set this yourself, and it's automatically set or not set when you connect to the server. 684 685### +B - Bot 686 687If this mode is set, you are marked as a 'Bot'. The bot can set this mode on itself. This adds additional information in response to WHOIS 688 689 /WHOIS Bot 690 691will return an extra response of `RPL_WHOISBOT` with the numeric `335` which can be used to identify said Bot. 692 693### +T - No CTCPs 694 695If this mode is set, you will not recieve CTCP messages. 696 697To set this mode on yourself: 698 699 /mode dan +T 700 701To unset this mode and recieve CTCP messages: 702 703 /mode dan -T 704 705## Channel Modes 706 707These are the modes that can be set on channels when you're a channel operator! 708 709### +b - Ban 710 711With this channel mode, you can change and see who's banned from the channel. Specifically, you can ban 'masks', or a set of nickname, username and hostname. 712 713Here's an example of banning a user named **bob** from channel #test: 714 715 /MODE #test +b bob!*@* 716 717Let's say that **bob** is connecting from the address `192.168.0.234`. You could also do this to ban him: 718 719 /MODE #test +b *!*@192.168.0.234 720 721Banning **bob** in this way means that nobody from that address can connect. 722 723To remove a ban, you do the same thing with `-b` instead of `+b`. 724 725To view the bans that exist on the channel, you can do this instead: 726 727 /MODE #test b 728 729#### Extended Bans 730 731Users can be muted rather than banned by prefixing a ban mask with `m:`. This prevents matching users from speaking in the channel, without kicking them or preventing them from joining the channel. For example, to mute a user named **bob** in the channel #test: 732 733 /MODE #test +b m:bob!*@* 734 735The mute can be removed with `-b` instead of `+b`. 736 737### +e - Ban-Exempt 738 739With this channel mode, you can change who's allowed to bypass bans. For example, let's say you set these modes on the channel: 740 741 /MODE #test +b *!*@192.168.0.234 742 /MODE #test +e bob!*@* 743 744This means that **bob** will always be able to join, even if he's connecting from `192.168.0.234`. 745 746For everything else, this mode acts like the `+b - Ban` mode. 747 748### +f - Forward 749 750This channel mode takes another channel as its parameter. Users who are unable to join this channel are forwarded to the provided channel instead. 751 752You need be a channel operator in both channels in order to set this mode. 753 754 /MODE #test +f #foo 755 756This means that users who attempt to join `#test`, but cannot due to another channel mode like `+i` or `+l`, will be forwarded to `#foo` instead. 757 758### +i - Invite-Only 759 760If this channel mode is set on a channel, users will only be able to join if someone has `/INVITE`'d them first. 761 762To set a channel to invite-only: 763 764 /MODE #test +i 765 766To unset the mode and let anyone join: 767 768 /MODE #test -i 769 770### +I - Invite-Exempt 771 772With this channel mode, you can change who's allowed to join the channel when the `+i - Invite-Only` mode is enabled. 773 774For example, let's say you set these modes on the channel: 775 776 /MODE #test +i 777 /MODE #test +I bob!*@* 778 779This means that **bob** will be able to join even without being `/INVITE`'d. 780 781For everything else, this mode acts like the `+b - Ban` mode. 782 783### +k - Key 784 785This channel mode lets you set a 'key' that other people will need to join your channel. To set a key: 786 787 /MODE #test +k p4ssw0rd 788 789Then, to join users will need to do `/JOIN #test p4ssw0rd`. If they try to join without the key, they will be rejected. 790 791To unset the key: 792 793 /MODE #test -k 794 795### +l - Limit 796 797This mode lets you restrict how many users can join the channel. 798 799Let's say that `#test` currently has 5 users in it, and you run this command: 800 801 /MODE #test +l 6 802 803Only one more user will be able to join the channel. If anyone tries to join the channel when there's already six people on it, they will get rejected. 804 805Just like the `+k - Key` mode, to unset the limit: 806 807 /MODE #test -l 808 809### +m - Moderated 810 811This mode lets you restrict who can speak in the channel. If the `+m` mode is enabled, normal users won't be able to say anything. Users who are Voice, Halfop, Channel-Op, Admin and Founder will be able to talk. 812 813To set this mode: 814 815 /MODE #test +m 816 817To unset this mode (and let everyone speak again): 818 819 /MODE #test -m 820 821### +n - No Outside Messages 822 823This mode is enabled by default, and means that only users who are joined to the channel can send messages to it. 824 825If this mode is unset, users who aren't on your channel can send messages to it. This can be useful with, for example, GitHub or notification bots if you want them to send messages to your channel but don't want them to clutter your channel with by joining and leaving it. 826 827### +R - Only Registered Users Can Join or Speak 828 829If this mode is set, only users that have logged into an account will be able to join and speak on the channel. If this is set and a regular, un-logged-in user tries to join, they will be rejected. 830 831Unregistered users already joined to the channel will not be kicked automatically. They will no longer be able to send messages to the channel, unless they have been voiced (+v). If they leave, they would not be allowed to rejoin. 832 833To set this mode: 834 835 /MODE #test +R 836 837To unset this mode: 838 839 /MODE #test -R 840 841### +M - Only Registered Users Can Speak 842 843If this mode is set, only users that have logged into an account will be able to speak on the channel. Unregistered users may still join the channel, unless they are restricted from doing so by another channel mode like +R. When an unregistered user tries to speak, they will be rejected. Users who have been voiced (+v) are excepted from this restriction. 844 845To set this mode: 846 847 /MODE #test +M 848 849To unset this mode: 850 851 /MODE #test -M 852 853### +s - Secret 854 855If this mode is set, it means that your channel should be marked as 'secret'. Your channel won't show up in `/LIST` or `/WHOIS`, and non-members won't be able to see its members with `/NAMES` or `/WHO`. 856 857To set this mode: 858 859 /MODE #test +s 860 861To unset this mode: 862 863 /MODE #test -s 864 865### +t - Op-Only Topic 866 867This mode is enabled by default, and means that only channel operators can change the channel topic (using the `/TOPIC` command). 868 869If this mode is unset, anyone will be able to change the channel topic. 870 871### +C - No CTCPs 872 873This mode means that [client-to-client protocol](https://tools.ietf.org/id/draft-oakley-irc-ctcp-02.html) messages other than `ACTION` (`/me`) cannot be sent to the channel. 874 875### +u - Auditorium 876 877This mode means that `JOIN`, `PART`, and `QUIT` lines for unprivileged users (i.e., users without a channel prefix like `+v` or `+o`) re not sent to other unprivileged users. In conjunction with `+m`, this is suitable for "public announcements" channels. 878 879### +U - Op-Moderated 880 881This mode means that messages from unprivileged users are only sent to channel operators (who can then decide whether to grant the user `+v`). 882 883## Channel Prefixes 884 885Users on a channel can have different permission levels, which are represented by having different characters in front of their nickname. This section explains the prefixes and what each one means. 886 887### +q (~) - Founder 888 889This prefix means that the given user is the founder of the channel. For example, if `~dan` is on a channel it means that **dan** founded the channel. The 'founder' prefix only appears on channels that are registered. 890 891Founders have complete administrative control of the channel. They can take any action and modify anyone else's privileges. 892 893### +a (&) - Admin 894 895This prefix means that the given user is an admin on the channel. For example, if `&tom` is on a channel, then **tom** is an admin on it. The 'admin' prefix only appears on channels that are registered. 896 897Admins have the same moderation privileges as channel operators (see below), but they can't be kicked or demoted by other admins or channel operators. 898 899### +o (@) - Channel Operator 900 901This prefix means that the given user is an operator on the channel (chanop, for short). For example, if `@ruby` is on a channel, then **ruby** is an op. 902 903Chanops are the default type of channel moderators. They can change the channel modes, ban/kick users, and add or remove chanop (or lower) privileges from users. 904 905### +h (%) - Halfop 906 907This prefix means that the given user is a halfop on the channel (half-operator). For example, if `%twi` is on a channel, then **twi** is a halfop. 908 909Halfops have some moderation privileges: they can kick users (but not ban them), change the channel topic, and grant voice privileges (see below). 910 911### +v (+) - Voice 912 913This prefix means that the given user is 'voiced' on the channel. For example, if `+faust` is on a channel, then **faust** is voiced on that channel. 914 915Voiced users can speak when the channel has `+m` (moderated) mode enabled. They get no other special privileges or any moderation abilities. 916 917 918-------------------------------------------------------------------------------------------- 919 920 921# Commands 922 923The best place to look for command help is on a running copy or Ergo itself! 924 925To see the integrated command help, simply spin up a copy of Ergo and then run this command: 926 927 /HELPOP <command> 928 929If that doesn't work, you may need to run this instead: 930 931 /QUOTE HELP <command> 932 933We may add some additional notes here for specific commands down the line, but right now the in-server docs are the best ones to consult. 934 935 936-------------------------------------------------------------------------------------------- 937 938 939# Working with other software 940 941Ergo should interoperate with most IRC-based software, including bots. If you have problems getting your preferred software to work with Ergo, feel free to report it to us. If the root cause is a bug in Ergo, we'll fix it. 942 943One exception is services frameworks like [Anope](https://github.com/anope/anope) or [Atheme](https://github.com/atheme/atheme); we have our own services implementations built directly into the server, and since we don't support federation, there's no place to plug in an alternative implementation. (If you are already using Anope or Atheme, we support migrating your database --- see below.) 944 945If you're looking for a bot that supports modern IRCv3 features, check out [bitbot](https://github.com/jesopo/bitbot/)! 946 947## Kiwi IRC and Gamja 948 949We recommend two web-based clients for use with Ergo: [Kiwi IRC](https://github.com/kiwiirc/kiwiirc/) and [Gamja](https://git.sr.ht/~emersion/gamja). Both clients are 100% static files (HTML and Javascript), running entirely in the end user's browser without the need for a separate server-side backend. They can connect directly to Ergo, using Ergo's support for native websockets. Both clients support Ergo's server-side history features; for a demonstration, see the Ergo testnet (click [here for Kiwi](https://testnet.ergo.chat/kiwi/) or [here for Gamja](https://testnet.ergo.chat/gamja)). 950 951For best interoperability with firewalls, you should run an externally facing web server on port 443 that can serve both the static files and the websocket path, then have it reverse-proxy the websocket path to Ergo. For example, configure the following listener in ircd.yaml: 952 953```yaml 954 "127.0.0.1:8067": 955 websocket: true 956``` 957 958then the following location block in your nginx config (this proxies only `/webirc` on your server to Ergo's websocket listener): 959 960``` 961 location /webirc { 962 proxy_pass http://127.0.0.1:8067; 963 proxy_read_timeout 600s; 964 proxy_http_version 1.1; 965 proxy_set_header Upgrade $http_upgrade; 966 proxy_set_header Connection "Upgrade"; 967 proxy_set_header X-Forwarded-For $remote_addr; 968 proxy_set_header X-Forwarded-Proto $scheme; 969 } 970``` 971 972then add the following `startupOptions` to Kiwi's `static/config.json` file (see the [Ergo testnet's config.json](https://testnet.ergo.chat/kiwi/static/config.json) for a fully functional example): 973 974``` 975 "startupOptions" : { 976 "websocket": "wss://domain.example.com/webirc", 977 "channel": "#chat", 978 "nick": "kiwi-n?" 979 }, 980``` 981 982or with Gamja, create a new `config.json` (in the base directory of the Gamja install, alongside Gamja's `index.html`) file along these lines: 983 984``` 985{ 986 "server": { 987 "url": "wss://domain.example.com/webirc", 988 "autojoin": "#chat", 989 "auth": "optional" 990 } 991} 992``` 993 994## Migrating from Anope or Atheme 995 996You can import user and channel registrations from an Anope or Atheme database into a new Ergo database (not all features are supported). Use the following steps: 997 9981. Obtain the relevant migration tool from the latest stable release: [anope2json.py](https://github.com/ergochat/ergo/blob/stable/distrib/anope/anope2json.py) or [atheme2json.py](https://github.com/ergochat/ergo/blob/stable/distrib/atheme/atheme2json.py) respectively. 9991. Make a copy of your Anope or Atheme database file. (You may have to stop and start the services daemon to get it to commit all its changes.) 10001. Convert the database to JSON, e.g., with `python3 ./anope2json.py anope.db output.json` 10011. Copy your desired Ergo config to `./ircd.yaml` (make any desired edits) 10021. Run `ergo importdb ./output.json` 10031. Run `ergo mkcerts` if necessary to generate self-signed TLS certificates 10041. Run `ergo run` to bring up your new Ergo instance 1005 1006## Hybrid Open Proxy Monitor (HOPM) 1007 1008[hopm](https://github.com/ircd-hybrid/hopm) can be used to monitor your server for connections from open proxies, then automatically ban them. To configure hopm to work with Ergo, add operator blocks like this to your Ergo config file, which grant hopm the necessary privileges: 1009 1010````yaml 1011# operator classes 1012oper-classes: 1013 # hopm 1014 "hopm": 1015 # title shown in WHOIS 1016 title: Proxy Monitor 1017 1018 # capability names 1019 capabilities: 1020 - "kill" 1021 - "ban" 1022 - "nofakelag" 1023 1024# ircd operators 1025opers: 1026 # operator named 'hopm' 1027 hopm: 1028 # which capabilities this oper has access to 1029 class: "hopm" 1030 1031 # custom hostname 1032 vhost: "proxymonitor.hopm" 1033 1034 # modes are the modes to auto-set upon opering-up 1035 modes: +is c 1036 1037 # password to login with /OPER command 1038 # generated using "ergo genpasswd" 1039 password: "$2a$04$JmsYDY6kX3/wwyK3ao0L7.aGJEto0Xm4DyL6/6zOmCpzeweIb8kdO" 1040```` 1041 1042Then configure hopm like this: 1043 1044```` 1045/* ergo */ 1046connregex = ".+-.+CONNECT.+-.+ Client Connected \\[([^ ]+)\\] \\[u:([^ ]+)\\] \\[h:([^ ]+)\\] \\[ip:([^ ]+)\\] .+"; 1047 1048/* A DLINE example for ergo */ 1049kline = "DLINE ANDKILL 2h %i :Open proxy found on your host."; 1050```` 1051 1052## Tor 1053 1054Ergo has code support for adding an .onion address to an IRC server, or operating an IRC server as a Tor onion service ("hidden service"). This is subtle, so you should be familiar with the [Tor Project](https://www.torproject.org/) and the concept of an [onion service](https://www.torproject.org/docs/tor-onion-service.html.en). 1055 1056There are two possible ways to serve Ergo over Tor. One is to add a .onion address to a server that also serves non-Tor clients, and whose IP address is public information. This is relatively straightforward. Add a separate listener, for example `127.0.0.2:6668`, to Ergo's `server.listeners`, then configure it with `tor: true`. Then configure Tor like this: 1057 1058```` 1059HiddenServiceDir /var/lib/tor/ergo_hidden_service 1060HiddenServicePort 6667 127.0.0.2:6668 1061 1062# these are optional, but can be used to speed up the circuits in the case 1063# where the server's own IP is public information (clients will remain anonymous): 1064HiddenServiceNonAnonymousMode 1 1065HiddenServiceSingleHopMode 1 1066```` 1067 1068Tor provides end-to-end encryption for onion services, so there's no need to enable TLS in Ergo for the listener (`127.0.0.2:6668` in this example). Doing so is not recommended, given the difficulty in obtaining a TLS certificate valid for an .onion address. 1069 1070The second way is to run Ergo as a true hidden service, where the server's actual IP address is a secret. This requires hardening measures on the Ergo side: 1071 1072* Ergo should not accept any connections on its public interfaces. You should remove any listener that starts with the address of a public interface, or with `:`, which means "listen on all available interfaces". You should listen only on `127.0.0.1:6667` and a Unix domain socket such as `/hidden_service_sockets/ergo_tor_sock`. 1073* In this mode, it is especially important that all operator passwords are strong and all operators are trusted (operators have a larger attack surface to deanonymize the server). 1074* Onion services are at risk of being deanonymized if a client can trick the server into performing a non-Tor network request. Ergo should not perform any such requests (such as hostname resolution or ident lookups) in response to input received over a correctly configured Tor listener. However, Ergo has not been thoroughly audited against such deanonymization attacks --- therefore, Ergo should be deployed with additional sandboxing to protect against this: 1075 * Ergo should run with no direct network connectivity, e.g., by running in its own Linux network namespace. systemd implements this with the [PrivateNetwork](https://www.freedesktop.org/software/systemd/man/systemd.exec.html) configuration option: add `PrivateNetwork=true` to Ergo's systemd unit file. 1076 * Since the loopback adapters are local to a specific network namespace, and the Tor daemon will run in the root namespace, Tor will be unable to connect to Ergo over loopback TCP. Instead, Ergo must listen on a named Unix domain socket that the Tor daemon can connect to. However, distributions typically package Tor with its own hardening profiles, which restrict which sockets it can access. Below is a recipe for configuring this with the official Tor packages for Debian: 1077 10781. Create a directory with `0777` permissions such as `/hidden_service_sockets`. 10791. Configure Ergo to listen on `/hidden_service_sockets/ergo_tor_sock`, with `tor: true`. 10801. Ensure that Ergo has no direct network access as described above, e.g., with `PrivateNetwork=true`. 10811. Next, modify Tor's apparmor profile so that it can connect to this socket, by adding the line ` /hidden_service_sockets/** rw,` to `/etc/apparmor.d/local/system_tor`. 10821. Finally, configure Tor with: 1083 1084```` 1085HiddenServiceDir /var/lib/tor/ergo_hidden_service 1086HiddenServicePort 6667 unix:/hidden_service_sockets/ergo_tor_sock 1087# DO NOT enable HiddenServiceNonAnonymousMode 1088```` 1089 1090Instructions on how client software should connect to an .onion address are outside the scope of this manual. However: 1091 10921. [Hexchat](https://hexchat.github.io/) is known to support .onion addresses, once it has been configured to use a local Tor daemon as a SOCKS proxy (Settings -> Preferences -> Network Setup -> Proxy Server). 10931. Pidgin should work with [torsocks](https://trac.torproject.org/projects/tor/wiki/doc/torsocks). 1094 1095 1096## ZNC 1097 1098ZNC 1.6.x (still pretty common in distros that package old versions of IRC software) has a [bug](https://github.com/znc/znc/issues/1212) where it fails to recognize certain SASL messages. Ergo supports a compatibility mode that works around this to let ZNC complete the SASL handshake: this can be enabled with `server.compatibility.send-unprefixed-sasl`. 1099 1100Ergo can emulate certain capabilities of the ZNC bouncer for the benefit of clients, in particular the third-party [playback](https://wiki.znc.in/Playback) module. This enables clients with specific support for ZNC to receive selective history playback automatically. To configure this 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". Other clients with support are listed on ZNC's wiki page. 1101 1102## External authentication systems 1103 1104Ergo can be configured to call arbitrary scripts to authenticate users; see the `auth-script` section of the config. The API for these scripts is as follows: Ergo will invoke the script with a configurable set of arguments, then send it the authentication data as JSON on the first line (`\n`-terminated) of stdin. The input is a JSON dictionary with the following keys: 1105 1106* `accountName`: during passphrase-based authentication, this is a string, otherwise omitted 1107* `passphrase`: during passphrase-based authentication, this is a string, otherwise omitted 1108* `certfp`: during certfp-based authentication, this is a string, otherwise omitted 1109* `peerCerts`: during certfp-based authentication, this is a list of the PEM-encoded peer certificates (starting from the leaf), otherwise omitted 1110* `ip`: a string representation of the client's IP address 1111 1112The script must print a single line (`\n`-terminated) to its output and exit. This line must be a JSON dictionary with the following keys: 1113 1114* `success`, a boolean indicating whether the authentication was successful 1115* `accountName`, a string containing the normalized account name (in the case of passphrase-based authentication, it is permissible to return the empty string or omit the value) 1116* `error`, containing a human-readable description of the authentication error to be logged if applicable 1117 1118Here is a toy example of an authentication script in Python that checks that the account name and the password are equal (and rejects any attempts to authenticate via certfp): 1119 1120``` 1121#!/usr/bin/python3 1122 1123import sys, json 1124 1125raw_input = sys.stdin.readline() 1126input = json.loads(raw_input) 1127account_name = input.get("accountName") 1128passphrase = input.get("passphrase") 1129success = bool(account_name) and bool(passphrase) and account_name == passphrase 1130print(json.dumps({"success": success})) 1131``` 1132 1133Note that after a failed script invocation, Ergo will proceed to check the credentials against its local database. 1134 1135## DNSBLs and other IP checking systems 1136 1137Similarly, Ergo can be configured to call arbitrary scripts to validate user IPs. These scripts can either reject the connection, or require that the user log in with SASL. In particular, we provide an [oragono-dnsbl](https://github.com/oragono/oragono-dnsbl) plugin for querying DNSBLs. 1138 1139The API is similar to the auth-script API described above (one line of JSON in, one line of JSON out). The input is a JSON dictionary with the following keys: 1140 1141* `ip`: the IP in a standard human-readable notation, e.g., `1.1.1.1` or `2001::0db8` 1142 1143The output is a JSON dictionary with the following keys: 1144 1145* `result`: an integer indicating the result of the check (1 for "accepted", 2 for "banned", 3 for "SASL required") 1146* `banMessage`: a message to send to the user indicating why they are banned 1147* `error`, containing a human-readable description of the authentication error to be logged if applicable 1148 1149-------------------------------------------------------------------------------------------- 1150 1151 1152# Acknowledgements 1153 1154Ergo's past and present maintainers and core contributors are: 1155 1156* Jeremy Latt (2012-2014) 1157* Edmund Huber (2014-2015) 1158* Daniel Oaks (2016-present) 1159* Shivaram Lingamneni (2017-present) 1160 1161In addition, Ergo has benefited tremendously from its community of contributors, users, and translators, not to mention collaborations with the wider IRCv3 community. There are too many people to name here --- but we try to credit people for individual contributions in the changelog, please reach out to us if we forgot you :-) 1162