Featured image of post Hosting a Ergo IRC Server
Hosting

Hosting a Ergo IRC Server

A step-by-step guide on how to host your own private Ergo IRC server.

A step-by-step guide on how to host your own private Ergo IRC server.

Getting a TLS Certificate

Start by enquireing a TLS certificate for your domain. You can use Let’s Encrypt to obtain a free TLS certificate. But for this guide we will use certbot to obtain a certificate for the domain irc.ha1fdan.xyz:

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

sudo apt-get update
sudo apt-get install certbot
certbot certonly --manual --preferred-challenges dns -d irc.ha1fdan.xyz
# Follow the instructions to create a DNS TXT record for domain verification.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Press Enter to Continue

Successfully received certificate.
Certificate is saved at: /etc/letsencrypt/live/irc.ha1fdan.xyz/fullchain.pem
Key is saved at:         /etc/letsencrypt/live/irc.ha1fdan.xyz/privkey.pem
This certificate expires on 2026-08-20.
These files will be updated when the certificate renews.

Great! Now you have your TLS certificate ready. Next, let’s set up the Ergo IRC server.

Installing Ergo

Download the latest release of Ergo from the official GitHub repository:

1
2
3

wget https://github.com/ergochat/ergo/releases/download/v2.18.0/ergo-2.18.0-linux-x86_64.tar.gz
tar -xzf ergo-2.18.0-linux-x86_64.tar.gz
cd ergo-2.18.0-linux-x86_64

Create a configuration file for Ergo. You can use the provided example configuration as a starting point:

1
2

cp default.yaml ircd.yaml
nano ircd.yaml

Key things to configure in ircd.yaml:

 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
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51

# network configuration
network:
    # name of the network
    name: irc.ha1fdan.xyz


# server configuration
server:
    # server name
    name: irc.ha1fdan.xyz

    # addresses to listen on
    listeners:
        # The standard plaintext port for IRC is 6667. Allowing plaintext over the
        # we recommend using plaintext only on local (loopback) interfaces:
        "127.0.0.1:6667": # (loopback ipv4, localhost-only)
        "[::1]:6667":     # (loopback ipv6, localhost-only)
        ":6697":
            tls:
                cert: /etc/letsencrypt/live/irc.ha1fdan.xyz/fullchain.pem
                key: /etc/letsencrypt/live/irc.ha1fdan.xyz/privkey.pem
            proxy: false
            min-tls-version: 1.2
    
    lookup-hostnames: false
    ip-cloaking:
        # whether to enable IP cloaking
        enabled: true
        enabled-for-always-on: true

        # fake TLD at the end of the hostname, e.g., pwbs2ui4377257x8.irc
        # you may want to use your network name here
        netname: "irc.ha1fdan.xyz"

# account options
accounts:
    authentication-enabled: true
    registration:
        enabled: true # temporarily
        allow-before-connect: false
    require-sasl:
        enabled: false # temporarily


channels:
    default-modes: +ntC
    max-channels-per-client: 100
    operator-only-creation: true
    registration:
        enabled: true
        operator-only: true

You are free to customize the configuration further based on your needs.

Running Ergo

Now you can start the Ergo server:

1
2
3
4
5
6
7
8
9

root@v2202605360721462163:~/ergo-2.18.0-linux-x86_64# ./ergo run --conf ircd.yaml
2026-05-22T18:23:53.456Z : info  : server     : ergo-2.18.0 starting
2026-05-22T18:23:53.456Z : info  : server     : Using config file : ircd.yaml
2026-05-22T18:23:53.457Z : info  : server     : Using datastore : ircd.db
2026-05-22T18:23:53.457Z : info  : server     : Proxied IPs will be accepted from : localhost
2026-05-22T18:23:53.458Z : info  : listeners  : now listening on 127.0.0.1:6667, tls=false, proxy=false, tor=false, websocket=false.
2026-05-22T18:23:53.458Z : info  : listeners  : now listening on [::1]:6667, tls=false, proxy=false, tor=false, websocket=false.
2026-05-22T18:23:53.458Z : info  : listeners  : now listening on :6697, tls=true, proxy=false, tor=false, websocket=false.
2026-05-22T18:23:53.458Z : info  : server     : Server running

Congratulations! Your Ergo IRC server is now up and running.

Creating an Operator Account

To create an operator account, you can use the ergo command-line tool:

1
2
3
4
5
6

root@v2202605360721462163:~/ergo-2.18.0-linux-x86_64# ./ergo genpasswd
Enter Password: 
Reenter Password: 
$2a$04$m9jqEeLfr85Bq2tdEH2PO.JyZaEpcO7VfDAHyq0ZHntQqn5WcqLWu

nano ircd.yaml

Add the generated password hash to the opers section of your ircd.yaml configuration file:

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

