Hosting a Ergo IRC Server

This is part 2 of the Ergo IRC server guide. In part 1 we set up the server, obtained a TLS certificate, and created our operator account. In this part we will lock down the server, set up invite-only channels, configure account management, and write a custom MOTD.

Locking Down the Server

By default, Ergo allows anyone to connect and create channels. For a private server we want to restrict this. The key settings in ircd.yaml are:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


accounts:
    registration:
        enabled: true           # allow self-registration
        allow-before-connect: false
    require-sasl:
        enabled: false          # don't force SASL — users identify after connecting

channels:
    default-modes: +ntCi        # +i makes ALL new channels invite-only by default
    operator-only-creation: true # only operators can create channels
    registration:
        enabled: true
        operator-only: true

With this setup:

Anyone can connect and register an account
All channels are invite-only by default (+i)
Only you (the operator) can create new channels
Users land on the server but can’t join anything without your invite

Reload the config without restarting:

1

/REHASH

Nick Reservation

Ergo enforces nick reservation strictly by default. This means if a user has a registered account, nobody else can use their nick — and without logging in first, they’ll be renamed on connect.

The recommended login method is SASL PLAIN, configured in the IRC client:

Login method: SASL PLAIN
Username: their account name
Password: their account password

Without SASL, users can still identify manually after connecting:

1

/ns identify <username> <password>

Invite-Only Channels

To make #main permanently invite-only and add users to the exception list so they can join without a live invite from you:

1
2


/MODE #main +i
/MODE #main +I username

The +I exception list lets trusted users join anytime, even when you’re offline. To view the current list:

1

/MODE #main +I

1

/CHANSERV REGISTER #main

Managing Accounts via the HTTP API

Ergo 2.18 includes a built-in HTTP API. Enable it in ircd.yaml:

1
2
3
4
5


api:
    enabled: true
    listener: "127.0.0.1:8089"
    bearer-tokens:
        - "your-secret-token-here"  # generate with: ./ergo gentoken

Useful API calls:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


# List all accounts
curl -X POST \
  -H "Authorization: Bearer <token>" \
  http://127.0.0.1:8089/v1/ns/list

# Reset a user's password
curl -X POST \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"accountName": "username", "passphrase": "newpassword"}' \
  http://127.0.0.1:8089/v1/ns/passwd

# Register a new account
curl -X POST \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"accountName": "username", "passphrase": "password"}' \
  http://127.0.0.1:8089/v1/ns/saregister

Note that the API does not support account deletion — use /NICKSERV SUSPEND ADD <username> to disable accounts instead.

Custom MOTD

Ergo supports formatting codes in the MOTD when motd-formatting: true is set in ircd.yaml. The codes are:

$b — bold
$i — italic
$c03 — color (green), $c07 — grey, $c11 — cyan, $c — reset color

Edit ergo.motd and add your own message. Here is the one used on this server:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34


 /$$   /$$             /$$    /$$$$$$      /$$                    
| $$  | $$           /$$$$   /$$__  $$    | $$                    
| $$  | $$  /$$$$$$ |_  $$  | $$  \__//$$$$$$$  /$$$$$$  /$$$$$$$
| $$$$$$$$ |____  $$  | $$  | $$$$   /$$__  $$ |____  $$| $$__  $$
| $$__  $$  /$$$$$$$  | $$  | $$_/  | $$  | $$  /$$$$$$$| $$  \ $$
| $$  | $$ /$$__  $$  | $$  | $$    | $$  | $$ /$$__  $$| $$  | $$
| $$  | $$|  $$$$$$$ /$$$$$$| $$    |  $$$$$$$|  $$$$$$$| $$  | $$
|__/  |__/ \_______/|______/|__/     \_______/ \_______/|__/  |__/

$b$c03Private • Invite-only • Encrypted$c$b

$c07─────────────────────────────────────────$c
  $bThis server is private.$b
  You are here because someone trusts you.
  Keep it that way.
$c07─────────────────────────────────────────$c

  $c11Network$c  irc.ha1fdan.xyz
  $c11Port$c     6697 (TLS only)
  $c11Auth$c     Account required

$c07─────────────────────────────────────────$c

  $bNew here?$b Register an account:
  $c11/msg NickServ REGISTER <password> <email>$c

  $bReturning?$b Log in with:
  $c11/ns identify <username> <password>$c
  $iOr set$i $bLogin method$b $ito$i $c11SASL PLAIN$c $iin your client$i
  $ito keep your nick automatically.$i

$c07─────────────────────────────────────────$c
  $iNeed help or an invite? /msg ha1fdan$i
$c07─────────────────────────────────────────$c

Note: The $ signs in ASCII art logos will be interpreted as formatting codes. Either escape them as $$ or disable motd-formatting if you use ASCII art with $ characters.

Reload the MOTD without restarting:

1

/REHASH

Documentation

For more detailed information on configuring and using Ergo, please refer to the official documentation: https://github.com/ergochat/ergo/blob/master/docs/MANUAL.md