Setting up and managing an InspIRCd cluster

  • Author:Robert Whitney
  • Date:2018/01/22

IRC is a simple idea, and should be simple to manage. Unfortunately by design it isn’t simple to manage a cluster of IRC servers.
InspIRCd attempts to fill the gap with remote configuration files which can be included via executable (eg- wget -O -

Unfortunately using wget to grab up your configuration can lead to undesired side-effects. For example if your configuration fails to load from the website, you may find that all your modules, olines, etc. become unloaded. I have attempted to fix this via a simple configuration management tool written in nodejs. This post will walk you through setting up your IRCd and the configuration manager system-wide.

If instructions are unclear or something is missing from this guide then please let me know via the comments. Everything in this guide should work on Debian/Ubuntu systems and the like. Please let me know in the comments if you need to divert from the instructions for any reason.

IRCd Setup

You will need to perform these steps for each server that you would like to build an IRCd on.
Update: /var/run/irc has been changed to /home/irc due to /var/run being a tempfs on many distributions.

# apt-get install build-essential openssl libssl-dev pkg-config npm git
# mkdir /home/irc
# mkdir /home/irc/.ssh
# chown irc:irc /home/irc
# chsh irc -s /bin/bash
# usermod -d /home/irc irc
# mkdir $HOME/src
# cd $HOME/src
# git clone
# cd inspircd/
# git checkout insp20
# ./configure --prefix=/opt/inspircd --enable-openssl --uid=irc
# make && make install
# chown -R irc:irc /opt/inspircd
# chmod -R 0770 /opt/inspircd
# wget -O /etc/systemd/system/ircd.service
# chmod +x /etc/systemd/system/ircd.service
# systemctl enable ircd.service

While this makes go ahead and get yourself a cup of coffee and read through the next steps.
When it’s finished you should see something like this at the end of the output:

*        INSTALL COMPLETE!          *
  Base install: /opt/inspircd
  Configuration: /opt/inspircd/conf
  Binaries: /opt/inspircd/bin
  Modules: /opt/inspircd/modules
  Data: /opt/inspircd/data
To start the ircd, run: /opt/inspircd/inspircd start
Remember to create your config file: /opt/inspircd/conf/inspircd.conf
Examples are available at: /opt/inspircd/conf/examples/


You will need to setup your configurations how you want them based on the example configurations provided by InspIRCd. This will operate as a base configuration for your network so setup your configurations how you want them, then proceed to the configuration management step. Make sure you use absolute paths for all includes.

Remember that while you are building your configuration you will want to place certain variables which will be used when generating the final configuration file for the program.


  • &ipv4-addr; - Put this wherever you need the IPv4 address of the server.
  • &ipv6-addr; - Put this wherever you need the IPv6 address of the server.
  • &network-name; - Put this wherever you need the network name.
  • &server; - Put this wherever you need the server address (eg-
  • &adminName; - Put this wherever you need the name of the admin for the server.
  • &adminNick; - Put this wherever you need the nickname of the admin for the server.
  • &adminEmail; - Put this wherever you need the email of the admin for the server.

InspIRCd configuration example

Final Configuration

Once your configuration is done your directory structure should look something like this:

|- conf
|\- base
| \- inspircd.conf
|\- sync
| |- modules.conf
| |- opers.conf
| \- rules.txt
\- .gitignore

Update: An example of what your configs might look like can be found here.

Make sure you saved your inspircd.conf in the base directory.
The setup above would need a .gitignore file which would look something like this:


Configuration Management

Preparing configurations for deployment

You will need to setup a git repository (if it’s not private, you’re doing it wrong). Once your git repo is setup simply push your configs out to the repo. The structure of your configuration files should look like the one shown above minus the local directory which will be created on a per-server basis.
Make sure to setup deploy keys on your repository for your configuration for the irc account on each server that you setup otherwise you won’t be able to pull the configuration files.

config-manager Setup

You will need to open up a root terminal again and type the following commands:

# su - irc # login to irc user
$ ssh-keygen
$ cat $HOME/.ssh/ # copy the public key for later use.
$ exit # logout of irc user
# mkdir /opt/config-manager
# wget -O /opt/config-manager/pull.js
# wget -O /opt/config-manager/config.json
# npm install --save fs replaceall simple-git
# su - irc # login to irc user
$ cd /opt/inspircd/conf
$ rm -rf examples
$ git clone <[email protected]:config/path> . # git clone the configuration repository that you setup above.
$ mkdir local/
$ touch local/links.conf local/motd.txt local/opers.conf local/ssl.cert local/ssl.key inspircd.conf # be sure to actually edit these files too!
$ exit # end session as irc user.

Deploy configurations

The configuration file for config-manager is stored at /opt/config-manager/config.json and needs to be edited before you continue to the next step…

The configuration file at /opt/inspircd/conf/inspircd.conf should look something like this:

<include executable="/usr/bin/node /opt/config-manager/pull.js">
<include file="/opt/inspircd/conf/sync/modules.conf">
<include file="/opt/inspircd/conf/sync/opers.conf">
<include file="/opt/inspircd/conf/local/opers.conf">
<include file="/opt/inspircd/conf/local/links.conf">

Make sure the path to your nodejs install is correct, sometimes it is /usr/bin/nodejs instead of /usr/bin/node. In that case you will either need to create a symlink (recommended) or change the executable include to point to the correct path.

Once everything has been set in place then you can startup the IRCd with the command service ircd start. You can check the status to see if the IRCd is running properly by running service ircd status.

Robert Whitney
I'm a geek, gamer and breaker of things.
Opinions expressed here, even 💩 ones, are my own and do not represent those of my employer or associates.
Referral Links

Using my referral links is the best way to help me pay for my projects and development servers and get something out of it for yourself.

Copyright©2011 - 2018, Robert Whitney; All rights reserved.
Aeon Address: WmtnQAoEJsfbcjyMJLmfW8SJ3j5VCGGjX4k3hHrc4XbhVcz6dxifHs65h2w3y5gq8Qf4D4tgzb6VxEtggSq5hR8s1CzN1cLeK