Tip of the day: On IRC you can use the HELPOP command to read about various IRC commands.


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

This is the official UnrealIRCd FAQ, which aims to answer 95% of all questions asked (top-100 questions).

TIP: Use CTRL+F to search for phrases that match your question or the error you are having.

This FAQ is structured into sections (see the index further down):

  • If you have a general question, but not a software problem, then see the first two sections: About UnrealIRCd and Releases.
  • Trouble compiling? See the section Compile/build problems
  • Trouble starting UnrealIRCd? See Getting UnrealIRCd up and running. If you are upgrading then the Upgrading section may also apply.
  • Your UnrealIRCd is started but you cannot connect to it? See Connecting
  • You have a question or problem while using UnrealIRCd? In other words: your UnrealIRCd is running and you are connected to it but there is some other question or problem:
    • See Running, Linking servers and the Services sections
  • Finally the Other section deals with questions on crashes and 3rd party modules

You can get support:

  • On IRC at irc.unrealircd.org in #unreal-support. Be sure to check the rules. One of the rules is that you should have searched this FAQ first.
  • On the forums
  • For reporting bugs and feature suggestions use the bug tracker

About UnrealIRCd

Is UnrealIRCd suitable for me?

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?

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

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

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?

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 security features but will need some power and memory during times of attack / heavy flooding. 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?

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

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).

How can I help?

You can help in many ways! See Contributing.


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

The latest Stable version is 6.1.7, released on July 16, 2024.

Next stable, which will be 6.1.8, is scheduled to be released end of September, 2024.

All older series, such as 4.x and 5.x, are no longer supported. See UnrealIRCd releases.

In general, for the Stable branch, we release a new 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.

See History of UnrealIRCd releases for all releases since 1999.

Which versions are supported?

The currently supported UnrealIRCd versions (and EOL dates) can be seen in the table below:

Series First stable release Security fixes only End of life (EOL) Duration Comment
UnrealIRCd 3.2 2004-04-25 2015-12-11 2016-12-31 12.5 years Very old, unsupported, do not use
UnrealIRCd 4 2015-12-24 2019-05-20 2020-12-31 5 years Old, unsupported, do not use
UnrealIRCd 5 2019-12-13 2022-07-01 2023-07-01 3.5 years No longer supported
UnrealIRCd 6 2021-12-17 - - - Stable

There is no strict release cadence of the major versions.

When a new major version is released we will announce the exact end dates of the previous major release. The previous major release is always supported for at least another 12 months after the new major release.

See also:

What is new in the latest version?

Please check out the releases announcements on the forums or browse through the release notes for UnrealIRCd 6

How do I get the latest source code?

Regular downloads

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

Go to our GitHub page. Click on the green button Code and select Download ZIP.

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

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 unrealircd-src

This will create a directory unrealircd-src with all the source code (UnrealIRCd 6 bleeding edge).

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-src directory: git pull

git: command not found

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

The UnrealIRCd documentation is located here.

Where can I get online support?

I found a bug or have a feature suggestion

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

How to install UnrealIRCd

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

Compile/build problems

I ran ./configure and got tons of problems

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

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

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. What helps is if you follow our installation guide, the first step there is installing some packages.

(v)fork: Resource temporarily unavailable

You are trying to compile you ircd, likely on a '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 them.

Windows: unresolved external symbol ..

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

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

The questions below answer problems with getting UnrealIRCd booted.

Where are errors logged?

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.

Linux: error while loading shared libraries

If you try to start UnrealIRCd on Linux and you may have this problem:

$ ./unrealircd start
Starting UnrealIRCd
/home/irc/unrealircd/bin/unrealircd: error while loading shared libraries: libcrypto.so.1.1: cannot open shared object file: No such file or directory

This can happen if your system/distro/OpenSSL had a major upgrade, like from Ubuntu 20.04 to Ubuntu 22.04. The old OpenSSL version for which UnrealIRCd was compiled has then been removed by the package manager and a new version is installed. Such a problem is not unique to UnrealIRCd, it applies to all software that you compiled from source.

