Matt Hughes tinkerer, grower, craftsman

Setting up an IRC server with charybdis and atheme

First off, decide which versions of the software you're going to be using. I used the latest stable versions, which were charybdis-3.4.2 and atheme-7.2.6 at the time of this post.

Check out the release pages for charybdis and atheme for a full listing of releases.

tar -xvf charybdis-3.4.2.tar.gz
mv charybdis-charybdis-3.4.2/ charybdis

tar -xvf atheme-7.2.6.tar.gz
mv atheme-atheme-7.2.6/ atheme

Go on and install build-essential and automake, if you don't have them already.

sudo apt-get install build-essential automake

Building Charybdis

Install some packages required by charybdis:

sudo apt-get install libssl-dev byacc flex

Now you're ready to build ircd!

cd ~/charybdis
./configure prefix=/usr/local/charybdis --enable-openssl --enable-small-net
sudo make install
sudo chown -R USER:USER /usr/local/charybdis

Building Atheme

Install a couple of prerequesite packages. I have no idea what libqrencode does, but QR codes over IRC seem fun:

sudo apt-get install gettext libqrencode-dev

Install git, if you don't have it already:

sudo apt-get install git

You'll need to run a couple of git commands to get the correct source code for the contrib module and libmowgli.

cd ~
git clone git:// atheme-dev
cd ~/atheme-dev/
git submodule init
git submodule update
cp -R modules/contrib/* ../atheme/modules/contrib/
cp -R libmowgli-2/* ../atheme/libmowgli-2/

We also need one file from the charybdis source, to prevent a build error:

cd ~
cp ~/charybdis/include/serno.h ~/atheme/include/

Now you're ready to build atheme!

cd ~/atheme
./configure --prefix=/usr/local/atheme --enable-ssl --enable-contrib --enable-examples
sudo make install
sudo chown -R USER:USER /usr/local/atheme

Fun with config files

Here's where the real fun starts!

charybdis configuration

First, navigate to your charybdis config directory, and copy the example config file to ircd.conf.

cd /usr/local/charybdis/etc
cp ircd.conf.example ircd.conf
vim ircd.conf

There are a few places we will want to make our edits:

  • serverinfo block for basic server configuration
  • admin block for your contact info
  • connect and service blocks for IRC services

You'll also want to edit ircd.motd, and add a fun "message of the day" that users will see when they connect to your server.


Edit the first several lines of the serverinfo block, like so:

serverinfo {
    name = "";
    sid = "55A";
    description = "Your IRC Server";
    network_name = "Network";
    network_desc = "Your IRC network.";

The sid value should be "one digit and two characters which can be digits or letters", according to the Operators guide for the charybdis IRC server.


Add your contact info to the admin block, like so:

admin {
    name = "Matt Hughes";
    description = "Your friendly IRC admin";
    email = "";

Users can see this information when they run the /admin command in their IRC client.


Add/edit a connect block for the atheme-services daemon. The value in quotations should match the serverinfo name value in the atheme.conf file. We'll get to the atheme.conf file shortly.

connect "" {
    host = "";
    send_password = "server_password";
    accept_password = "client_password";
    port = 6668;
    class = "server";


You want this value to match the serverinfo name value when we start editing the atheme.conf file.

service {
    name = "";

atheme configuration

Navigate to your atheme directory, and copy the example config to atheme.config.

cd /usr/local/charybdis/etc
cp ircd.conf.example ircd.conf
vim ircd.conf

There are two blocks we need to edit in atheme.conf:

  • serverinfo for basic information
  • connect to connect to our IRC server


These edits are very similar to the ones we made in ircd.conf:

serverinfo {
    name = "";
    desc = "Atheme IRC Services";
    numeric = "61B";
    netname = "Your IRC Network";
    adminname = "Matt Hughes";
    adminemail = "";
    auth = none;

There are logs of other values in the serverinfo block; I only included the ones that need to be changed above. Make sure that the name and numeric values are no the same ones you used in ircd.conf. The auth value relates to how nicks are registered. You can require e-mail validation to register a nick, but I omitted it for simplicity.

Edit the uplink block so:

uplink "" {
    host = "";
    send_password = "client_password";
    receive_password = "server_password";
    port = 6668;

A few notes:

  • The value in quotes should be the serverinfo name value from your ircd.conf
  • The host value of assumes that you're running charybdis and atheme from the same machine
  • Make sure the send_password and accept_password values are reversed from the values in ircd.conf

Let's try it out!

Start up charybdis:

notice: starting charybdis-3.4.2 ...
notice: libratbox version: 20081213_1-26296 - Using SSL: OpenSSL 1.0.1f 6 Jan 2014 compiled: 0x1000106f, library 0x1000106f
notice: now running in background mode from /usr/local/charybdis as pid 30887 ...

Start up atheme:

[2015-09-28 17:27:55] atheme 7.2.6 is starting up...
[2015-09-28 17:27:55] module_load(): module /usr/local/atheme/modules/nickserv/list is already loaded [at 0x214d1f0]
[2015-09-28 17:27:55] module_load(): module /usr/local/atheme/modules/groupserv/main is already loaded [at 0x2150ea0]
[2015-09-28 17:27:55] opensex: grammar version is 1.
[2015-09-28 17:27:55] corestorage: data schema version is 12.
[2015-09-28 17:27:55] groupserv: opensex data schema version is 4.
[2015-09-28 17:27:55] pid 30910
[2015-09-28 17:27:55] running in background mode from /usr/local/atheme

Now you're ready to connect with your IRC client (I prefer HexChat) and register your nick with NickServ!

In your IRC client, run the /connect command:


You should see some output like this:

* Looking up
* Connecting to (x.x.x.x:6667)
* Connected. Now logging in.
* *** Looking up your hostname...
* *** Checking Ident
* *** Couldn't look up your hostname
* *** No Ident response
* Capabilities supported: account-notify away-notify extended-join multi-prefix sasl
* Capabilities requested: account-notify away-notify extended-join multi-prefix 
* Capabilities acknowledged: account-notify away-notify extended-join multi-prefix 
* Welcome to the FunCollider Internet Relay Chat Network GenBurnside
* Your host is funcollider.irc[funcollider.irc/6667], running version charybdis-3.4.2
* This server was created Fri Sep 25 2015 at 12:31:12 EDT
* yourserver.irc charybdis-3.4.2 DQRSZagiloswz CFILPQbcefgijklmnopqrstvz bkloveqjfI
* SAFELIST ELIST=CTU CHANTYPES=&# EXCEPTS INVEX CHANMODES=eIbq,k,flj,CFLPQcgimnprstz CHANLIMIT=&#:15 PREFIX=(ov)@+ MAXLIST=bqeI:100 MODES=4 NETWORK=FunCollider KNOCK :are supported by this server
* There are 0 users and 11 invisible on 2 servers
* I have 2 clients and 1 servers
* 2 2 :Current local users 2, max 2
* 11 11 :Current global users 11, max 11
* Highest connection count: 3 (2 clients) (2 connections received)
* - yourserver.irc Message of the Day - 
* - ================================================================================
* -                                    Welcome!  
* - ================================================================================
* - End of /MOTD command.

Now see if atheme-services is running correctly:

/NickServ help

You should get a list of commands back from NickServ:

-NickServ- ***** NickServ Help *****
-NickServ- NickServ allows users to 'register' a nickname, and stop
-NickServ- others from using that nick. NickServ allows the owner of a
-NickServ- nickname to disconnect a user from the network that is using
-NickServ- their nickname.
-NickServ- If a registered nick is not used by the owner for 30 days,
-NickServ- NickServ will drop the nickname, allowing it to be reregistered.
-NickServ- For more information on a command, type:
-NickServ- /msg NickServ help <command>
-NickServ- For a verbose listing of all commands, type:
-NickServ- /msg NickServ help commands
-NickServ- The following commands are available:
-NickServ- GHOST           Reclaims use of a nickname.
-NickServ- GROUP           Adds a nickname to your account.
-NickServ- IDENTIFY        Identifies to services for a nickname.
-NickServ- INFO            Displays information on registrations.
-NickServ- LISTCHANS       Lists channels that you have access to.
-NickServ- REGISTER        Registers a nickname.
-NickServ- SENDPASS        Email registration passwords.
-NickServ- SET             Sets various control flags.
-NickServ- UNGROUP         Removes a nickname from your account.
-NickServ-                 STATUS, TAXONOMY, VACATION, VERIFY
-NickServ- ***** End of Help *****

Having trouble?

As I learned the hard way in setting up IRC and services a few times, it's easy to mess up! The charybdis and atheme logs are your friends: