Upgrading from UnrealIRCd 4.x to UnrealIRCd 5.x is really easy, there are almost no configuration changes needed!

If you have more than 1 server and you will have some servers on 4.x and some on 5.x, then be sure to read the important recommendations in Running a mixed UnrealIRCd 4 and UnrealIRCd 5 network.

Important recommendations

We only have three important recommendations:

1. No UnrealIRCd 3.2.x. There can be no UnrealIRCd 3.2.x server on your network. This shouldn't be a problem since 3.2.x was deprecated many years ago.
2. Use up to date services! If you use Services then upgrade these to the latest version and use the latest protocol module (usually called "unreal4"). Yes, even if the server that services links to is still on 4.x then you must still upgrade services. We currently tested and support anope 2.0.9 or higher or atheme 7.2.9 or higher.
3. Don't run a mixed network too long. We don't recommend running a mixed network for multiple months. This is because as long as you run a mixed UnrealIRCd 4 - UnrealIRCd 5 network you'll encounter a number of issues. These can only be resolved by running a true 100% UnrealIRCd 5 network.

Issues

Below you can read all details about the user-visible issues that you may run into when your network is partially 4.x and partially 5.x.

Summary: as long as you run a mixed U4-U5 network some things won't work at all, while other things may work only partially, in particular channel-related things. It is not fatal and it will not cause a crash, but it can be confusing and annoying. That's why you don't want to run a mixed-U4-U5-network for too long.

Functionality that works fine

Some U5 functionality should cause zero problems, even network-wide when the new U5 server is linked they can immediately be useful for your U4 network:

• Storing of *LINES and spamfilters via the tkldb module (loaded by default in U5)
• Storing of Permanent channels (+P) via the channeldb module (loaded by default in U5)

Missing functionality on U4 servers

This is the most obvious one: new functionality for users in UnrealIRCd 5 will not work on your UnrealIRCd 4 servers. This ranges from the various new IRCv3 features, channel history, server ban exceptions (/ELINE), etc.

There can also be functionality that is half-working, which is usually more confusing, see next section.

Functionality that works partially on U5 servers which can be confusing

Channel modes have been added (eg: +H) or have been changed (eg: +f with subtype r for repeats). These features may be broken or only working partially if you run a mixed U4-U5 network.

History may be half-working

For example, if you have 4x U4 servers and 1x U5 server and enable chat history with MODE #channel +H 15:1440 then chat history will be played back only on the U5 server. Everyone will understand that. However, depending on channel membership and your linking topology, in a mixed U4-U5 network you may also be missing channel history from certain people while still seeing playback for other people. In the last 15 lines of history playback you may see Person1 talking, but Person2 from a 'far server' is not shown. This may look rather odd when you see the channel history.

New channel modes will not spread well

Similarly, channel modes may not be spreading well if you set the new +H or +f with thew new subtype 'r'. Any U4 server in the path (linking topology) will block or alter such requests. So if you have a toplogy of: U5--U4 hub--U5 then the other U5 server will not see the MODE change properly.

Cannot join channels containing non-UTF8 characters

By default in UnrealIRCd 5 channel names may only contain valid UTF8 characters (set::allowed-channelchars). If you have some very old clients using for example Russian/Cyrillic windows-1251 codepage instead of UTF8 then this means those channels can't be joined on UnrealIRCd 5. It is recommended to tell these users to upgrade their client and use UTF8. If this is not feasible then you can change the setting.

Error messages triggered on commands

Users may get receive error messages from remote 4.x servers when certain commands are used on 5.x servers. Currently the only known command that has this behavior is TAGMSG.

Functionality removed in U5, present in U4

• Spamfilters of type posix are no longer supported. They were already deprecated in later 4.x releases. Use spamfilter type regex instead.
• Extended ban ~R. So instead of using MODE #chan +e ~R:Name you should use MODE #chan +e ~a:Name

On UnrealIRCd 5 you cannot set these. Setting them on UnrealIRCd 4 servers will have no effect on users connected to UnrealIRCd 5 servers.

Services

If you use Services, then be sure to use the latest versions. In particular:

• anope (version 2.0.9 or higher) - with the "unreal4" protocol module
• atheme (version 7.2.9 or higher) - with the "unreal4" protocol module

File locations

On *NIX, all the file locations are pretty much the same. The only difference is that conf/ssl is now called conf/tls. A symlink will be created if you are upgrading an existing installation.

On Windows, it is important to note that UnrealIRCd is now 64-bit and installs to C:\Program Files\UnrealIRCd 5 instead of the old C:\Program Files (x86)\UnrealIRCd 4.

Installation / upgrading

The installation of UnrealIRCd 5 works exactly the same as installing UnrealIRCd 4. Just follow the installation procedure for *NIX or for Windows.

You can upgrade form any 5.X.X version to any 5.Y.Y version.

1. Backup your existing /home/xxx/unrealircd directory:

   cp -Rav /home/xxx/unrealircd /home/xxx/unrealircd.bak

2. Download and install latest version of UnrealIRCd.
3. Double check: make sure you ran make install as this will install all new files in /home/xxx/unrealircd.
4. Configuration test to make sure the IRCd will boot later (this will not start the ircd, it will only TEST the configuration!):

   cd /home/xxx/unrealircd

   ./unrealircd configtest

   This should print out:

   Configuration test passed OK

   If you see warnings/errors, fix them and run ./unrealircd configtest again until all issues are fixed.
5. Now you can restart the IRCd so it uses the new version:

   cd /home/xxx/unrealircd

   ./unrealircd restart

ERROR: Upgrade failed

If the ./unrealircd upgrade script gives this error then it can mean various things. Try to read the error messages above it, see if you can fix these.

If you can't fix it then simply don't use ./unrealircd upgrade and go for the manual upgrade method

Allow block uses allow::mask nowadays

In UnrealIRCd 5.2.1 and later we have changed the allow block slightly.

Instead of allow::ip and allow::hostname we now use allow::mask, so we use the same type of match blocks everywhere in the config.

Simply edit your configuration file and change ip (or hostname) to mask.

So, change:

allow {
        ip *@*;
        class clients;
        maxperip 3;
}

To:

allow {
        mask *@*;
        class clients;
        maxperip 3;
}

Configuration changes

Your UnrealIRCd 4.x configuration file will work fine on 5.x.

There are 2 major changes that will raise a warning only (the IRC server will start up fine, though):

• The except tkl { } block is now called except ban { }. Solution: simply rename except tkl to except ban in your configuration files. See Except ban block#UnrealIRCd 5 if you want more information.
• The setting set::oper-only-stats is removed, we now have set::allow-user-stats which does the inverse. Solution: simply delete your oper-only-stats line from the configuration, most likely you don't need it.

We suggest you install the latest and supported version of UnrealIRCd 6

Third party modules

If you do have 3rd party modules then be advised that all modules for 4.x need to be updated for use with UnrealIRCd 5.x.

Many 3rd party modules have been updated and added to the public 3rd party modules repository. With the help of the new Module manager you can install the modules with one simply command!

Check our tutorial that explain how to Install UnrealIRCd modules