1. Getting Started

Running an IRCd takes time, effort, and plenty of knowledge about IRC, networking, and about the operating system you are intending to run it on. If you don't know any of the following terms, you are not fit to run an IRCd: router, firewall, nameserver, oper, public IP, private IP, DNS, NTP.

Note: This tutorial is designed for Unreal 3.2.7 and newer. Older versions are not compatible with some of these settings.

Getting Unreal:

  1. Go to www.unrealircd.com.
  2. From the left, download the proper version. If you are on Windows, be sure to select either Win32 or Win32-SSL.

2. Installing


Run the installer.


  1. Get the .tar.gz file on your shell by either uploading it with FTP, or using WGET (or simmilar).
  2. Extract the .tar.gz file using the following 2 commands:
    gzip -d Unreal3.2.3.tar.gz
    tar -xvf Unreal3.2.3.tar
  3. Go to the Unreal3.2 directory, and run:
  4. Answer the questions. When that completes, run:
  5. If you told ./Config anything other than the default for install path, you will need to run:
    make install

3. Required Configuration

3.1 Beginning

Configuring UnrealIRCd takes time and effort. A good configuration can take as little as 15 minutes for someone who knows what they are doing, and as long as a couple hours for someone who is new to running an IRCd. Following this is not a substitute for reading the documentation. You will need to read the documentation in order to properly configure some things here. This tutorial is meant to give you a basic setup to get your server running. In order to secure your server, or configure advanced features, you will need to read the documentation. The documentation is important, and you will need to read it to be able to get support from the Unreal support channel or forums. I cannot stress how important it is to read the documentation enough!

To begin, you will need to create a file called "unrealircd.conf" in main Unreal directory. Windows users might want to read [error] Couldn't open "unrealircd.conf"- No such file or directory, which tells you how to create unrealircd.conf without having Windows add a hidden file extension to the end of the file name. You may open this with your favorite text editor. For windows users, I recommend something that can display line numbers, as this will make things easier for fixing any errors.

Any configuration notation used here is the same as what is used in the Unreal documentation. Read section 4.1 of the Unreal documentation to get an explanation. If you don't, you will be lost!

Time to open unrealircd.conf, and start configuring!

3.2 Loading the Proper Modules

There are 2 modules that need to be loaded. The commands module, and the cloaking module. The commands module holds all the commands for your server, and the cloaking module is used to cloak users hosts. Note the extension on Windows is .dll, and *NIX is .so. Also, the default paths on *NIX may change depending on installation options.


loadmodule src/modules/commands.so;
loadmodule src/modules/cloak.so;


loadmodule modules/commands.dll;
loadmodule modules/cloak.dll;

3.3 The Me Block

This block is your basic server information.

me::name The name of your server.
me::info A short 1-line description of your server.
me::numeric This is your server's number. This can be anything between 0 and 254, and must be unique when linking.