opers:
    # default operator named 'admin'; log in with /OPER admin <password>
    admin:
        # which capabilities this oper has access to
        class: "server-admin"

        # traditionally, operator status is visible to unprivileged users in
        # WHO and WHOIS responses. this can be disabled with 'hidden'.
        hidden: true

        # custom whois line (if `hidden` is enabled, visible only to other operators)
        whois-line: is the server administrator
        # custom hostname (ignored if `hidden` is enabled)
        #vhost: "staff"
        password: "$2a$04$0123456789abcdef0123456789abcdef0123456789abcdef01234"

After saving the configuration file, restart the Ergo server to apply the changes:

1

./ergo run --conf ircd.yaml

Now you can log in as an operator using the admin username and the password you set. Once logged in, we will create a account for ourselves and give it operator privileges.

Creating a User Account

To create a user account, you can use the NICKSERV REGISTER command in your IRC client:

1

/NICKSERV REGISTER <password> <email>

Then in your logs you should see something like this:

1
2

2026-05-22T18:38:22.180Z : info  : accounts   : client : ha1fdan : registered account : ha1fdan
2026-05-22T18:38:22.180Z : info  : accounts   : s00001 : ha1fdan : logged into account : ha1fdan

Now re-enable require-sasl and disable registration again in ircd.yaml:

1
2
3
4
5

accounts:
  registration:
    enabled: false
  require-sasl:
    enabled: true

Permanently Running Ergo

To run Ergo permanently, you can use a process manager like systemd. Create a new service file for Ergo:

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

sudo nano /etc/systemd/system/ergo.service

[Unit]
Description=Ergo IRC Server
After=network.target

[Service]
ExecStart=/opt/ergo/ergo run --conf /opt/ergo/ircd.yaml
WorkingDirectory=/opt/ergo
User=ergo
Group=ergo
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Save the file and exit. Then create a user and group for Ergo:

1

sudo useradd -r -s /bin/false ergo

And move the Ergo files to /opt/ergo:

1
2
3

sudo mkdir /opt/ergo
sudo mv ~/ergo-2.18.0-linux-x86_64/* /opt/ergo/
sudo chown -R ergo:ergo /opt/ergo

The ergo user can’t read the Let’s Encrypt certs - they’re root-only by default. Fix it by adding the ergo user to a ssl-cert group:

1
2
3
4

groupadd ssl-cert
usermod -aG ssl-cert ergo
chown -R root:ssl-cert /etc/letsencrypt/live/ /etc/letsencrypt/archive/
chmod -R 750 /etc/letsencrypt/live/ /etc/letsencrypt/archive/

Operator user setup

Since we just created our user account, in my case ha1fdan. A simple way to do this is by simply changeing the default operator (admin) to ha1fdan in the opers section of ircd.yaml:

1
2
3
4
5
6

# ircd operators
opers:
    # default operator named 'admin'; log in with /OPER admin <password>
    ha1fdan:
        # which capabilities this oper has access to
        class: "server-admin"

Starting Ergo as a Service

Finally, enable and start the Ergo service:

1
2
3

sudo systemctl daemon-reload
sudo systemctl enable ergo
sudo systemctl start ergo

Logging in to the IRC Server

You can now connect to your IRC server using an IRC client. Use the following settings:

  • Server: irc.ha1fdan.xyz
  • Port: 6697
  • Use TLS: Yes
  • Nickname: Your desired nickname
  • Username: Your desired username (this must be the username you registered with NickServ)
  • Real Name: Your desired real name
  • Login method: SASL PLAIN (Username + password)
  • Password: The password you set when registering with NickServ

Once connected, you can use the following commands to interact with the server:

  • /OPER ha1fdan <password>: Log in as an operator (replace <password> with the operator password you set in ircd.yaml)
  • /JOIN #channel: Join a channel (replace #channel with the name of the channel you want to join)
  • /CHANSERV REGISTER <channel> <password>: Register a channel (replace <channel> with the name of the channel you want to register and <password> with a password for the channel. Password is optional but recommended for channel security.)
  • /MSG <nickname> <message>: Send a private message to another user (replace <nickname> with the recipient’s nickname and <message> with your message)
  • /WHOIS <nickname>: Get information about a user (replace <nickname> with the nickname of the user you want to look up)
  • /QUIT: Disconnect from the server

Create an account for your friend

To create an account for your friend, you as an operator must first log in using the /OPER command. Then you can use the following command to create an account for your friend:

1
2

/OPER ha1fdan <password>
/NICKSERV SAREGISTER <username> <password>

They can change their password after logging in with:

1

/NICKSERV PASSWD <oldpassword> <newpassword>

“Delete” an account

To “delete”/deactivate an account, you can use the following command:

1

/NICKSERV SUSPEND ADD <username> [DURATION duration] [reason]

This will suspend the account, preventing the user from logging in. You can specify a duration for the suspension or leave it indefinite. To remove the suspension, use:

1

/NICKSERV SUSPEND DEL <username>

If you want to completely remove the account and all its data, you can use:

1

/NICKSERV ERASE <username>

This erases all records of an account, allowing reuse of the username.

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

© 2026 · Ha1fdan · 0xD