Installing Atheme

Atheme is a set of IRC services. It is cross-platform (runs on Linux and BSD) and works well with a variety of IRCds such as ngircd.

Atheme provides users with the NickServ, ChanServ and other *Serv that users expect from IRC. This allows users to register their nicknames, channels, and much more.


First, install cmake and gettext-tools (internationalization support):

Please note that you may have to update your gcc compiler to a newer version.

$ doas pkg_add cmake gettext-tools

Create a new user for atheme:

$ doas useradd -m -g =uid -c "atheme" -d /home/atheme -s /bin/ksh atheme
$ doas su atheme
$ cd

Next, download the latest of Atheme:

$ ftp
$ unxz atheme-services-v7.2.12.tar.xz
$ tar -xf atheme-services-v7.2.12.tar
$ cd atheme-services-v7.2.12

Before proceeding, make sure to thoroughly read and the doc/ folder.

$ ./configure

This will now build a default configuration.

You will now see a default configuration like this below:


	Atheme version       : 7.2.12
	Installation prefix  : /home/atheme/atheme
	Module root directory: ${exec_prefix}/modules
	Config directory     : ${prefix}/etc
	Logfile directory    : ${prefix}/var
	Data directory       : ${prefix}/etc
	PID directory        : ${prefix}/var
	Reproducible builds  : no
	Large network support: no
	OpenSSL support      : yes
	GNU libidn support   : no
	Contrib modules      : no
	Mowgli installation  : Internal
	PCRE support         : no
	Perl support         : no
	QR Code support      : no
	CFLAGS               : -I/home/atheme/atheme-services-v7.2.12/libmowgli-2/src/libmowgli -g -O2
	Internationalization : no

Once you see this you are now ready to start building.

Please note that using 'make' or 'make install' might cause errors so please use 'gmake' and 'gmake install' instead to avoid compiling errors.

$ gmake
$ gmake install

Lets now create your atheme.conf:

$ cd ~/atheme/etc/
$ cp atheme.conf.example atheme.conf

Now before you start editing your atheme.conf we need to make sure that we create a new services.db file else atheme will NOT work.

To do this:

$ touch services.db

editing atheme.conf:

#loadmodule "modules/crypto/argon2d";
loadmodule "modules/crypto/posix";

Change 'loadmodule "modules/crypto/posix";' to 'loadmodule "modules/crypto/pbkdf2v2";' so your configuration looks like this.

#loadmodule "modules/crypto/argon2d";
loadmodule "modules/crypto/pbkdf2v2";

Let's now start adding your ircd's link block to atheme.conf:

serverinfo {
        name = "";
        desc = "Atheme IRC Services";
        numeric = "00A";
        recontime = 10;
        netname = "misconfigured network";
        hidehostsuffix = "users.misconfigured";
        adminname = "misconfigured admin";
        adminemail = "misconfigured@admin.tld";
        registeremail = "noreply@admin.tld";
        mta = "/usr/sbin/sendmail";
        loglevel = { error; info; admin; network; wallops; };
        maxlogins = 5;
        maxusers = 5;
        mdlimit = 30;
        emaillimit = 10;
        emailtime = 300;
        auth = none;
        casemapping = rfc1459;

Replace '' with your real services link block name example:

Then set your netname to your networks name example: IRCNow

Once you have configured this then it's now time to move on to your uplink settings in atheme.conf:

uplink "" {
        host = "";
        #vhost = "";
        send_password = "mypassword";
        receive_password = "theirpassword";
        port = 16667;

Please change up host to your servers host example:

The localhost ip should be fine if running atheme services from the same machine otherwise please use the real ip address of the server you are linking to.

You can leave #vhost commented out for running on localhost otherwise uncomment out for your real machines ip address.

Send and receive password in most cases can be set the same password as some ircd's only need 1 password for linking.

We now need to set your ircd's protocol module for atheme to work in this case we will be using ngircd.

you will see this line in your atheme.conf:

#loadmodule "modules/protocol/charybdis";

We need to change this to use ngircd's protocol module by changing it to this:

loadmodule "modules/protocol/ngircd";

Once you have done this then go ahead and set what hostname your services will use normally

there will be a line in each service such as ChanServ NickServ for the host they should use.

host = "";

Set them to any services name you wish for them to use heres a example:

host = "";

Configuring ngircd.conf

In ngircd.conf, you need a block that looks like this:

	Name =
	Host =
	;Bind =
	Port = 16667
	;Group = 123
	Passive = yes
	SSLConnect = false
	ServiceMask = *Serv,Global

Replace with the actual services hostname. The host will likely be (again, because atheme is running on the same server as ngircd). The port should be 16667.

Make sure that MyPassword matches the server password for the uplink block in atheme. Set Passive to yes so that ngircd does not automatically connect to atheme (let atheme initiate the connection), and turn off SSL.

Finally, we set the ServiceMask. This lets ngircd know that the nicknames *Serv and Global belong to IRC Services.

If ngircd is already running, remember to reload changes to ngircd.conf:

$ doas rcctl reload ngircd

NOTE: restarting ngircd is unnecessary and results in downtime.

To start services:

$ cd ~/atheme/bin
$ ./atheme-services

If './atheme-services' fails, please double check the conf file.

No Automation At This Time


If you run into issues, check /home/atheme/atheme/var/ for log files.