me {
    name "irc.foonet.com";
    info "FooNet Server";
    numeric 1;

3.4 The Admin Block

This block is the administrative information about the server. This will be displayed when users type /admin. In this block, there is nothing set, and you may put just about whatever you like in it.

admin {
    "Bob Smith";

3.5 The Class Block

These are for making client classes. They allow you to specify parameters for classes of clients.

class::pingfreq How often the server will send a PING to each client.
class::maxclients The maximum number of clients that can be in this class at one time.
class::sendq How much data in bytes the server can send to the client at a time.
class::recvq How much data in bytes the client can send to the server at a time (flood control).

class clients {
    pingfreq 90;
    maxclients 500;
    sendq 100000;
    recvq 8000;

3.6 The Allow Block

This tells Unreal who is allowed to connect. There can be multiple allow blocks, and everyone who connects to the server must match one.

allow::ip The IP mask of users allowed to connect.
allow::host The hostmask of users allowed to connect.
allow::class The class the people connecting with this allow block will be placed in.
allow::maxperip The maximum number of connections allowed per IP at one time.

allow {
    ip *@*;
    hostname *@*;
    class clients;
    maxperip 5;

3.7 The Listen Block

Listen blocks tell Unreal which ports to listen on for connections.

IP and port In the listen block, you use the format IP:port. The IP is used to tell Unreal the interface IP to bind to. If you are on a shell, you will need to use an IP in these blocks. You can have 1 port, or a range of ports (like 6667-6669).

listen *:6667-6669;

3.8 The Set Block

This is where all the little settings go. There are many settings in this block, but these are only the required settings. They are separated in this list where there are sub-blocks in the set block.

set::kline-address This can be an email or web address, and is shown to people when they get K:Lined.
set::maxchannelsperuser This is the maximum channels a user can be in at one time.

set::default-server The server Unreal will tell users to connect to if the server is full.
set::services-server This is the name of your services server.
set::network-name The name of your network.

set::hosts::global The vhost Unreal will give global opers.
set::hosts::coadmin The vhost Unreal will give co-server administrators.
set::hosts::admin The vhost Unreal will give server administrators.
set::hosts::servicesadmin The vhost Unreal will give services administrators.
set::hosts::netadmin The vhost Unreal will give network administrators.

set::help-channel The network help channel This MUST be in quotes!
What Unreal will prefix cloaked hosts with.

set::cloak-keys The 3 cloak keys for your server.

set {
    kline-address "set.this.email";
    maxchannelsperuser 10;
    default-server none;
    services-server services.roxnet.org;
    network-name ROXnet;
    hosts {
        global "ircop.roxnet.org";
        coadmin "coadmin.roxnet.org";
        admin "admin.roxnet.org";
        servicesadmin "csops.roxnet.org";
        netadmin "netadmin.roxnet.org";
    help-channel "#help";
    hiddenhost-prefix "rox";
    cloak-keys {
        "and another one";
        "and another one";

4. Finding Errors

Once you are done configuring Unreal, save the conf, and start Unreal. If Unreal fails to start, check ircd.log for errors. If it is a configuration error, you will see lines in your log that look like:

[DATE] config error: unrealircd.conf:<line_number>: error text

When fixing these errors, just open up unrealircd.conf, find the line number, and see what the problem is.

5. Recommended Configuration

There are many more things to configure before you can have a conf that is good to use on a server with users. Here are a few more little things that should be in your conf.

5.1 Oper Block

In order to oper, you need to have an oper block. The oper block gives you the permissions you need to manage your server while connected. See section 4.7 of the documentation for an example and proper configuration of your oper block.

5.2 Including Files

There are some pre-configured files for your server which are useful to help users, and sometimes yourself. These are the files and their descriptions:

badwords.channel.conf This file has a pre-configured list of channel badwords that will be blocked with channel mode +G.
badwords.message.conf This is the list of badwords that will be blocked from PM's when the users have usermode +G.
dccallow.conf This is a list of files that can be harmful to users if sent with a virus.
help.conf This is all the /helpop data.
spamfilter.conf Spamfilters for common spam, viruses, and exploits.

To include these files, just simply use the Include Directive, which looks like:

include file.conf;

6. Services

There are many choices for services to use with Unreal. There are both services that run on *NIX, and services that run on Windows. Some services run on both Windows and *NIX, others don't. No matter which services you choose, each has its own installation and configuration. Setting up services takes more time. If you are lazy when configuring services, they will not work as you expect them to, so take your time and read their documentation!

Listed here are only a few of the many services packages out there. If you don't like the selection here, or just want to see what else is there, services packages are very easily found with Google.

Services Name Website *NIX Windows
Anope www.anope.org yes yes
Atheme www.atheme.org yes yes

This document is ©2005-2011 X-Tab.org, written permission must be obtained from X-Tab.org to copy and/or distrubute this document.
Some parts have been taken from the official UnrealIRCd documentation and may be copyrighted by the UnrealIRCd project.