To fix this you will have to recompile UnrealIRCd. So go to your unrealircd-X.Y.Z directory (or even better: grab the latest release while you are at it!) and re-run ./Config and make and make install.

Windows: It doesn't start?? nothing happens!

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).

Switch from service mode to GUI mode

  • Open an elevated command prompt
  • Change to the C:\Program Files\UnrealIRCd 6\bin directory
  • Run the command unrealsvc uninstall

This won't uninstall UnrealIRCd itself, but will uninstall the service.

Now just click the UnrealIRCd icon on the desktop or start menu. You will now see a graphical interface (GUI).

If you want to run in services mode again, then follow the same steps but run "unrealsvc install".

I still want to run as a service

If you run UnrealIRCd as a service then errors are logged to service.log in the logs subdirectory.

set:: missing

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

{ } block missing

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

Unknown directive

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'

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

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

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

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

See #Connecting

loadmodule ....: undefined symbol ....

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

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

The problem

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

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

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.


How do I upgrade UnrealIRCd?

  • See Upgrading for all minor upgrades, such as 5.2.x→5.2.y or 6.0.x→6.0.y. Hint: on *NIX you can simply use ./unrealircd upgrade
  • For 5.x to 6.x, see Upgrading from 5.x
  • For 4.x to 5.x, see Upgrading from 4.x
  • For upgrading from 3.2.x to 5.x/6.x, see here

Converting old log block to new (U5 to U6 upgrade)

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.

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

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

Upgrade: download verification issues

'gpgv' not installed

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

There are also other possible errors such as:

[!!!] WARNING: GPG/PGP verification failed. This could be a security issue.
Type 'IGNORE' in uppercase to continue if you think it is safe.
Type anything else to abort.

If you get that warning, with the note "This could be a security issue" then something might be seriously wrong. Please report to the UnrealIRCd team at [email protected] and/or https://bugs.unrealircd.org/.

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

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;


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

How to upgrade from 3.2.x

You can upgrade from 3.2.x to UnrealIRCd 6. Copy over your 3.2.x config files to your 6.x directory (in the conf subdirectory). Then run ./unrealircd upgrade-conf to convert your configuration files. 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?

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

  • Upgrade all servers at the same time, from 3.2.x to 6.x, in 1 big move. That is: kill all 3.2.x servers, then start all 6.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 6.x.

Why is the upgrade path so shitty for 3.2.x to 5.x/6.x?

So, you can upgrade from 3.2.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 6 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.


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)

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?

First of all, is UnrealIRCd really running? If on Windows: do you see a GUI? If on *NIX: do you see the process if you run ps x|grep ircd ?

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

Can you connect locally to your IRCd?

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 bound 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

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

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!

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)

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?

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?

On Linux (but not easily on Windows) you can double check if UnrealIRCd is actually listening on the port. You can 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

On *BSD you can do this via sockstat -l | grep unrealircd

syzop@vulnscan:~ $ sockstat -l | grep unrealircd
syzop     unrealircd 3578  12 tcp4   *:6667                *:*
syzop     unrealircd 3578  12 tcp4   *:6668                *:*
syzop     unrealircd 3578  12 tcp4   *:6900                *:*
syzop     unrealircd 3578  12 tcp4   *:7000                *:*

In the examples 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

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

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

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

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

You basically have two options (choose 1):

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

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: Many IRC clients will not accept self-signed certificates by default 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 Using Let's Encrypt with UnrealIRCd.

Option 2: Allow insecure oper connections

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.

Check out the documentation:

I am missing server notices in UnrealIRCd 6

You are IRCOp but you are missing all or some server notices after you upgraded from UnrealIRCd 5 to UnrealIRCd 6?

In UnrealIRCd 6 lots of snomask letters changed, so maybe you have the wrong letters set. See the 5.x to 6.x Upgrade guide under Update your snomasks.

Also, as long as you run a mixed UnrealIRCd 5 - UnrealIRCd 6 network, you may miss some server notices, but not a lot.

Helpop doesn't work

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!!

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!!


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

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

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

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

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

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

hidden on the client-side

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?

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

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

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

short answer

Increase the sendq in your class block for the client (class::sendq).

This is the standard value in the example conf:

