How to Upgrade from UnrealIRCD 3 to UnrealIRCd 4

July 18, 2016

UnrealIRCd can convert your existing 3.2.x configuration files to the UnrealIRCd 4 format:

  1. Copy your 3.2.x unrealircd.conf (and related files, if any) to your conf directory (Never heard of the conf/ directory? It’s new in UnrealIRCd 4.
  2. Then to upgrade your configuration files:
    1. On *NIX run ./unrealircd upgrade-conf
    2. On Windows just launch UnrealIRCd and after you see the list of configuration errors click OK and in next screen you will be asked if you want your configuration files to be upgraded.
  3. Then boot UnrealIRCd.

It’s as simple as that!

If you are (still) interested in specific configuration file changes between UnrealIRCd 3.2.x and UnrealIRCd 4 then see below.


There have been two major changes with regards to loading modules:

  • The “commands” module is gone and has been replaced with 150+ individual modules
  1. Remove the loadmodule lines for & (or commands.dll & cloak.dll)
  2. Add the following line to your unrealircd.conf:
    include "modules.default.conf";
  • If you have any 3rd party modules you should now use the shorter syntax which is OS-neutral. Instead of:
    loadmodule "src/modules/";

    You should now use:

    loadmodule "somemodule";

    UnrealIRCd will then figure out the exact name of the module. Also with the new directory structure you never load modules from src/ anymore, so that too is all the same on both OS’s.


While the include directive did not change, some locations of files did:

  • help.conf is now help/help.conf (translations too: is help/
  • badwords.*.conf have been removed and replaced by a single badwords.conf file

There’s one change between alpha1/2/3 and alpha4:

  • modules.conf is now called modules.default.conf

Allow block

In the allow block you now need to choose between allow::ip and allow::hostname.

Many people have something like this:

allow {
        hostname *@*;
        ip *@*;

Simply change that to just:

allow {
        ip *@*;

The allow::maxperip setting is no longer optional, it must now be set. A good setting is 2 or 3.

Me block

In your me { } block, change your “numeric” to “sid”, and change the value as follows: pick a 3 character Server ID that starts with a digit. Example:

me {
    numeric "1";


me {
    sid "001";

Link block

UnrealIRCd 4 has a new link block. We nowadays recommend linking with SSL/TLS and using SSL Fingerprints for authentication between the two servers. We have written a Linking servers Tutorial to show just that and it also shows you how to link UnrealIRCd 3.2.x with UnrealIRCd 4. Instead of trying to upgrade your existing link block we suggest following that tutorial and it’s best-practices. Yes, even if you have been linking UnrealIRCd servers for over 10 years. If you insist, though, or are just curious about what exactly changed in the link block then see below.

UnrealIRCd 3.2.x link block:

link <server-name> {
    username <usermask>;
    hostname <ipmask>;
    bind-ip <ip-to-bind-to>;
    port <port-to-connect-on>;
    password-connect <password-to-connect-with>;
    password-receive <password-to-receive> { <auth-type>; };
    hub <hub-mask>;
    leaf <leaf-mask>;
    leafdepth <depth>;
    class <class-name>;
    ciphers <ssl-ciphers>;
    options {

New block in UnrealIRCd 4:

link <server-name> {
    /* Below, often you will have both an incoming { } and outcoming { } sub-block.
     * However you may also choose to have only 1 of them if you always link in the same direction.
    incoming {
        mask 1.2.3.*;
    outgoing {
        bind-ip <ip-to-bind-to>; /* optional now */
        hostname; /* may also be an IP */
        port 6697; /* or move the hostname & ip into one item ? */
        options { ssl; autoconnect; }; /* optional, but recommended */
    password "some-password"; /* either a plaintext password that's the same for both sides or an SSL fingerprint (or certificate) */
    hub <hub-mask>; /* optional */
    leaf <leaf-mask>; /* optional */
    leaf-depth <depth>; /* optional */
    class <class-name>;
    ciphers <ssl-ciphers>; /* optional */
    options {
        quarantine; /* is a generic option. optional. */

As you can see, some directives remain the same, while others have been moved to either the incoming or outgoing section which refer to the incoming side of the link (receiving end) and the outgoing side (the one doing the outside connect) respectively. The reason for this is that the old link block was highly confusing as to whether settings applied to incoming, outgoing or both. Also, when it applied to both it actually prevented you from doing some things, such as: specifying a DNS name to connect to outgoing (eg: now link::outgoing::hostname and to still restrict the IP incoming (eg: link::incoming::mask *@93.17.*). Now you can still have an IP (mask) restriction while connecting via DNS.

Other than the incoming::mask and outgoing::hostname split (and move of other items), another major change is password. There’s now only a single password item and no longer two, as this provided very little benefit. We now recommend the use of SSL fingerprints for authentication which can be used as a password (this was also possible in 3.2.x). If you don’t want to use that and prefer to ignore our Tutorial: Linking servers then you can just set a plaintext password instead.

Finally, with the new link block a lot of it is made optional. You may leave out the whole outgoing part if you only accept the link as incoming, for example for a services link block. Similarly, you may leave out incoming if you have an outgoing block. Within the outgoing block only hostname and port are mandatory (though you probably want to enable ssl via options there as well, and possibly autoconnect). Outside incoming and/or outgoing only password and class are mandatory, all the rest is optional. If you don’t specify any of the hub or leaf options we assume hub *; (in other words: link may introduce any other servers).


Oper block

In 3.2.x IRCOp privileges are set via oper::flags. In UnrealIRCd 4 you instead use oper::operclass to refer to an Operclass block, which contains the set of privileges.

Also, oper::from::userhost is now oper::mask. Similar to the change in the Vhost block

Example 3.2.x oper block:

oper TestOper {
    from { userhost *@192.168.*; }; };
    password "test";
    flags {
    class clients;

In UnrealIRCd 4 this may look like:

oper TestOper {
    mask 192.168.*;
    password "test";
    operclass netadmin;
    swhois "a Network Administrator";
    class clients;

Above we refer to an operclass called netadmin. This netadmin operclass is defined in the operclass.default.conf shipped with UnrealIRCd 4 by default. You probably want to include this file in your unrealircd.conf like:

include "operclass.default.conf";

(similarly to how most people should load modules.default.conf)



  • spamfilter::regex is now spamfilter::mask
  • you need to explicitly set spamfilter::mask-type to one of: posix for old 3.2.x style regexes, regex for fast PCRE regexes (new in UnrealIRCd 4) or simple for ultra-fast regular matching which only supports the ? and * wildcards.

CGIIRC block

The cgiirc block has been replaced by the WebIRC block with a slightly different (and simplified) syntax.

Set block

In the Set block the following changed:

  • set::throttle has been removed and replaced by set::anti-flood::connect-flood like this:
    set { anti-flood { connect-flood 3:60; }; };

Vhost block

In the Vhost block the item vhost::from::userhost is now called vhost::mask:

vhost {
        from { userhost { *@*; }; };
        login "test";
        password "xyz";

Is now:

vhost {
        mask *@*;
        login "test";
        password "xyz";

Listen block

The Listen block was restructured. Primarily to get rid of strange brackets with IPv6.

Old syntax:

listen *:6667;
listen *:6697 { options { ssl; }; };

New syntax is:

listen {
        ip *;
        port 6667;

listen {
        ip *;
        port 6697;
        options { ssl; };


How to Upgrade UnrealIRCD 4.0.0 to UnrealIRCd 4.0.1

tar xvf unrealircd-4.0.1.tar.gz
rm -rf unrealircd-4.0.1.tar.gz
cd unrealircd-4.0.1
make install

Than go to: /home/YourUSER/unrealircd/
type: ./unrealircd restart

(and hope you dont run into any errors :D)