From UnrealIRCd documentation wiki
Jump to navigation Jump to search
This page contains changes which are not marked for translation.
Other languages:

This is the official UnrealIRCd FAQ, which aims to answer 95% of all questions asked.

This FAQ is structured into sections: it starts with general information, then answers boot problems (startup), unable to connect to the server (connect problems), and then onwards to when you have a problem but UnrealIRCd is up and running. Use the index below to find your question.

About UnrealIRCd[edit]

Is UnrealIRCd suitable for me?[edit]

UnrealIRCd is a highly advanced and customizable IRC daemon. It is used both by experts and beginners.

Of all IRC servers out there, UnrealIRCd is the most popular one (42%) if you look at the statistics from IRCStats.org. It is the most popular IRC server for both small servers and bigger servers.

Note that the top-5 networks use their own IRC software because (presumably) they want development to be under their own control and design their own network-specific features. UnrealIRCd, on the other hand, is very customizable and should be suitable for all networks. You can tweak a lot of configuration settings and load or unload modules to suit your needs, without ever needing to touch any source code. You can also load 3rd party modules from people other than the UnrealIRCd team or code one yourself (if you know C).

How many users can UnrealIRCd handle?[edit]

An IRC network running UnrealIRCd, consisting of multiple servers, can be as big as 100,000 users or more. A single UnrealIRCd server can handle 8000 local users on Linux/BSD by default.

On Windows servers we do not recommend more than 1000 locally connected users. If you need more, it's best to run UnrealIRCd on Linux or FreeBSD.

Horizontal scaling[edit]

Although the maximum number of local users a server can handle can be increased when running ./Config, it is generally recommended to spread users over multiple servers instead. This is called horizontal scaling and this is where IRC is good at.

The beauty of IRC is that you can have multiple servers linked to form 1 single IRC network. Users on the same network can see each other and chat in the same channels. The benefit of this is when 1 server goes down for whatever reason (scheduled maintenance, network outage, DDoS, server outage, etc.) users can still connect to the other servers and enjoy IRC. This is achieved by linking servers together and then using DNS RR (Round Robin) where a record like irc.example.org points to multiple IP addresses.

Recommended setup for networks[edit]

If you are planning a (medium-size or big) network then we recommend starting with 3 servers: 2 for clients with a planned maximum of 5000, and 1 server as a hub (often with Services running on it too). Then, expand when you get more users. Technically, there's no 5K limit, though, see also next section on the system specifications (CPU/RAM).

How much CPU and memory do I need?[edit]

Most of the time UnrealIRCd uses only a few percent of CPU and less than 100MB of memory. However, in case your server is attacked or flooded this may rise significantly. UnrealIRCd has a lot of countermeasures against floods and attacks but will need some power and memory during those "peak times". This is what we recommend (assuming no other major services are running at the same machine):

Locally connected users CPU (vCPU/cores) System memory
<500 1-2 512MB minimum, 1GB recommended
500-2000 1-2 2GB recommended
2000-8000 2 4GB recommended
Remotely connected users CPU (vCPU/cores) System memory
0-100000 1 512MB minimum, 1GB recommended

As you can see, the requirements highly depend on LOCALLY connected users. Remote users only use very small amounts of memory, only a few kilobytes (Kb) at most, it's almost negligible. A network, with multiple servers, can therefore be as big as 100,000 users or more. See also How many users can UnrealIRCd handle?.

CPU: As said, UnrealIRCd generally uses only a few % CPU. Probably any CPU is fine. Some people even run UnrealIRCd on a Raspberry Pi. One thing to keep in mind is that adding more than 2 CPU's is not useful, as the extra CPU's will not be utilized.

Memoryː The machine should have a minimum of 512MB, but more would be better. Note that 99% of the time >512MB memory will NOT be used! The extra memory is there only in case of a flood / server attack / network issues, in which case for a short moment memory can peak to the given figure. If you use the recommended memory values then your server can "take the hit" (DoS and DDoS) without much noticeable slowdown and without going down.

What VM plan should I pick at my provider?[edit]

If you use Amazon EC2 then their T2 series (burstable) can be a good choice. They are ideal for low CPU use cases, like UnrealIRCd, and allow short "bursts" of higher CPU if needed. The t2.micro offers 10% CPU speed with 1GB ram and can easily handle 500 users. The t2.small should be sufficient for 500-2000 users per-server (so for almost everyone).

Microsoft Azure offers something similar with their B-series (burstable virtual machines). A VM like B1s would be enough for 0-500 users and B1ms should be sufficient up to 2000 users.

Things that have a major impact on CPU/memory[edit]

If you use complex regular expressions in spamfilters then this can negatively affect performance. However, most spam filters are simple enough that you can have tens or even 100 of them without any noticeable performance impact.

The Channel history feature could have a major impact on memory usage. How high depends on the number of channels that have channel mode +H set, and their exact settings (how much history is stored).

What is the current version and when will next version be released?[edit]

The latest Stable version is 5.2.2 released on October 3, 2021. There is currently no ETA for a next 5.2.x version.

UnrealIRCd 6 is currently available as a Release Candidate with 6.0.0-rc1 released on November 27, 2021. A stable 6.0.0 release is expected in December 2021 or January 2022.

In general, we release a new stable version every 2-3 months, even if there are only minor changes. This makes sure that at least new installations benefit from recent fixes and enhancements. We always try to make clear what changed in each version so you can decide yourself if you want to upgrade or not. In case of serious issues we will be forced to release more often.

No longer supported versions[edit]

The following UnrealIRCd versions do not receive any fixes anymore, not even security fixes! If you use these, please upgrade to UnrealIRCd 5 ASAP!

About the 5.2.x series[edit]

When UnrealIRCd 5.2.0 came out, it became the direct successor to UnrealIRCd 5.0.9(.1). This means there will be no further 5.0.x releases, in particular there will never be an UnrealIRCd 5.0.10.

When 5.2.0 came out in June 2021 we told existing 5.0.x users that there was no rush to upgrade to 5.2.x. Now that we have released 5.2.2 in October 2021 this has changed. We now recommend all 5.0.x users to upgrade to 5.2.2 somewhere in the next few weeks or months. UnrealIRCd 5.2.x is stable now and working well.

The only configuration changes in 5.2.x are in the set::anti-flood block and in the allow block (the latter will only give a warning). When starting UnrealIRCd will give you clear instructions if anything needs to be changed (and what). This process is really minor, the server will usually tell you to just delete a few old lines from the configuration file. For many users it will only be a warning and not a hard error.

If you are on 5.0.9(.1) or later then try the new ./unrealircd upgrade command which makes upgrading easy.

What is new in the latest version?[edit]

Please check out the releases announcements on the forums or browse through the release notes for 5.x or 6.x.

How do I get the latest source code?[edit]

Regular downloads[edit]

Most people should use the downloads from www.unrealircd.org. Those are releases that have actually been tested by several people.

There also exists something else, which is the very latest source code from our git repository. This contains code changes committed only minutes or days ago and is considered bleeding edge. Possibly nobody has tested this code, or just one person. It may not even compile. People run this code to help UnrealIRCd development, to find bugs, or to get fixes for issues that have not been addressed in a release.

Option #1: I'm lazy, I just want a .tar.gz or zip snapshot[edit]

Go to our GitHub page. Click on the green button Clone or download and select Download ZIP.

Option #2: The 'real way' to get the latest bleeding edge source...[edit]

This describes how to 'checkout' the repository on your machine, which allows you to easily pull in updates (which happen every day/week). First, run:

git clone https://github.com/unrealircd/unrealircd.git

This will create a directory 'unrealircd' with all the source code (UnrealIRCd 5 by default, see later).

If you have already done that, and - after a few days - you want to pull in the latest changes then run the following in your unrealircd directory:

git pull

git: command not found[edit]

If you get something like git: command not found then you need to install git, so: apt install git / yum install git.


Where is the documentation[edit]

The UnrealIRCd documentation is located here.

Where can I get online support?[edit]

I found a bug or have a feature suggestion[edit]

If you have a feature suggestion or found a bug (or even crashed) then please report it on https://bugs.unrealircd.org/. This process only takes a couple of minutes!

We use bug tracker software so we don't loose track of bugs and feature requests. PLEASE report it there and don't report issues to us via IRC, email, forums, or any other way... all that will happen is we will forget about it and then your bug will not be fixed.

The bug tracker aids us with coordinating what bugs should be fixed in next version, what has priority, which bugs are similar (or duplicates) and thus may help us spot patterns, who should fix what bugs, etc.

Getting started[edit]

How to install UnrealIRCd[edit]

Check out the Installing from source or Installing (Windows) articles.

Compile/build problems[edit]

I ran ./configure and got tons of problems[edit]

Do NOT use ./configure! Run ./Config instead.

make: *** No targets specified and no makefile found. Stop.[edit]

First of all, did you run ./Config? You must run ./Config first!

The error means something must have gone wrong when you ran ./Config earlier. So scroll up in your terminal and have a look at the last 20-30 lines of output that ./Config gave to you. Maybe you don't have a C compiler or are missing some libraries.

On Debian and Ubuntu it may help to run the following as root: apt-get install build-essential. After that become a normal user again (not root) and run ./Config and make again as you did before.

(v)fork: Resource temporarily unavailable[edit]

You are trying to compile you ircd on a nice shell and your sysadmin has set your process limit too low.

Explain the problem to your system administrator: say you are unable to compile because of the process limit, and paste the error to him/her.

Windows: unresolved external symbol ..[edit]

NOTE: We highly suggest you to simply download the Windows precompiled version from unrealircd.org instead of compiling your own (unless you need to).

This error can mean a number of things, but if you see unresolved symbols in non-windows functions, such as:

  Creating library L_COMMANDS.lib and object L_COMMANDS.exp
M_OPER.obj : error LNK2019: unresolved external symbol _sendto_snomask_global re
ferenced in function _m_oper
M_INVITE.obj : error LNK2001: unresolved external symbol _sendto_snomask_global
src/modules/commands.dll : fatal error LNK1120: 1 unresolved externals
NMAKE : fatal error U1077: 'cl' : return code '0x2'

Then this is because the wircd.def file is not up to date with your compile settings. Fixing this is simple, you need to download dlltool.exe and place it in your path (eg: c:\windows\system32). Then, for compiling you use something like this:

nmake -f makefile.win32 [your other options here]
nmake -f makefile.win32 SYMBOLFILE
nmake -f makefile.win32 [your other options here]

So basically you just run nmake -f makefile.win32 SYMBOLFILE and then restart compiling again.

If that didn't help, then this is a different problem (eg: old compiler, too new compiler, invalid compile environment, etc).

Windows: I'm unable to compile UnrealIRCd on windows[edit]

NOTE: We highly suggest you to simply download the Windows precompiled version from unrealircd.org instead of compiling your own (unless you need to).

If you really want to compile UnrealIRCd on Windows yourself, then read the instructions on Compiling UnrealIRCd on Windows.

Getting UnrealIRCd up and running[edit]

The questions below answer problems with getting UnrealIRCd booted.

Windows: It doesn't start?? nothing happens![edit]

If you start UnrealIRCd and nothing happens, you see nothing, then you are probably running UnrealIRCd as a service. This means you checked 'install as a service' during the installer. When UnrealIRCd is running as a service you won't see a graphical interface (GUI). The GUI can be quite useful, especially when you're setting up UnrealIRCd for the first time. That's why we don't recommend installing as a service and the option is called "install as a service (not for beginners!)".

Switch from service mode to GUI mode[edit]

Open an elevated command prompt. Change to the "C:\Program Files\UnrealIRCd 5\bin" directory and run the command "unrealsvc uninstall". This won't uninstall UnrealIRCd itself, but will uninstall the service.

Then next time you try to start UnrealIRCd (run UnrealIRCd.exe) you will see the GUI, which is much more helpful.

If you want to run in services mode again, then run "unrealsvc install".

I still want to run as a service[edit]

If you run UnrealIRCd as a service then errors are logged to 'service.log', which may or may not be in the 'logs' subdirectory.

Where are errors logged?[edit]

Errors are normally logged to the file ircd.log in the logs subdirectory.

If you run UnrealIRCd "as a service" on Windows rather than in GUI mode then the errors are logged to service.log instead. Note that you may want to (temporarily) switch from service to GUI mode, see #Switch from service mode to GUI mode.

set:: missing[edit]

You didn't set a required variable in your set block. See the Set block for documentation on the specific variable.

{ } block missing[edit]

Your configfile doesn't contain a required block, please check the documentation on the block. Each block is documented in detail.

Unknown directive[edit]

Several possibilities:

  • you have a unknown/misspelled variable name.
  • you forgot to load a module
  • you are using an older UnrealIRCd version (note that the documentation in this wiki is about the UnrealIRCd development version so it may contain features not yet available in the current release).
  • you have put the setting in the wrong place, for example set::options::dont-resolve means set { options { dont-resolve; } }
  • you have a parse error in your config file. For example, the admin block should be something like:
