Upgrading from 3.2.x

From UnrealIRCd documentation wiki
Jump to: navigation, search
Other languages:

This page describes most of the changes in the configuration changes between UnrealIRCd 3.2.x and UnrealIRCd 4. You may also be interested in What's new in UnrealIRCd 4 or Running a mixed UnrealIRCd 3.2 and UnrealIRCd 4 network.

If you are upgrading from 3.2.x to 4.x then there are three important things to know:
1) New file locations
In UnrealIRCd 4 the location of the configuration files and other files have been changed. On *NIX the directory where you compile the IRCd from (previously 'Unreal3.2.X', now 'unrealircd-4.0.0') is no longer the same as the directory where the IRCd will be running from.
By default the IRCd is installed to /home/yourusername/unrealircd on *NIX. On Windows UnrealIRCd will install to C:\Program Files (x86\UnrealIRCd 4.
The new directory structure is as follows (both on Windows and *NIX):
conf/ contains all configuration files
logs/ for log files
modules/ all modules (.so files on *NIX, .dll files on Windows)

2) Configuration file changes
There have also been changes in various configuration blocks and settings. Don't worry, 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, read UnrealIRCd files and directories)
  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.

3) Third party modules
If you are using 3rd party modules (modules not developed by the UnrealIRCd team) then they will require an update before they can run on UnrealIRCd 4. Contact your developer for a new version or ask on our Modules forum where someone may be kind enough to convert the module for you if you ask nicely. Due to the many core changes in UnrealIRCd 4 it was simply impossible to make 3.2.x modules work out-of-the-box on 4.x as well.

4) Optional reading
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 commands.so & cloak.so (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/third/somemodule.so";
    You should now use:
    loadmodule "third/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: help.es.conf is help/help.es.conf)
  • 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 Tutorial: Linking servers 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 irc1.some.net; /* may also be an IP */
        port 6697; /* or move the hostname & ip into one item ? irc1.some.net:6697 */
        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 blah.dyndns.org) 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 {
        vhost some.host.name;
        from { userhost { *@*; }; };
        login "test";
        password "xyz";

Is now:

vhost {
        vhost some.host.name;
        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; };