IRC Guides · Servers

Link UnrealIRCd servers

Advanced · about 30 min read

This guide follows the official UnrealIRCd wiki: Tutorial: Linking servers. Goal: a secure multi-server network. Linking Anope is covered separately — see Linking UnrealIRCd with Anope and our Anope guide.

You need at least one working server first: Install UnrealIRCd.

Step 1 — Dedicated server port

Clients already use 6667 / 6697. Server-to-server traffic should use a separate SSL port marked serversonly:

listen *:6900 { options { ssl; serversonly; }; };

On a shell with a fixed IP you may need:

listen 1.2.3.4:6900 { options { ssl; serversonly; }; };

Open 6900 (or your chosen port) on the firewall as well. The example config often already includes this.

Step 2 — Server class

class servers
{
    pingfreq 60;
    connfreq 15;
    maxclients 10;
    sendq 20M;
};

connfreq controls how often autoconnect is retried (here every 15 seconds). The example configuration usually contains this block already.

Step 3 — SPKI fingerprint of each server

UnrealIRCd authenticates links with an SPKI fingerprint of each server’s TLS certificate — not a shared password string in the old sense.

On *NIX, from your UnrealIRCd install directory:

./unrealircd spkifp

Example output:

The SPKI fingerprint for certificate .../server.cert.pem is:
AHMYBevUxXKU/S3pdBSjXP4zi4VOetYQQVJXoNYiBR0=

You normally add this password on the other side of the link as:
password "AHMYBevUxXKU/S3pdBSjXP4zi4VOetYQQVJXoNYiBR0=" { spkifp; };

On Windows:

cd C:\Program Files\UnrealIRCd 6\bin
unrealircdctl spkifp

Run this on both servers and write down each fingerprint. You will put the peer’s fingerprint in your local link block (a common mistake is inserting your own).

Step 4 — Link blocks

Example names from the official tutorial: alpha.test.net and beta.test.net. Replace with your real server names.

On alpha.test.net (link to beta)

link beta.test.net {
    incoming {
        mask *;
    };
    outgoing {
        bind-ip *; /* or a specific IP on restricted shells */
        hostname beta.test.net; /* or IP / dynamic DNS name */
        port 6900;
        options { ssl; };
    };
    password "SPKI-FINGERPRINT-OF-BETA=" { spkifp; };
    hub *;
    class servers;
};

On beta.test.net (link to alpha)

link alpha.test.net {
    incoming {
        mask *;
    };
    outgoing {
        bind-ip *;
        hostname alpha.test.net;
        port 6900;
        options { ssl; autoconnect; };
    };
    password "SPKI-FINGERPRINT-OF-ALPHA=" { spkifp; };
    hub *;
    class servers;
};

autoconnect on beta makes beta try to connect to alpha every class::connfreq seconds. You can autoconnect the other way instead; autoconnecting from both sides is generally not recommended.

Step 5 & 6 — Rehash and link

1. Rehash both servers (as IRCOp: /REHASH), or restart if the server is empty.
2. Fix any config errors before continuing.
3. With autoconnect, servers should link within about one connfreq interval.
4. Check the map: /MAP
5. To force a link now: /CONNECT name.of.other.server

IRCOps see link attempts and errors in real time. If linking fails, use Unreal’s troubleshooting section on the same tutorial page.

Step 7 & 8 — Optional hardening

Restrict by IP

Instead of mask *; in incoming, limit who may link:

incoming {
    mask { ip 1.2.3.4; };
    /* or: mask { ip 1.2.*; }; */
};

This limits damage if config or keys leak.

Preferred hub / topology

On networks with more than two servers, leafs can prefer a primary hub then fall back:

set {
    server-linking {
        autoconnect-strategy sequential-fallback;
    }
}

link::hub and link::leaf can restrict whether a peer may introduce further servers (true “leaf” behaviour). Most small networks (two servers + services) skip this.