Matt Hughes tinkerer, grower, craftsman

Setting up an IRC server with charybdis and atheme - updated for 2018!

I've been tinkering with a FeedTheBeast server instance on and off the past month or so, and got interested in piping the in-game chat to an IRC channel again (like we did in the glory days of SushiCraft). Because it's way more fun to build things from scratch, I used my previous post as a guide to installing IRC and services on the same server. That post has gotten pretty outdated, and decided it could use an update.

First off, decide which versions of the software you're going to be using. The latest versions were charybdis-4.1.1 and atheme-7.2.10-r2 at the time of this post.

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

$ wget https://github.com/atheme/charybdis/archive/charybdis-4.1.1.tar.gz
$ tar -xvf charybdis-4.1.1.tar.gz
$ mv charybdis-charybdis-4.1.1/ charybdis

$ wget wget https://github.com/atheme/atheme/releases/download/v7.2.10-r2/atheme-v7.2.10-r2.tar.xz
$ tar -xvf atheme-v7.2.10-r2.tar.xz
$ mv atheme-v7.2.10-r2/ atheme

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

$ sudo apt install build-essential automake


Building Charybdis

Install some packages required by charybdis:

$ sudo apt install flex libsctp-dev libssl-dev libtool libzip-dev

Now you're ready to build ircd!

$ cd ~/charybdis
$ ./autogen.sh
$ ./configure prefix=/usr/local/charybdis
$ make
$ sudo make install
$ sudo chown -R USER:USER /usr/local/charybdis


==========================================

Building Atheme

Install a couple of prerequisite packages. I have no idea how libqrencode integrates with Atheme, but QR codes over IRC seems like fun:

$ sudo apt install gettext libqrencode-dev

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

$ sudo apt install git

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

$ cd ~/atheme    
$ git submodule update --init

Now you're ready to build atheme!

$ ./autogen.sh
$ ./configure --prefix=/usr/local/atheme --enable-contrib --enable-examples
$ make
$ 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.

serverinfo

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

serverinfo {
    name = "yourserver.com";
    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.

admin

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

admin {
    name = "Matt Hughes";
    description = "Your friendly IRC admin";
    email = "matthughes404@gmail.com";
};

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

connect

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 "atheme.services" {
    host = "127.0.0.1";
    send_password = "server_password";
    accept_password = "client_password";
    port = 6668;
    class = "server";
};

service

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

service {
    name = "atheme.services";
};


atheme configuration

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

$ cd /usr/local/atheme/etc
$ cp atheme.conf.example atheme.conf
$ vim atheme.conf

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

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

serverinfo

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

serverinfo {
    name = "atheme.services";
    desc = "Atheme IRC Services";
    numeric = "61B";
    netname = "Your IRC Network";
    adminname = "Matt Hughes";
    adminemail = "matthughes404@gmail.com";
    auth = none;
}

There are lots 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 "yourserver.com" {
    host = "127.0.0.1";
    send_password = "client_password";
    receive_password = "server_password";
    port = 6668;
};

loadmodule protocol

Uncomment the the following loadmodule line to enable the Charybdis protocol:

loadmodule "modules/protocol/charybdis";

A few notes:

  • The value in quotes should be the serverinfo name value from your ircd.conf
  • The host value of 127.0.0.1 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:

$ /usr/local/charybdis/bin/charybdis
notice: starting charybdis-4.1.1 ...
notice: librb version: unknown - OpenSSL: compiled 0x1010007f, library OpenSSL 1.1.0g  2 Nov 2017
notice: now running in background mode from /usr/local/charybdis as pid 31139 ...

Start up atheme:

$ /usr/local/atheme/bin/atheme-services
[2018-10-16 21:27:00] atheme 7.2.10-r2 is starting up...
[2018-10-16 21:27:00] module_load(): module /usr/local/atheme/modules/nickserv/list is already loaded [at 0x5588155f1d90]
[2018-10-16 21:27:00] module_load(): module /usr/local/atheme/modules/groupserv/main is already loaded [at 0x5588155f5ac0]
[2018-10-16 21:27:00] db-open-read: database '/usr/local/atheme/etc/services.db' does not yet exist; a new one will be created.
[2018-10-16 21:27:00] pid 31766
[2018-10-16 21:27:00] 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:

/server yourserver.com

You should see some output like this:

* Looking up yourserver.com
* Connecting to yourserver.com (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
* STATUSMSG=@+ CALLERID=g CASEMAPPING=rfc1459 CHARSET=ascii NICKLEN=30 MAXNICKLEN=31 CHANNELLEN=50 TOPICLEN=390 ETRACE CPRIVMSG CNOTICE DEAF=D :are supported by this server
* MONITOR=100 FNC TARGMAX=NAMES:1,LIST:1,KICK:1,WHOIS:1,PRIVMSG:4,NOTICE:4,ACCEPT:,MONITOR: WHOX CLIENTVER=3.0 :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-  
-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-  
-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-  
-NickServ- Other commands: ACC, DROP, HELP, LISTGROUPS, LOGOUT, SETPASS, 
-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:

/usr/local/atheme/var/atheme.log
/usr/local/charybdis/logs/ircd.log
/usr/local/charybdis/logs/serverlog