class clients
        pingfreq 90;
        maxclients 1000;
        sendq 200k;
        recvq 8000;

If 200k for the sendq is not enough, then simply double it to 400k, like this:

class clients
        pingfreq 90;
        maxclients 1000;
        sendq 400k;
        recvq 8000;

long answer

The error Max SendQ exceeded happens when a client issues a request that will return A LOT of data, too much to fit in the send queue. If you have large channels with like 400+ persons then a command like WHO #channel will return a lot of data. The maximum size of the send queue (queue of to-be-sent-data) is then hit and the client is disconnected with the Max SendQ exceeded message. Some clients do WHO #channel automatically on-join, others do not. This explains why some clients may go Max SendQ exceeded and others don't have this problem. Similarly, this explains why everything may seem to be working great for a long time, until you hit a certain large number of users (hundreds or thousands) in a single channel, and then suddenly lots of people go Max SendQ exceeded on join.

The solution is to simply increase the sendq. Something like 200k is standard these days. If needed you can bump to 400k or even more.

For IRCOps 1M is standard, so they can safely request lots of data like through STATS gline. Don't give normal users a 1M sendq (non-ircops), as maximum sendq is a protection mechanism against too much memory use and flooding.

hostnames are not resolving

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, viruses, drones

If your IRC network regularly receives spam and/or many (fake) users connecting, then check out the Security article, in particular the section Dealing with spammers and flooders.

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

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

You set vhost in the Oper block.

How do I get a title in /WHOIS

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

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

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)

What is cloaking

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

You have several options:

Option 1: make cloaking not the default

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

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

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

loadmodule "cloak";

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

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

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 other special groups of users (non-IRCOps) to flood at higher rates, see the Special users article.

Fakelag exemption is not working

Often people think the fake lag 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.

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?

Some admins would like to block private messaging (PM) / direct messaging (DM). Either completely, or partially such as only to authenticated users.

See "Disable private message" in the Security article for all information. It talks about temporarily disabling private messaging, but of course you can also choose to do so permanently as a matter of policy.

ERROR: Spamfilter type 'posix' is DEPRECATED

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

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

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).

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

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?

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

My server is under attack

If your server is currently under attack of drones/bots, DoS or DDoS, spammers or anything, then check out the Security article which tells all about what you can do in such a case.

Linking servers

How do I link two (or more) IRC servers

Have a look at our Tutorial: Linking servers.

Trouble with linking two IRC servers

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

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

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.

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.

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

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

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. Here are a few examples:

  • 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


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

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

You may see the following error during linking:

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

What it means

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

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

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

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

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

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

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

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?

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

WARNING: Bad ulines

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

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

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

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

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?

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?

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 them to this page.


Where is NickServ? ChanServ?

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?

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?

See the Services article.

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

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?

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

Are you services really online?

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

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

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

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)


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

My server crashed!!

If UnrealIRCd crashed and you are on a reasonably recent version then go to https://bugs.unrealircd.org/ and sign up for an account. Then click Report issue. Try to give as much information as possible. At the end of that form be sure to set View status to private so only developers can see the crash report.

TIP: If you are on *NIX then when you start UnrealIRCd via ./unrealircd start it should prompt you to submit a crash report. If you answer 'Yes' to that question then we receive the bug report with a core file and other useful information. You can also enter your email address there so we can contact you back (this is recommended).

Here is a statistic to keep in mind: more than 90% of the crashes reported are caused by source code modifications or 3rd party modules. So they are caused by source code not written by us (outside our control). If you run with 3rd party modules (this is very common) then it is still OK to submit the bug report. We will try to see if the crash is caused by UnrealIRCd or by a 3rd party module and report back to you (this is why it is important to leave your contact details). In some situations we may ask you to run without 3rd party modules. As said, just do the bug report and you will hear later.

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

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?

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?

Installing the module

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 6\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.

Only SSL/TLS users allowed

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

  • 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

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 ...";

Why does the example.conf not contain all options?

From time to time people ask why example.conf does not contain feature X, Y, Z, or simply all the possible set options, config blocks, and so on. It could be much larger with lots of examples on EVERYTHING. So why is this not the case?

There are several reasons for this, all of them being important:

  1. Size/readability: We want the example.conf to stay reasonably "small". It shouldn't scare beginners off. It should also not lead to a huge unreadable unrealircd.conf for anyone (beginners AND advanced users).
  2. Upgrade problems: From time to time (eg UnrealIRCd 4.0.x to 4.2.x to 5.x) we change the syntax of configuration items. Let's assume people use example.conf to create their unrealircd.conf (which is a reasonable assumption, as it is the recommended method and workflow of basically everyone in every software out there), then this would be problematic:
    • Right now, with the simple unrealircd.conf we have, if we change an option that only 1% of the people use/have in their conf file then only 1% of these people would need to update their configuration file with the new syntax.
    • On the other hand, if example.conf (and thus unrealircd.conf) would have every possible option then 100% of the people need to update their conf, even for an option that they never changed at all (and may not even know what it does).
  3. Old defaults: The same is true for changing defaults. From time to time we change the default value. This is impossible if every example.conf and unrealircd.conf already have a value set.. since then the default value is never used. That would be such a shame because we tend to pick "good defaults" and update them over time based on development and new insights, eg. more strict flood limits. It would mean all those people would be stuck with old defaults which may be less secure, less optimal, etc.
  4. Lots of extra (duplicate) work: Whenever the wiki documentation is updated, the example conf would have to be updated as well. So that would be more work but it is also easy for these two places to get out of sync, it is basically guaranteed to happen. Then it brings up the question which one is the correct one or more up to date, with all the associated problems. We have the same issue with some of the HELPOP items, but for documentation on settings it would be much more and a lot worse.
  5. Translations: Our example.conf is translated in multiple languages. If it would be much bigger then it would put more burden on our translators too, for every translator, so the work is compounded eg. 4 times if we have 4 example.xx.conf like now.

Sometimes it is suggested to have two example confs, one small example.conf (like now) and one very verbose, let's call it example.detailed.conf. This only solves problem #1 but still brings the same problems #2 and #3 if people start using that for their unrealircd.conf. Problems #4 and #5 remain too. It's better to just use the wiki to get to see all the options, you can see all the set options in Set block for example. Another benefit of the wiki is that it is kept up to date (even on a daily basis) and contains examples for various uses cases, can easily link to different related options, etc. etc.

So, long story short: it is not a weird idea to ask for all options in example.conf, but it has been carefully considered and is rejected on good grounds as it will cause more harm than it will do good.

High connection rate detected


You may receive warning like this:

[warn] High rate of connection attempts detected: 1001 exceeds 1000: some functionality is disabled. This could be an attack, or lots of genuine users connecting after a network outage.
[warn] This message will appear every 10 minutes for as long as this is the case. You will NOT get a notification if all is normal again (which is evaluated every 5 seconds). See https://www.unrealircd.org/docs/FAQ#hi-conn-rate

This means clients are trying(!) to connect to your server at the specified rate per second. The default setting is 1000 and the (non-adjustable) sample interval is 5 seconds, so hitting this 1000 connects per second for 5 seconds straight would be unusual in a normal situation. This could therefore be an attack with many drones trying to connect (but likely most of them not coming online on IRC, already being rejected before that). There is also a small chance that this warning shows up in non-attack situations such as if there was a network outage before and the network is back and lots of users are (re)connecting to your server.


The following functionality will be disabled temporarily:

  • We no longer print error messages to SSL/TLS users who are not allowed to connect. For example due to connect-flood, handshake flooding, etc.
  • We no longer do DNS lookups before checking connect-flood exceptions in except ban { } and ELINE.

This is all done to save CPU and other resources to withstand the peak situation. In general this effect is not a big problem, but you are made aware that functionality is reduced somewhat and that your server is possibly under attack (see Cause above).

In all cases, the situation is evaluated every 5 seconds. As soon as the connection rate drops below the limit, it is disabled and all is normal again. And if it goes above the limit (evaluated every 5 seconds) it is immediately turned on again. UnrealIRCd does not send warnings about it being turned off because of the potential of constant on/off switching every 5 seconds (hypothetically, anyway). It only prints the message at a maximum rate of 1 per 10 minutes if the high rate mode is on.


