Gentoo Wiki


This article is part of the HOWTO series.
Installation Kernel & Hardware Networks Portage Software System X Server Gaming Non-x86 Emulators Misc

Note: This guide only covers setting up the IRC daemon itself. For all the features you're probably used to on other IRC servers (chanserv, nickserv, etc), you'll need to set up "services", which are not a part of the UnrealIRCd distribution. See the recommended links at the end of the article for more information.


Emerging unrealircd

First off, you're going to need to emerge UnrealIRCd. Do this in the normal way:

Code: Emerging unrealircd
# emerge unrealircd

Note that at the end of the compiling, the authors leave us a little note informing us that UnrealIRCd won't run until we've correctly set up the /etc/unrealircd/unrealircd.conf file correctly. Let's move right along to that, shall we?

Editing unrealircd.conf

First off, I never expect my editing of the .conf file to go correctly on the first try. Consequently, we should make a backup of the unrealircd.conf file in case we foobar it ;-)

Code: Backup unrealircd.conf
# cp /etc/unrealircd/unrealircd.conf /etc/unrealircd/unrealircd.conf.orig 

The conf file warns you to read doc/unreal32docs.html (also online at the official site). While it does have a lot of information, and you should certainly read it, we'll run through the basic (required) configuration here.

Open up unrealircd.conf. The first thing is to uncomment the two "loadmodule" lines for *NIX. Do this now.

Code: Enabling Modules
/* FOR *NIX, uncomment the following 2lines: */
loadmodule "/usr/lib/unrealircd/modules/";
loadmodule "/usr/lib/unrealircd/modules/";

The config file allows you to control pretty much every part of the server. Don't let this intimidate you! Standard procedures apply: test changes incrementally, and keep backups! (You can always go back to the original file, since you've backed it up already. You did back it up, right?)

The next section includes several other .conf files. Standard stuff, just be aware of it in case you have to change any of it later.

The first required block is the "me" block.

Code: Basic server info in the "me" block
me {
	name "irc.your.tld";  # must be DNS name of the server
	info "Where all the cool kids hang out.";  # "tagline" for the server
	numeric 1;

"numeric" identifies this particular server among those on the network. Just set this to 1 unless you're implementing a IRC network with multiple linked servers, in which case it must be unique on each one. (Some services make use of this value too, so be aware of that.)

Next, let's fill in the admin information. This block is more or less freeform; the information here is returned as the output of the "/admin" command on the server. You can include more or less as much (or as little) information as you like, but it's generally good to have a name and e-mail address at the very least.

Code: The "admin" block is your place to shine
admin {
       "Arthur Dent";
       "Don't forget your towel."

UnrealIRCd groups connections into different "classes", which determine access rights, special options, and other things. By default, there are two classes: "clients" and "servers". You don't have to worry about "servers" unless you're setting up linked servers (and if you're doing that, you really should be reading the full documentation anyway, so I'm going to stop mentioning it.)

Set the maximum number of client connections in the "class clients" block.

Code: you need "clients"
class           clients
  pingfreq 90;
  maxclients 500;
  sendq 100000;
  recvq 8000;

That covers a basic configuration, but there's more. If you run the server without changing some of the other default settings, bad things could happen, so read on! (I've tried to highlight important settings that you really should change below.)

Code: "set" your server information in these blocks
set {
  network-name    "yourIRCnet";
  default-server    "irc.yourhost.tld";  # name of server to connect to if this one is full
  # if you don't have a services server, set next option to "ircservices.yourhost.tld" or similar
  services-server   "services.yourhost.tld";  
  stats-server    "stats.yourhost.tld";  # required if keeping stats
  help-channel    "#IRChelp";  # channel users should go to for help
  hiddenhost-prefix "hiddenprefix";  # prefix for hidden hosts (those with +x status)
  /* prefix-quit    "no"; */
  /* Cloak keys should be the same at all servers on the network.
   * They are used for generating masked hosts and should be kept secret.
   * The keys should be 3 random strings of 5-100 characters
   * (10-20 chars is just fine) and must consist of lowcase (a-z),
   * upcase (A-Z) and digits (0-9) [see first key example].
  cloak-keys {
    "and another one";
    "and another one";
  /* on-oper hosts: when a user sets mode +x to hide their hostname,
   * the IRCd will make it appear as though they are using the following hosts 
  hosts {
    local   "locop.yourhost.tld";  # for local opers
    global    "ircop.yourhost.tld";  # for global opers
    coadmin   "coadmin.yourhost.tld";  # for co-admins
    admin   "admin.yourhost.tld";  # for admins
    servicesadmin   "csops.yourhost.tld";  # for services-admins
    netadmin  "netadmin.yourhost.tld";  # for netadmins
    host-on-oper-up "no";  # if set, a user will automatically get +x when they /oper
set {
  kline-address "irc@your.server.tld";  # address for questions when a user gets banned ("k-lined"
  modes-on-connect "+ixw";  # default modes set when a user connects
  modes-on-oper  "+xwgs";  # default modes set when a user identifies to operator
  oper-auto-join "#opers";  # operators auto-join this channel
  dns {
    nameserver 123.45.678.9;  # set your DNS server!
    timeout 2s;
    retries 2;
  options {
    /* identd-check;  # when a user connects, check their identd response */
  maxchannelsperuser 10;  # max channels a user can be in at any one time
  anti-spam-quit-message-time 10s;  # anti-spam: max connected time before allowing a QUIT message
  /* static-quit "Client quit";  # ban custom QUIT messages */
  /* static-part yes; # "yes" bans custom 'part' reasons, other text sets 'part' comment */
  oper-only-stats "okfGsMRUEelLCXzdD";  # any stats listed here can only be used by operators
  # Limit reconnect rate. Default sets a limit of 3 attempts per host per 60sec.
  throttle {
    connections 3;
    period 60s;
  # Limits nick change rate. Default is 3 changes per user per 60sec.
  anti-flood {
    nick-flood 3:60;  /* 3 nickchanges per 60 seconds (the default) */
  spamfilter {
    ban-time 1d;  # default duration of a *line ban set by spamfilter
    ban-reason "Spam/Advertising";  # default reason for spamfilter bans 
    virus-help-channel "#help";  # channel to use for 'viruschan' action
    /* except "#help";  # spamfilter will not monitor this channel */

Testing Your Configuration

At this point, you should be ready to go! First, test your configuration file by starting unrealircd with no arguments:

Code: Moment of Truth...

If it doesn't like the conf file, it'll complain. If it doesn't, boot up your IRC client and try to connect.

You should use the script /etc/init.d/unrealircd to control the daemon, but this won't tell you if your configuration file's broken (at least, not in any log file I could find.)

To run the server at boot, use rc-update:

Code: Running the IRCd at boot
# rc-update add unrealircd default

For advanced configuration and more information, read the official documentation. In fact, you really should read it anyway. :)

Where to go from here? The next thing you'll probably want to do is set up a "services" package. This will enable service bots like NickServ, ChanServ, and the like. These are packaged separately. See this page for more information.

Happy IRCing!

Further Reading

Retrieved from ""

Last modified: Wed, 13 Feb 2008 06:26:00 +0000 Hits: 20,680