admin {

If you forget a ; somewhere then it won't work!

See Configuration#Configuration_file_syntax for an explanation on the syntax and to learn what is valid and what isn't. It's just one page.

illegal something::class / unknown class 'something'[edit]

You are referring to a class which you didn't declare.

You refer from allow/oper/server blocks to class blocks so the class blocks should be defined before you refer to them. So the order is important.

Error binding stream socket to .. Address already in use[edit]

This means the IRCd cannot listen on the port(s) you specified. Here are the two (most common) possibilities:

Another process is using the port[edit]

An IRCd process is already running on the same port(s).

Solution: simply kill the old IRCd before you try to launch UnrealIRCd (or make one of them use a different port)

You are on a shell box[edit]

When you use a shell provider you normally need to 'bind' to a a specific IP which the shell provider assigned to you. So if you have:

listen         *:6667;

Then change that to:


Where is the IP you received from your shell provider. You will have to do this for ALL your listen blocks.

See also the documentation of the Listen block.

UnrealIRCd starts fine but I get Connection refused[edit]

See #Connecting

loadmodule ....: undefined symbol ....[edit]

If you get undefined symbol errors such as:

* unrealircd.conf:52: loadmodule src/modules/commands.so: failed to load: tmp/F73A8A80.commands.so: Undefined symbol "ssl_get_cipher"

Then most likely you did not upgrade or (re)compile UnrealIRCd properly. Do the following:

make clean
make install

And try booting UnrealIRcd again.

Reasons why it might not have worked:

  • Perhaps you forgot 1 of the steps of above
  • Make sure your irc is installed in the path you think it is. Double check the paths you see / entered.
  • Possibly you have some old .so files from previous versions that you are trying to load. Check the file date/time to ensure they are really just compiled a few minutes ago.

If all of the above didn't work then you could just as easily try a clean UnrealIRCd installation. rm -rf or rename your current one, extract a fresh .tar.gz and configure&compile it.

Your server is not listening on any SSL ports[edit]

From 4.0.11 onwards you may see something like this:

[error] Your server is not listening on any SSL ports.
[error] Add this to your unrealircd.conf: listen { ip *; port 6697; options { ssl; } }

This is because you do not have any listen { } blocks with SSL enabled.

Why is this important? Using SSL/TLS prevents people from eavesdropping, much like HTTPS is better than HTTP. For more information see our SSL/TLS article.

To fix this, follow the instructions as outputed on your screen. In the example of above the fix is to add this to your unrealircd.conf:

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

Or a nicer version (but the same result):

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

We suggest to use use port number 6697 for SSL/ TLS. This port number standard port for secure IRC (Source: [1]).

Most people should not see this warning/error, since UnrealIRCd has been shipping and advocating this SSL port in the default example.conf since 2004 (Source: [2])

You have old examples in your spamfilter.conf[edit]

The problem[edit]

If you see the following error or warning:

[warning] *** IMPORTANT ***
[warning] You have old examples in your spamfilter.conf. We suggest you to edit this file and replace the examples.

Then this means that the example spamfilters in your conf\spamfilter.conf are outdated.

The solution[edit]

Please open the conf\spamfilter.conf file on your server and replace the contents (or at least the examples) with this: New spamfilter.conf

Or, if this is too much work for you, then you can also just remove all examples or not include spamfilter.conf from your unrealircd.conf. They are just (old) examples anyway.

More information[edit]

The information from above was about example spamfilters that shipped with UnrealIRCd. You may also have added custom spamfilters yourself. For those, if you use method posix then you need to change these to method regex. See the FAQ item POSIX spamfilters are deprecated for more information.

Converting old log block to new (U5 to U6 upgrade)[edit]

If you are using UnrealIRCd 5 config on UnrealIRCd 6 then you may see something like:

[error] unrealircd.conf:100: Your log block contains no sources and no destinations.
[error] The log block changed between UnrealIRCd 5 and UnrealIRCd 6, see ... on how to convert it to the new syntax.

In UnrealIRCd 6 we use a new log block syntax. For full details see Log block (UnrealIRCd 6).

Most people will just want to log everything. Use this:

log {
        source {
        destination {
            file "ircd.log" { maxsize 100M; }


The FAQ items below assume your UnrealIRCd is running but you can't connect to it with an IRC client.

We split the connection problems in two sub-sections:

Please be sure to read the correction secton :)

Unable to connect to IRC server (server at home)[edit]

This FAQ item assumes you are running UnrealIRCd on a server at home. If this isn't the case then see #Unable to connect to IRC server (VPS/shell) instead!

Really running?[edit]

First of all, is UnrealIRCd really running? Do you see a GUI on Windows? And see an 'unrealircd' process on *NIX ? (ps x|grep ircd)

Check also #Where are errors logged? to see if there are no errors.

Can you connect locally to your IRCd?[edit]

Try /server 6667. If even yourself can't connect to your own IRCd by this then verify if the IRCd is running at all! Or maybe you bounded to a specific IP or using a different port. You should fix this, there's no point in continuing with the steps below.

Have outside users connect to your IP[edit]

Try using the IP name of your IRC server first, rather than a hostname. So /server 6667 where is your internet IP. You can find out your internet IP by going to whatsmyip.org or similar sites. (Also note that outside users cannot connect to your ircd with ips like 192.168.x.x or 10.x.x.x, those are LAN ip's, not internet routable IP's!)

You probably need some port forwarding[edit]

If outside users can't connect to your Internet IP, but you can connect locally, then most likely a router or firewall in-between is blocking their access. This is common. You need to "forward" your IRCd port (usually 6667 and 6697) on your router. Please consult your routers documentation. This article may also be of help.

Don't forget Windows firewall![edit]

You may need to allow the Windows Firewall to allow incoming connections to your IRCd. It should have asked this when you fired up the IRCd. Alternatively, you can disable Windows firewall if you trust the people on the same LAN and are connected to the internet via a router.


When the port has been forwarded on your router and windows firewall is turned off (or on but incoming IRCd connections are allowed) then it should be no problem to get outside users on your IRCd. Have fun!

Unable to connect to IRC server (VPS/shell)[edit]

Below assumes you are running UnrealIRCd on a VPS, shell provider or a dedicated server. If instead, you are running a server at your own home then see #Unable to connect to IRC server (server at home) instead!

Really running and listening?[edit]

First of all, is UnrealIRCd really running? On *NIX run ps x|grep ircd, it should output something like this:

syzop@vulnscan:~$ ps x|grep unrealircd
 7795 ?        S      0:00 /home/syzop/unrealircd/bin/unrealircd

This means UnrealIRCd is running.

Listening on the right ports?[edit]

On *NIX (but not easily on Windows) you can double check if UnrealIRCd is actually listening on the port. You do this via netstat -anp|grep ircd:

syzop@vulnscan:~$ netstat -anp|grep unrealircd
(Not all processes could be identified, non-owned process info
 will not be shown, you would have to be root to see it all.)
tcp        0      0  *               LISTEN      7795/unrealircd
tcp        0      0  *               LISTEN      7795/unrealircd
tcp        0      0  *               LISTEN      7795/unrealircd
tcp        0      0  *               LISTEN      7795/unrealircd
unix  2      [ ]         DGRAM                    212392255 7795/unrealircd

In the example of above the IRCd is running on the ports 7000, 6667, 6668 and 6900.

If it's not listening on the correct ports then stop here. Check #Where are errors logged? for errors.

Connect by IP[edit]

Try connecting to the IP of your IRC server first, rather than connect by hostname. So /server 6667 where is the internet IP of the machine.

Check the firewall[edit]

If you cannot connect by IP then you need to check the firewall of the server. Consult the documentation for your Linux distribution or your non-Linux OS.

On some VPS providers like Amazon, you need to configure the firewall in your admin panel as well (these are called Security groups on Amazon EC2).

Can connect by IP but not by hostname[edit]

If connecting by IP works perfectly fine (/server, but you cannot connect to it by hostname (/server some.nice.hostna.me) then you need to understand that the hostname you are connecting with needs to be 'registered' at your DNS provider. You must own the domain name, and add something called an 'A record' to point to your IRC server. Explaining how to do this is outside the scope of this FAQ.


This section assumes your server is up and running and you can connect to it, but you are having some sort of problem or question.

You need to use a secure connection (SSL/TLS) in order to /OPER[edit]

If you try to /OPER up from an insecure connection you will see the following error message: You need to use a secure connection (SSL/TLS) in order to /OPER.


UnrealIRCd, by default, requires IRCOps to use an SSL/TLS connection before they can use the /OPER command. This is because IRCOps will see sensitive information, both in terms of privacy and safety. By not using SSL/TLS you risk intercepting of sensitive information (including passwords) by third parties.

How to fix it[edit]

You basically have two options (choose 1):

Option 1: Tell your IRC client to connect with SSL/TLS[edit]

This is the highly recommended action. The standard SSL/TLS port is 6697. You have to configure your IRC client to connect to port 6697 and you must tell the IRC client to use SSL/TLS. How you do this depends on your IRC client:

  • In AdiIRC and mIRC you prefix the port with a plus sign: /server irc.example.org +6697
  • In irssi you use the -tls option: /connect -tls irc.example.org 6697
  • In weechat you use the -ssl option: /connect irc.example.org/6697 -ssl
  • Many other IRC clients use similar methods. In graphical chat clients you may have to tick a box called 'SSL' or 'TLS'.

IMPORTANT: Some IRC clients will not accept self-signed certificates by default (e.g: mIRC 7.59+) and you will recieve errors such as SSL certificate verify failed. Almost always the IRC client has an option to still trust/accept the certificate, consult your IRC client documentation. Of course, it would be even better if you use a "real" SSL/TLS certificate, see also Using Let's Encrypt with UnrealIRCd.

Option 2: Allow insecure oper connections[edit]

You can disable the SSL/TLS requirement for IRCOps. This is NOT recommended and, depending on your case and jurisdiction, you may violate law such as GDPR Article 32. However, it is available as an option, for example if you run a test network with only you (1 person) on it:

To disable the requirement you have to change set::plaintext-policy::oper from deny to warn:

set {
    plaintext-policy {
        oper warn;

Where do I get a list of commands, user modes, channel modes, etc.[edit]

Check out the documentation:

Where's channel mode +j (jointhrottle)?[edit]

Jointhrottle is a useful anti flood feature which limits (throttles) the number of joins a user can do (to the same channel) to X per Y seconds. In UnrealIRCd 3.2.x you would enable this via channel mode +j.

This was moved in UnrealIRCd 4 to the set::anti-flood::join-flood configuration setting and the channel mode +j has been removed. Why? There's rarely any need to configure this on a per-channel basis, and this way it's enabled by default in UnrealIRCd on all servers for all channels.

Where did user mode ... go in UnrealIRCd 4?[edit]

The following user modes were removed in UnrealIRCd 4:

  • Netadmin, services-admin, admin, co-admin: due to the new IRCOp access control.
  • User mode 'g' (failops): we already have 'o' and snomasks for this
  • User mode 'v' (receive infected DCC send rejection notices): moved to new snomask 'D'
  • User mode 'h' (helpop): all this did was display "is available for help" in /WHOIS. For IRCOps you can use oper::swhois for that. If you want non-ircops to have this too, then add a Vhost block with vhost::swhois.

This command is no longer working in UnrealIRCd 4[edit]

The following commands were removed in UnrealIRCd 4:

  • /ADDLINE: dangerous command. With this command you can (too) easily break your configuration file, in which case your server can't /REHASH anymore and won't get back after a restart. Only people with access to the configuration files (eg: shell access) should modify the configuration file.
  • /ADCHAT & /NACHAT: because of the new IRCOp access controls this no longer makes sense.
  • /CHATOPS: use /GLOBOPS which does the same

For people using /GLOBOPS and /LOCOPS or the other /..CHAT commands: We have something wonderful on IRC called "channels". It allows you to talk to multiple people at the same time. You should really have an #opers and/or similar channel(s). This being said, we kept the /GLOBOPS and /LOCOPS command in anyway.

Helpop doesn't work[edit]

If the /HELPOP command does not output anything, then try /QUOTE HELPOP just to be sure.

Still nothing? You need to include help.conf from your unrealircd.conf like this:

include "help/help.conf";

So better double check you have it. After having added it, rehash.

I can't change channel modes, join invite only channels, etc even though I am IRCOp!![edit]

So, you are an IRCOp and you expect to be able to join all channels, regardless of whether they are invite only, have a channel key, if you are banned, etc. etc.? And you expect to be able to change channel modes through /MODE even though you are not a channel operator?

Have a look at the OperOverride. And you should read the IRCOp guide as well.

I have k/g-lined myself!![edit]


See #How to prevent myself from getting banned on how to get on IRC anyway to resolve the situation.

NOTE: There's no way to remove any *LINES from the shell. Well, if you restart the IRCd the KLINEs will be cleared, of course. And if you have no other IRC servers linked then all other ban types (GLINE's) will be cleared as well.

How to prevent myself from getting banned[edit]

If you want to be sure that you can never get KLINE'd / GLINE'd / etc... then see below. Note that this has nothing to with channel bans (+b)!

Open your unrealircd.conf and add the following lines:

except ban { mask; }

Naturally replace with your own IP address (your own ip address, not your server ip address)

After that, rehash the ircd.

How to become IRCOp / administrator[edit]

You define IRC Operators in the Oper block and then use the /OPER command on IRC to become an IRCOp.

For example, if your oper block is called 'TestOper' like this (first few lines):

oper TestOper {
        mask *;
        password "test";

Then you would use the following command to become IRCOp:

/oper TestOper test

NOTE: both the name and the password are case sensitive!

Still have trouble becoming IRCOp?

  • Try with an oper::mask * like in the example of above. Only after it works you limit it down to an IP range, or you just keep it at *
  • Make sure you rehashed after making any changes to your unrealircd.conf

Once you are IRCOp, we recommend reading the IRCOp guide!

How to broadcast a message to all users[edit]

As an administrator you may want to broadcast a message to all users, either on one particular server or to everyone on all servers. Naturally only IRCOp's may do this, regular users can't.

Network-wide broadcasting[edit]

You normally use Services for this, the command is usually called GLOBAL and goes via OperServ:

/OS GLOBAL Hi this is a message to everyone!

You can also use this UnrealIRCd command. It also works without services but rquires you to have all your server names end in the same domain name:

/NOTICE $*.yournet.org Hi this is a message

Server-specific message[edit]

To send a message to everyone connected to irc1.yournet.org:

/NOTICE $irc1.yournet.org Hi this is a message

I am IRCOp but /LIST still hides certain channels[edit]

hidden on the client-side[edit]

Clients often have filtering options enabled by default. For example in mIRC if you right click on the channel list and select List options:

  • Ensure that it does not filter on a minimum amount of people. If you filter at minimum 2, then you won't see channels with only 1 user in it.
  • mIRC has a checkbox option called Hide non-text channels or Hide non-alphanumeric channels which want to uncheck (deselect). If the option is enabled then it will hide certain channels.

permitted to see?[edit]

You need the override::see::list operclass privilege in order to see secret channels in /LIST. The operclasses shipped with UnrealIRCd in operclass.default.conf include this capability, so if you use the 'netadmin' or other default operclasses then this is already OK.

incorrect time[edit]

Unusual, but possible: if your clock is off by 24 hours (or more) then some channels will be hidden as well.

Warning! Possible desynch: SJOIN for channel .. has a fishy timestamp (XX)[edit]

This is a serious condition, and is actually some sort of bug.

In technical terms, it means a MODE command (to be exact: the last parameter mode) was misinterpreted to be timestamp of the channel. For example UnrealIRCd 3.2.2 had a problem with SAMODE and certain parameters.

This is a serious condition and unfortunately the only way to fix it is to have all users leave the channel so it can be re-created.

I (suddenly) got clients quiting with Max SendQ exceeded![edit]

short answer[edit]

Increase your class::sendq

long answer[edit]

This happens when a client issues a request that will return A LOT of data, usually '/who' (eg /who #channel). If you for example have large channels like 300+, 500+ etc... then /who #chan will return A LOT of data, therefore the max sendq (sendq == send queue) is reached and the client is disconnected... Some clients or scripts do a '/who #chan' on join. This explains why certain people will be killed directly on join, while others will not.

The solution is to simply increase the sendq. To what value? Something like 250000 is reasonably high (250k). If that doesn't work, try 500000 (500k).

hostnames are not resolving[edit]

You get *** Couldn't resolve your hostname; using your IP address instead?

The best way to test is to let someone from a remote location (not your LAN) connect to you where you can be sure of his host resolves (for example it works at ircnet/efnet/undernet/..). If the host resolves fine on one of those other networks but not on your UnrealIRCd server then you know there is a possibly problem on your end (your UnrealIRCd or your server).

DNS information is acquired from /etc/resolv.conf (*NIX) or the registry (Windows). Type '/quote dns i' (as an oper) to see the current nameserver in use by UnrealIRCd. If you changed your nameserver settings in resolv.conf or in Windows then you will have to run /REHASH -dns or restart UnrealIRCd.

Example of how to test your nameserver at *NIX:

# host domain name pointer test.domain.
# host test.domain
test.domain has address

In this example the host is correct and the nameserver seems to work fine. The user should get the host test.domain on IRC.

Another example:

# host domain name pointer somehost.domain.
# host somehost.domain
somehost.domain has address

In this case your own name server is fine, it is sending replies. But the information does not match: reverse dns resolved to somehost.domain, however, when double checking this by resolving somehost.domain we got back. Since forward DNS and reverse DNS don't match the user will not have a hostname on IRC. That's how it works, otherwise everyone could spoof their own hosts... In this case the owner of the domain and/or the IP could (or should) fix their DNS entries to make them match.

How to combat spam, advertising, worms, virusses, drones[edit]

If your IRC network regularly receives spam and/or many (fake) users connecting, then:

  1. Check out Anti-flood features and in particular the sections there called DNS Blacklists and Connthrottle
  2. Use Spamfilter to kill / block people based on 'patterns' in messages or elsewhere. This is mainly against advertising/spam.

Exiting ssl client [..] Internal OpenSSL error or protocol error[edit]

If you get messages like:

Exiting ssl client [@]: SSL_write(): Internal OpenSSL error or protocol error
Exiting ssl client [@]: SSL_write(): OpenSSL functions requested a read()

Or anything else like that then it's nothing to worry about, these are sent to the JUNK snomask.. which is.. guess what? for junk...

What this error message means is that someone (or something) tried to connect to the SSL port but something went wrong.. in almost all cases it is a non-SSL client connecting to a SSL port, things like a bot, another server (w/autoconnect) or services trying to connect every X minutes...

To summarize: it's usually nothing to worry about and not an attack, unless you get like X msgs of these per second the whole time ;).

If you don't like it, remove the junk snomask (/MODE nick +s -j)!

How do I get an oper/admin/.. host after I oper up[edit]

You set vhost in the Oper block.

How do I get a title in /WHOIS[edit]

If you want /WHOIS to show something like "UserX is a Network Administrator" or "UserX is your friendly administator" then you can use swhois in the Oper block for that.

To grant such a title to non-IRCOps you can use swhois in the Vhost block.

I changed my oper block but the changes are not effective[edit]

Did you rehash your server?

You also need to de-oper before /OPER'ing up again to have all settings effective. To do this you simply do:

/MODE yournick -o

and then use /OPER... again.

ERROR: (g)zlines should be placed on user@IPMASK not user@hostmask[edit]

If you execute the command /GZLINE *@blablabla.dialin.bla.com you will get something like:

ERROR: (g)zlines should be placed on user@IPMASK, not user@hostmask (this is because (g)zlines are processed BEFORE a dns lookup is done)


This is because ZLINE's (and global zlines, GZLINE's) need to be placed on an ipmask and not a hostmask. The reason for this is that zlines are processed right after accepting the connection, before any data is received and before any DNS lookups (hostname lookups) are done. So when the server is checking the zline ban list, it does not know the hostname, it only knows the IP. A (g)zline disconnects the user IMMEDIATELY after the connection attempt. In fact, that is the main difference between (g)zlines and klines/glines!


Two options:

  • Use a KLINE or GLINE instead, which can be placed on a hostmask
  • Place the ban on the IP of the user (eg: *@, you can get this by /WHOIS'ing the user (the 'connecting from' line). If the user already left then you could use your '/dns [host]' client command, although that's a tad less safe[1].

[1] If the bad guy owns the domain, then he might have updated his name to point to another ip.

I want to disable host cloaking (hosts like: Gll-20409F99.example.net)[edit]

What is cloaking[edit]

Cloaking is a means to hide the real host from other users, for resolvable hostnames it looks a like Gll-20409F99.example.net, and IP's will look like 9DD2051.356EF559.713C47B6.IP. You get a cloaked host by the usermode +x (this can be manually set, or automatically by the server). For more general information on cloaking, see the section on cloaking in the docs.

Cloaking is a security feature (for your users), so think twice before disabling it!

How to disable it[edit]

You have several options:

Option 1: make cloaking not the default[edit]

Just remove the 'x' in set::modes-on-connect, then users will not be set +x automatically and thus will not be cloaked. Users can still set themselves usermode +x if they want to.

set {
        modes-on-connect "+i";

Option 2: fully deny users to be cloaked[edit]

If you never ever want people to use cloaking then remove 'x' from set::modes-on-connect (if it is present), AND set set::restrict-usermodes to 'x':

set {
        modes-on-connect "+i";
        restrict-usermodes "x";

Option 3: Don't load the cloaking module[edit]

You can simply decide not to load the cloak module. So remove the line with

loadmodule "cloak";

If you edit this in modules.default.conf then remember to re-apply these settings after each UnrealIRCd upgrade.

Why is UnrealIRCd responding slowly (laggy). It's only processing 1 line per second??[edit]

It is NOT because UnrealIRCd is slow. It's called fake lag and it's an anti-flood countermeasure. Yes, it's a feature, not a bug.

See the question below.

How to allow users to send more commands per second[edit]

By default, UnrealIRCd applies fake lag, a lag penalty to the user to limit the number of commands users can execute per timeframe.

IRCOps are 100% exempt from this fake lag. Although they could still go Excess flood due to sendq/recvq restrictions you have imposed in the Class block.

You can also allow non-IRCOps to flood at higher rates, see below.

Allowing high command rates in UnrealIRCd 5.2.1 and later[edit]

Step 1: create a new security group[edit]

Create a new security group consisting of those users that are really trusted and should be able to flood more. For example, the following creates a security group called flood-users that matches all users with IP and people that are identified to services with the account TrustedAccount:

security-group flood-users {
    include-mask {; ~a:TrustedAccount; }

For more information about possible masks, including matching on TLS fingerprint and other criteria, see Mask item.

Step 2: set higher flood limits[edit]

Then create an anti-flood sub block to set a higher limit for the security group that you just created:

set {
    anti-flood {
        flood-users {
            lag-penalty 100;
            lag-penalty-bytes 0;

The above allows the users in the security group flood-users to send a command every 100 milliseconds, so 10 commands per second (1000/100=10). It allows bursting of 10000/100=100 commands (if after such a burst not sending higher than 10 commands per second).

If you need even faster rates then here is a cheat sheet:

lag-penalty Commands per second Maximum burst of commands in 1 second
1000 1 10
100 10 100
50 20 200
25 40 400
10 100 1000

The exact details of lag-penalty and lag-penalty-bytes and the fake lag algorithm are explained in detail in the set::anti-flood block and is a fairly complex topic.

The old way: nofakelag[edit]

IRC Operators are exempt from fake lag and can send as fast as they want. You can see IRCOps can flood hundreds or thousands of commands per second. Note: they could still go Excess flood due to sendq/recvq restrictions you have imposed in the Class block.

It is also possible to turn fake lag on/off for regular clients. To do this, in the directory where you compile UnrealIRCd you open include/config.h and search for FAKELAG_CONFIGURABLE. Change the following line, from:




..and save the file. Then you have to recompile (make clean; make install) and restart UnrealIRCd.

Then, for users you trust, you can enable class::options::nofakelag for regular users, eg:

class nolag {
    sendq 500M;
    recvq 8000;
    options { nofakelag; }

allow {
    ip *@192.168.*;
    class nolag;
    maxperip 20;

This way, users with an IP address of 192.168.* will be able to flood at full speed.

Again, be very careful if you disable fake lag. Most people who do this are either on a closed network with only a few friends (flooding ASCII art) or are using IRC behind the scenes as a communication mechanism for something other than chatting. Fake lag is there for a reason! It is very dangerous to allow users to flood at full speed. Users can generate vast amounts of bandwidth (really a lot!) and can easily use the lack of flood controls to cause a Denial of Service attack.

NOTE: You may also hit another flood protection limit, such as this one.

Fakelag exemption is not working[edit]

Often people think fakelag exemption is not working. Even if they are IRCOp their messages are still being throttled / slowed down. If you are an IRCOp and you are seeing your messages being throttled then this is NOT done by UnrealIRCd. It is your client. Yes, really it is your client. Almost every IRC client throttles sending of messages and commands on their side, including but not limited to mIRC, irssi, KVIRC, eggdrop, etc. They do this as a protection mechanism. How to disable this throttling depends on your client and in quite some cases it is even quite difficult to do so.

TODO: other people, feel free to edit the wiki and add some instructions for the more popular clients.

User/Channel is being flooded. Message not delivered.[edit]

You may see the error Channel is being flooded. Message not delivered or User is being flooded. Message not delivered. In normal circumstances you should never see this error. It should only happen during a large flood.

This error is triggered when you hit target-flood protection. You can either increase the limit or blacklist the module. Reasons for doing so would be if you have a private network where you have users flooding ASCII art, or if you use IRC channels for something other than chatting (eg logging). Note that changing target-flood settings will weaken flood protection on your IRC server. If you have a public internet-facing server then this is not recommended.

How to prevent private messages?[edit]

Some people would like to block private messaging (PM) / direct messaging (DM). This is possibly with the usermodes/privdeaf module which provides usermode +D (deaf).

Individual users can set +D. Then nobody (except IRCOps) can message them:

/mode yournick +D

You can also set +D by default on users via the configuration file. To do so, simply add D to your modes-on-connect:

set { modes-on-connect "+iD"; }

If you do the above then individual users can still unset the mode (-D). If you don't want this, then you can restrict the mode:

set {
    modes-on-connect "+iD";
    restrict-usermodes "D";

Now your users can never private message anyone.

NOTE: IRCOps can still message users, they are exempt from this restrictions.

ERROR: Spamfilter type 'posix' is DEPRECATED[edit]

The "posix" spamfilter type is being phased out. If you get this warning or error then simply replace the type posix with regex. In most cases this should work fine.

IMPORTANT: If you are using the example spamfilter.conf shipped with UnrealIRCd, then you should probably read the following article instead: old examples in your spamfilter.conf.

Below are some examples:

Update your /SPAMFILTER command[edit]

If you were using this:

/spamfilter add -posix cN gzline 1d No_advertising_please /come to irc\..+\..+/

Then you should now use this instead:

/spamfilter add -regex cN gzline 1d No_advertising_please /come to irc\..+\..+/

Update your configuration file[edit]

If you have something like this in your configuration file:

spamfilter {
        match-type posix;
        match "come to irc\\..+\\..+";

Then this should be changed to:

spamfilter {
        match-type regex;
        match "come to irc\\..+\\..+";

If you are really interested in reading more about this, there are some subtle differences between "posix" and "regex", which this page outlines (external link to PHP.net).


In UnrealIRCd 4.x there were 3 spamfilter types:

  • The simple spamfilter type supports only * and ?, allowing very fast matching.
  • The posix type uses regular expressions through the TRE regex engine. TRE has not been maintained for many years now, the last release is from 2009 and it is now a defunct product. It contains various bugs that will never be fixed, including bugs that may freeze the IRCd completely. The only reason it still exists in 4.x is that it can run the spamfilters that were used in UnrealIRCd 3.2.x.
  • The regex type uses regular expressions using the PCRE2 engine. This regex engine is used by various big projects, including PHP, and is a fully supported product.

We are phasing out the TRE regex library from UnrealIRCd for the reasons mentioned above.

Again, just to reiterate, you should simply use the "regex" spamfilter type instead. That one uses PCRE2 and will be fully supported.

Why do users on WEBIRC gateways not get user mode +z?[edit]

UnrealIRCd no longer gives user mode +z to users on WEBIRC gateways using SSL/TLS IRC, unless the WEBIRC gateway gives us some assurance that the client---webirc gateway connection is also secure (eg: using HTTPS). This fixes a security issue if the client--webirc connection is unencrypted and such (actually unencrypted) users are able to join +z channels, which should be for encrypted connections only.

Technically, this is the regular WEBIRC format:

WEBIRC password gateway hostname ip

This indicates a secure client connection (NEW):

WEBIRC password gateway hostname ip :secure

Naturally, WEBIRC gateways MUST NOT send the "secure" option if the client is using http or some other insecure protocol.

You should check with your WEBIRC vendor if they have an update available to fix this issue.

Why do I get Session limit exceeded on connect?[edit]

By default, UnrealIRCd allows 3 connections per IP, unless you increase that number to your desired one

allow {
	mask *;
	class clients;
	maxperip 3;

If it was UnrealIRCd limit, it would look like this:

Too many connections from your IP

If the message you see is

Session limit exceeded

Than this is services problem and you should check operserv.conf and increase defaultsessionlimit under os_session module

Linking servers[edit]

How do I link two (or more) IRC servers[edit]

Have a look at our Tutorial: Linking servers.

Trouble with linking two IRC servers[edit]

Have a look at our dedicated Troubleshooting: linking servers article.

(sync) Possible negative TS split at link server.blah.net (1078875430 - 1078875478 = -48)[edit]

If you get an error like:

(sync) Possible negative TS split at link server.blah.net (1078875430 - 1078875478 = -48)

then this -48 means one of the clock is 48 seconds behind the other. This is bad.

See #Why correct time is important and how to fix your clock

Your clock is .. seconds behind my clock. Please verify both your clock and mine, fix it and try linking again.[edit]

See #Why correct time is important and how to fix your clock

Your clock is .. seconds ahead of my clock. Please verify both your clock and mine, fix it, and try linking again.[edit]

If you get something like:

Your clock is -1337 seconds ahead of my clock. Please verify both your clock and mine, fix it and try linking again.


Rejecting link xx.xx.xx[@X.X.X.X.59383]: our clock is 575 seconds ahead.
Correct time is very important in IRC. Please verify the clock on both services.test.net (them) and
maintest.test.net (us), fix it and then try linking again

Then see #Why correct time is important and how to fix your clock

Why correct time is important and how to fix your clock[edit]

It is very important on IRC to have a perfectly synchronized clock. You can read below why correct time is important, but you can also skip directly to the Solution.

Why correct time is important[edit]

As said, correct time is important. This is even more important when you link servers. If the clocks of your servers are off by more than a 5 seconds then you may experience problems already. If they are off for more than 30 seconds then you have a serious problem. In fact, we don't allow linking two servers when their clocks are more than 30 seconds off.

We really use timestamps in IRC everywhere. So incorrect time will cause quite a number of issues:

  • Temporary KLINES/GLINES/SHUNS/etc will not expire correctly. They might expire like an hour earlier, or even directly when they are added, or later.
  • Sudden (wrong) nick collision kills. Incorrect time can be exploited by someone to kill other users (thus incorrect time is a security problem as well!)
  • Channels might not show up in /LIST (especially if time is more than a day off)
  • Services might be unable to set a user +r (+r = register user)
  • In /WHOIS it may look like someone 'signed on' at the wrong time, even in the future

Solution: Synchronize the server clock[edit]


Windows 10 should automatically synchronize the clock. If it isn't working, then just search the web on how to do this.


On Linux/*BSD/etc you can get your clock perfectly synchronized by running ntpd. To install this you need root access on the machine.

On Linux distro's you run sudo apt-get install ntp or sudo yum install ntp.

If you don't have root access on the machine, then ask your system administrator to install ntpd. Incorrect time on a server in general is considered bad practice, so the sysadmin should be made aware of this and resolve the situation.

A word on when your servers are in (different) time zones and daylight saving[edit]

It is absolutely no problem for your servers to be in different time zones. In fact, this is a common situation. Similarly, there's no problem with daylight saving and switching back and forth.

Why is this no problem? Well, on IRC we always use GMT/UTC time for all timestamps. So we don't actually use "local time".

What is important is that both your time AND YOUR TIME ZONE are set correctly. You can see which timezone your server is using by running the date command. It shows something like: Sun Jun 28 14:36:21 CEST 2015, in this example CEST is the time zone.

Example of incorrect clock caused by a bad time zone: Say, you are sitting next to your server and you are (both) in the Eastern Time zone. The wall clock says it's 11:00am and your server also shows 11:00am. Good, right? However, by mistake, your server is actually configured to use Central Time (oops!). This means the clock is actually incorrect, the UTC clock will be 1 hour off!

ERROR: Servers need to use SSL/TLS</a>[edit]

You may see the following error during linking:

Servers need to use SSL/TLS (set::plaintext-policy::server is 'deny')

What it means[edit]

It means that a server is linking in without SSL/TLS. This could be services (eg: anope) or some other software.

NOTE: services on 'localhost' will never see this error.

Why SSL/TLS is important[edit]

SSL/TLS encrypts all data sent over the Internet (or any other network). Without SSL/TLS, data travels in cleartext and can be intercepted by 3rd parties. Everyone should use SSL/TLS and this is especially true for server connections. A single server connection may carry "interesting data" about hundreds of users, including but not limited to: names, e-mail addresses, passwords, IP addresses and even complete conversations.

Option 1: Connect using SSL/TLS[edit]

Make your services connect to UnrealIRCd using SSL/TLS. This is the only real and recommended fix.

Option 2: Change the error into a warning[edit]

Alter the plaintext policy, by setting:

set { plaintext-policy { server warn; } }


NOTE: This basically ignores the serious security issue of your server(s) sending data insecurely over the internet (or local network).

ERROR: Server is using an outdated SSL/TLS protocol or cipher[edit]

You may see the following error while linking servers:

Server is using an outdated SSL/TLS protocol or cipher (set::outdated-tls-policy::server is 'deny')

What it means[edit]

This means the server is linking with an outdated SSL/TLS protocol or cipher. This is usually caused by using old server software, such as UnrealIRCd 3.2.x or some really really old OpenSSL (0.9.x).

Option 1: Upgrade your server software[edit]

Upgrade the server software of the server linking in, eg: upgrade UnrealIRCd from 3.2.x to 5.x, upgrade anope to 2.x, etc. As said, this should only be needed if you are running really old software that has not been upgraded for many years. It should never happen if you are linking two UnrealIRCd 5.x servers.

Option 2: Change the error into a warning[edit]

Alter the set::outdated-tls-policy, by putting this in your configuration file:

set { outdated-tls-policy { server warn; } }


How to use Let's Encrypt with UnrealIRCd?[edit]

See the dedicated article: Using Let's Encrypt with UnrealIRCd

WARNING: Bad ulines[edit]

If you get something like this:

*** WARNING: Bad ulines! It seems your server is misconfigured: your ulines { } block is matching an UnrealIRCd server (maintest.test.net). This is not correct and will cause security issues. ULines should only be added for services! See https://www.unrealircd.org/docs/FAQ#bad-ulines

Then this means your server is misconfigured, as your ulines { } block is matching an UnrealIRCd server.

The ulines block lets you define certain servers as having extra abilities. This should only be used for servers such as services and should never match a regular UnrealIRCd server, otherwise you'll create security issues.

Things that happen when you have ULines for normal UnrealIRCd servers:

  • You will not see "far connects" as an IRCOp, even if you have MODE Yournick +s +cF set.
  • Servers will be missing from /MAP (if this is what you want, then use the hideserver module instead).
  • Flood protection such as channel mode +f is not 100% effective, as remote messages/joins/etc from ULines are not counted as flooding.
  • Channel mode +Z can be set on a channel even if there are insecure users on it.
  • Likely several other things that are not intended..

You should ONLY add ULines for:

  • Services, such as anope/atheme, eg services.example.org

You should NEVER add ULines for:

  • UnrealIRCd servers, eg irc1.example.org, hub.example.org, ..

Authentication failed due to different password types on both sides of the link[edit]

While linking you may see the following error:

Link denied for 'irc2.test.net' (Authentication failed due to different password types on both sides of the link) irc2.test.net[@192.168.X.Y.0]

You are seeing this error because you have mixed different password types (authentication types) at both sides of the link. They should be of the same type.

The solution[edit]

The fix is to use the same type on both sides. So you must check the configuration file on both servers:

  • Either use a plaintext password on BOTH sides of the link, so:
    password "somepassword";
  • Or use an SSL/TLS authentication type, like spkifp on BOTH sides of the link, such as:
    password "AHMYBevUxXKU/S3pdBSjXP4zi4VOetYQQVJXoNYiBR0=" { spkifp; }

Again, you cannot use a plaintext password (the first example) on side A of the link and an spkifp password (the second example) on side B of the link. Mixing is not permitted, which is what this error is about.

Authentication types are explained in more detail in the Authentication types article. Also, the Tutorial: Linking servers article should also be of help to show you standard linking practices.

Old server protocols are not supported[edit]

UnrealIRCd 5 dropped support for UnrealIRCd 3.2.x and earlier server protocols. This means two things:

  • You cannot link UnrealIRCd 3.2.x to UnrealIRCd 5.x/6.x
  • You cannot use services packages that haven't been maintained for years

Use up to date services[edit]

Do you get this message when linking in services? Services packages like anope v1.x, epona and ircservices that are no longer maintained by their developers for many years. They won't work with UnrealIRCd 5.

Do you use anope 2.0.x and still get this message? You may have selected the wrong protocol module. In particular, in anope you must use the unreal4 protocol module (which is for unrealircd 4 and higher) and NOT unreal (which is for unrealircd 3.2.x). Also, anope 2.0.7 or higher is required for UnrealIRCd 5.

Why was support for old server protocols dropped?[edit]

The problem with keeping support for rather old protocols is:

  • It causes network-wide issues. For example, the SID/UID protocol extensions solve many desync issues that result from nick collisions. When at least 1 server does not have SID support then it negates these fixes.
  • It clutters the source, because you now have many exceptions to the rule
  • It causes bugs, for the same reason, and also because code for such older protocols is undertested

What PROTOCOL options do I need?[edit]

If you are a services coder, then check out Server_protocol:PROTOCTL_command

If you are not a services coder then ask your services developer to update the code to the latest protocol. You can refer him/her to this page.


Where is NickServ? ChanServ?[edit]

NickServ, ChanServ, .. are supplied by a services package. UnrealIRCd (like most ircds) doesn't come with services. You have to choose, download and install your services separately. See our Services article.

Why doesn't UnrealIRCd come with services included?[edit]

We don't integrate services in UnrealIRCd itself because we feel you should be able to choose a package that you like yourself. People tend to disagree on which services are the best, it's better to keep this separate from the ircd or else we get "religious wars". See our Services article for available services packages.

How do I get Services?[edit]

See the Services article.

/CS or /CHANSERV says: Services are currently down. Please try again later.[edit]

You execute the /CS or /CHANSERV or any other such command and it says Services are currently down. Please try again later.

Did you install services?[edit]

You need to install services, see Services and the questions above.

Are you services really online?[edit]

Are your services really online and linked? Check with /MAP. Send a message manually to NickServ like /MSG NickServ HELP. You see output? Then see next. If you don't, then first make sure your services are installed and linked correctly.

Configure set::services-server[edit]

set::services-server must point to your services server like this:

set {
        services-server "services.mynet.net";

After changing this, don't forget to rehash.

/NS or /CS say: Unknown command[edit]

Commands like /NS or /CS are called aliases. You need to enable these (they are enabled in the example configuration, though), see Commonly included files under the Include directive. If you made any changes then don't t forget to rehash.

NickServ/ChanServ don't op me or say I'm not a registered nick all the time[edit]

Make sure your services are U-lined. You configure this via the ULines block. While you are at it, make sure your set::services-server is set correctly too!

IMPORTANT : After changing your ULines you must:

  • Rehash the server
  • Disconnect services (/SQUIT services.*)
  • Re-link services (start them again, although some services auto-connect automatically)

Server upgrade issues[edit]

How do I upgrade UnrealIRCd?[edit]

See the Upgrading article.

Nesting comments[edit]

Previously in UnrealIRCd you could do something like this::

/* This is a comment
 * Lalala
 /* and this is a comment within a comment */

... this was because each /* required a */ to terminate the comment. In other words 'comment nesting', if you had two /* then you needed two */.

Starting with UnrealIRCd 4.2.1 we no longer do this and the rule is simply: /* to start a comment and the first */ ends the comment immediately:

/* This is a comment
 * Lalala
 * you can type more but you can only close it once:

Any attempt to use the old way will result in a Ignoring extra end comment warning.

Why? The old style 'comment nesting' was non-standard, and confusing if you for example wrote /* This is for FreeBSD/*NIX */

New operclass permissions[edit]

UnrealIRCd 4.2.1 and higher have a new operclass permission systems. When upgrading you may encounter the message: UnrealIRCd 4.2.1 and higher have a new operclass permissions system. and be referred to this FAQ item.

Default operclasses[edit]

About 99% of our users use the default operclasses and in such a case you should never see this error. Your operclass.default.conf should have been upgraded when installing UnrealIRCd 4.2.1 or higher. So if you are seeing an error in conf/operclass.default.conf then something went wrong with that.

However, if you are seeing an error related to a file that is NOT operclass.default.conf then see next section:

Modified operclasses[edit]

This is for the 1% of the users that like to customize their operclasses. The bad news is: we renamed about 50 of the permissions out of the 100+ so you will have to redo your changes. The good news is that the grouping and naming of permissions is now a lot better and more logical and we did this all for you! The new permissions are extensively documented at the Operclass permissions page.

Note that operclass::privileges is now called operclass::permissions. But you CANNOT just rename your block and be done with it!! For example all the override privilege is now called channel, and thus if you grant channel to low-privileged IRCOp's then they end up having a lot of privileges. Yes, really, you either need to use the default operclasses or have a serious look at the operclass permissions and not try to cut any corners!

Upgrade: download verification issues[edit]

'gpgv' not installed[edit]

You may get the warning:

WARNING: The GnuPG (GPG/PGP) verification tool 'gpgv' is not installed.
Consider running 'sudo apt install gpgv' or 'yum install gnupg2'
When 'gpgv' is installed then the UnrealIRCd upgrade script can
verify the digital signature of the download file.

WARNING: Unable to check download integrity
This is for your information only. It is possible to continue.
Press ENTER to continue, or CTRL+C to abort.

Then there is nothing really wrong, but.. it means the script cannot verify the digital signature. You have two choices:

  • Simply press ENTER to ignore the warning
  • Or do what it says and install the gpgv program (sudo apt install gpgv or sudo yum install gnupg2) and run ./unrealircd upgrade again.

GPG/PGP verification failed[edit]

There are also other possible errors such as:

WARNING: GPG/PGP verification failed. This could be a security issue.
This is for your information only. It is possible to continue.
Press ENTER to continue, or CTRL+C to abort.

If you get that warning, with the note "This could be a security issue" then you should be careful. Something is wrong. Please report to the UnrealIRCd team at syzop@unrealircd.org and/or https://bugs.unrealircd.org/.

ERROR: Upgrade failed[edit]

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: see Upgrading.

Allow block uses allow::mask nowadays[edit]

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;


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


These are questions which simply don't fit well in the other sections.

My server crashed!![edit]

Please report on https://bugs.unrealircd.org/

Note that if the server crashed because of your own source modifications or 3rd party modules not coded by us then we won't help. If you don't know what this is, then you probably don't fit into this no-help category ;)

My server crashed when sending an incorrect raw command from another server (eg: services)[edit]

Please report on https://bugs.unrealircd.org/. We will try to fix the issue but note that issues in this category (input from trusted servers) may not receive the highest priority.

What are 3rd party modules and how do I get them?[edit]

You can use modules to add functionality to UnrealIRCd. Modules can add new user modes, channel modes, extended bans, snomasks, commands and other functionality.

We use the term third party modules to refer to modules that were not included in UnrealIRCd but written by someone else.

You can find a list of 3rd party modules at https://modules.unrealircd.org/ and on https://forums.unrealircd.org/ we have subforums for modules, you can also place requests there.

Please be careful with installing and using 3rd party modules:

  • Like any module and any C program, a fault in such a module can cause the IRCd to crash (or misbehave)
  • 3rd party modules could contain malicious code, only use ones from people you trust!
  • Any crashes or other issues should be reported to the author of the module and not to the UnrealIRCd team. We cannot help you with crashes in someone else his code.

If you are a C coder then you can write an UnrealIRCd module. On the left navigation plane of this wiki there is a section UnrealIRCd development, where you can find developer documentation (C API).

How to install 3rd party modules?[edit]

Note: this assumes UnrealIRCd 5

Installing the module[edit]

On *NIX you generally use the command ./unrealircd module install third/name-of-module. This will take care of downloading and compiling the module.

On Windows you will have to drop a .DLL file in the directory called C:\Program Files\UnrealIRCd 5\modules\third. This DLL file should be provided by the module author.


Now that your module is compiled you probably need to load it from your unrealircd.conf. This step is the same for all Operating Systems:

loadmodule "third/nameofmodule";

Some modules may require you to do more than just that. For example, they may require you to set certain settings. It would be best to consult the documentation of the module for details.

How to upgrade from 3.2.x[edit]

You can upgrade from 3.2.x to 5.x or 6.x. Just be sure to run ./unrealircd upgrade-conf to convert your configuration file. You may still get some warnings or errors when you try to start UnrealIRCd but these should be self-explanatory.

Note that it is not possible to link UnrealIRCd 3.2.x to UnrealIRCd 5.x or later (see also this question).

How do I upgrade my network?[edit]

Since you cannot link 3.2.x to 5.x you have two options:

  • Upgrade all servers at the same time, from 3.2.x to 5.x, in 1 big move. That is: kill all 3.2.x servers, then start all 5.x servers. Of course, best to first test your setup on a small test network.


  • Do a two-stage upgrade:
  1. Upgrade all your servers gradually (one by one) from 3.2.x to 4.x
  2. After all that is done. You can now upgrade gradually (one by one) from 4.x to 5.x.

Why is the upgrade path so shitty for 3.2.x to 5.x?[edit]

So, you can upgrade from 3.2.x to 5.x just fine, see above. But... the way to upgrade on a multi-server network is indeed not ideal.

The reason for this is that a lot of cleanups have taken place in the past 5 years to get rid of old code. We now make modern assumptions about server traffic (protocols). To be frank, and you probably already know this very well: you shouldn't be running 3.2.x anymore since all support (including security support) for 3.2.x was dropped on Dec 31, 2016.

UnrealIRCd 4 was released in December 2015, you have had more than 4 years to upgrade from 3.2.x to 4.x. Also, again, if you run 3.2.x that is very dangerous since it lacks security fixes.

Only SSL/TLS users allowed[edit]

Since Jan 1st 2020 the irc.unrealircd.org support network only allows SSL/TLS connections. You can no longer connect with a plaintext connection on port 6667. Please instruct your IRC client to connect on port 6697 using SSL/TLS. See below for some more client-specific information:

How to use SSL/TLS[edit]

  • in mIRC you use: /server irc.unrealircd.org +6697
  • in irssi you use: /server -ssl irc.unrealircd.org 6697
  • other clients may have similar ways or provide a graphical interface

How you can make your servers SSL/TLS-only too[edit]

We made irc.unrealircd.org TLS-only with the following configuration setting:

set {
        plaintext-policy {
                user deny;
                oper deny;
                server deny;
                user-message "Insecure connection. Please reconnect using SSL/TLS on port +6697. See ...";