This setting can be changed via set::high-connect-rate. If you have low-end hardware like an old Raspberry Pi then this might be a good idea.

History mode (+H) causes my bot to re-trigger previous commands - What do I do?

UnrealIRCd sends history playback on join if the client supports the server-time capability

Solution 1

The simplest solution is to make the bot ask for the capability (or CAP) draft/chathistory (usually during connection):

CAP REQ draft/chathistory

When a client uses the draft/chathistory capability, UnrealIRCd will never send chathistory to it by itself. It will only send history if the client asks for it using the CHATHISTORY command. So as long as the bot does not use the CHATHISTORY command, it will never receive channel history. Problem solved!

Solution 2

This is only for developers of bots:

  1. Make the client also support batch capability, see https://ircv3.net/specs/extensions/batch
  2. The bot can then detect the playback-on-join because the history playback is wrapped in a batch of the type chathistory:
:maintest.test.net BATCH +98yW6blDPLeAbEBdn3xJuI chathistory #test
@batch=98yW6blDPLeAbEBdn3xJuI;time=2023-03-18T15:47:04.944Z :[email protected] PRIVMSG #test :i like apples
@batch=98yW6blDPLeAbEBdn3xJuI;time=2023-03-18T16:38:33.953Z :s5667!~x@oper/netadmin.test.net PRIVMSG #test :that's fantastic
:maintest.test.net BATCH -98yW6blDPLeAbEBdn3xJuI

Note the chathistory in the first line.

How can I allow other message tags?

In UnrealIRCd you need to have a module for each message tag. See the Message tag article for all the built-in supported message tags. UnrealIRCd supports almost all IRCv3 server message tags.

For client message tags too, a message tag handler needs to be loaded by a module. This is a design decision. The IRCv3 work group created client message tags where 1) the server has no idea which client tags the client supports and 2) allows a lot of traffic via message tags (4096 bytes per line, much more than the convential 512 bytes per line). This was with good intentions, allowing tags to be created without having to wait for server support and lots of room (bytes), but according to the UnrealIRCd head coder this creates a number of security and moderation issues. These problems are explained in detail in this IRCv3 discussion thread. In UnrealIRCd we deal with these problems by requiring a module for each message tag, including client message tags, these modules can then inspect and filter specific values.

Examples of client tags that we support out of the box (as seen in the Message tags article) are +typing and +draft/reply. As discussed in the IRCv3 discussion thread quoted earlier, the potential problems are under control for these tags. The +typing tag allows only a few values and the the +draft/reply tag only allows limited data (a msgid). And just as important: both these tags pose zero to nearly no moderation problem or issues for clients that don't see these tags.

An example of a tag that we will not support in UnrealIRCd is +draft/react. The problem is that ONLY clients supporting that tag can see the text of the reaction, and all other people in the channel don't see the text. This causes confusion and moderation issues and destroys the general principle of IRC where everyone can run their own client of choice and be "part of the conversation".

All in all, UnrealIRCd takes the middle ground: it is not one of the IRCds that refuses to implement (client) message tags, but also not one that blindly allows 100% through with all its consequences.

If you have a (client) message tag in mind that is not supported out of the box:

  • Check out https://modules.unrealircd.org/ to see if there's a 3rd party module for it. At the time of writing there are 3rd party modules for +draft/react and +draft/display-name.
  • Consider raising an issue on https://bugs.unrealircd.org/ for the tag, explaining why the message tag would be beneficial to the general audience and a link to the formal specification. Taking into account what has been said in this FAQ item.
  • If you don't think the tag is useful to the general audience but is very specific to your network, then consider making a 3rd party module. You can peek at the existing 3rd party modules or official message tag modules. Things to keep in mind while coding such a module are: contain the length of the message tag and, if possible, the content. Other thoughts: think about what would happen if a client does not support the message tag and thus would not display it or take any action, would it cause confusion or issues? What if someone would flood witht his tag? You can also, optionally, create any other restrictions on the tag if you like, for example, requiring a services account, a certain mode, oper status, or whatever you like.