How to Install and Configure 'InspIRCd' on Linux


Tuesday 16th May 2017

InspIRCd is a modular Internet Relay Chat (IRC) server written in C++ for Linux, BSD, Windows and Mac OS systems.

This guide will cover installation, configuration and Let's Encrypt SSL. It is written with the assumption that you already have basic knowledge of Linux and IRC.

The guide is targeted at Ubuntu/Debian systems, however it should be possible to follow for other Linux distributions too. Just make sure to use the appropriate package management commands for your distribution.

The version of InspIRCd that I am using in this guide is 2.0.23, however you should be able to use the guide with newer versions. Just swap out 2.0.23 for the version number you are using.

The main focus for the configuration of InspIRCd outlined here is security and simplicity.

Jump to step: #1: Preparations | #2: Downloading and Verifying | #3: Installation | #4: Configuration Files | #5: Let's Encrypt SSL | #6: Final Configuration

Guide Created by Jamie Scaife 14th/15th May 2017.

Step #1: Preparations

a. It is highly recommended to create a new, unprivileged user account for running InspIRCd:

$ sudo adduser --disabled-password inspircd

This command will create a new user called "inspircd", with a disabled password. This means that there is no password set and you will not be able to log in with a password. Instead, you can just su into the user. If you'd like to set a password, simply omit "--disabled-password".

b. Install the required dependencies:

$ sudo apt-get install libgnutls-dev gnutls-bin pkg-config

If you are using a distribution other than Ubuntu/Debian, please see the InspIRCd Wiki for more information.

c. If you don't already have a command-line IRC client, it is useful to install one. I personally recommend Irssi:

$ sudo apt-get install irssi

d. Log in as your new user:

$ sudo su inspircd

Step #2: Downloading and Verifying

It is important that you do not install InspIRCd from the Debian/Ubuntu Universe package repositories. These packages are out of date and potentially insecure. The out of date packages are not the fault of the InspIRCd development team, but rather the independent package maintainers.

a. The source for InspIRCd can be downloaded from their GitHub repository. Visit the releases page and download the source code Tarball (.tar.gz) for the latest stable release. At the time of writing this guide, the latest version is 2.0.23.

########################################################################
InspIRCd 2.0.23 Source Code

Name: inspircd-2.0.23.tar.gz / v2.0.23.tar.gz
Size: 714.5 KB (731,695 bytes)
MD5: 8f9ae3c377334248af6f675b568d7234
SHA1: b1b575d2b3896f93b6a3a5b1cc7498541d223282
SHA256: 522b31fc80e8fd90b66837bf50f8a941233709d5b1fc9c0b3c47a413fb69f162
VirusTotal: 0/55 Detection Ratio
Link: https://github.com/inspircd/inspircd/archive/v2.0.23.tar.gz
########################################################################

You can download the file using wget:

$ wget https://github.com/inspircd/inspircd/archive/v2.0.23.tar.gz

b. Verify the integrity of your download:

$ sha256sum v2.0.23.tar.gz
522b31fc80e8fd90b66837bf50f8a941233709d5b1fc9c0b3c47a413fb69f162  v2.0.23.tar.gz
$ sha1sum v2.0.23.tar.gz
b1b575d2b3896f93b6a3a5b1cc7498541d223282  v2.0.23.tar.gz
$ md5sum v2.0.23.tar.gz
8f9ae3c377334248af6f675b568d7234  v2.0.23.tar.gz

c. Extract the compressed file:

$ tar xvf v2.0.23.tar.gz

Step #3: Installation

a. If you created a new user for InspIRCd, make sure you are logged in as it.

Change directory into the inspircd-2.0.23 directory:

$ cd inspircd-2.0.23

Press tab after the first few characters in order to autocomplete.

Now start the InspIRCd pre-compilation configuration.

$ ./configure

Follow the wizard, choosing the options as outlined below. Values that you should change are marked in bold and underline.

Welcome to the InspIRCd configuration program! (interactive mode)
Package maintainers: Type ./configure --help for non-interactive help

*** If you are unsure of any of these values, leave it blank for    ***
*** standard settings that will work, and your server will run      ***
*** using them. Please consult your IRC network admin if in doubt.  ***

Press <RETURN> to accept the default for any option, or enter
a new value. Please note: You will HAVE to read the docs
dir, otherwise you won't have a config file!

Your operating system is: linux (linux)
Your InspIRCd revision ID is r0
.

I have detected the following compiler: g++ (version 5.4)

In what directory do you wish to install the InspIRCd base?
[/home/inspircd/inspircd-2.0.23/run] ->
/home/inspircd/inspircd-2.0.23/run does not exist. Create it?
[y] y

In what directory are the configuration files?
[/home/inspircd/inspircd-2.0.23/run/conf] ->
/home/inspircd/inspircd-2.0.23/run/conf does not exist. Create it?
[y] y

In what directory are the modules to be compiled to?
[/home/inspircd/inspircd-2.0.23/run/modules] ->
/home/inspircd/inspircd-2.0.23/run/modules does not exist. Create it?
[y] y

In what directory is the IRCd binary to be placed?
[/home/inspircd/inspircd-2.0.23/run/bin] ->
/home/inspircd/inspircd-2.0.23/run/bin does not exist. Create it?
[y] y

In what directory are variable data files to be located in?
[/home/inspircd/inspircd-2.0.23/run/data] ->
/home/inspircd/inspircd-2.0.23/run/data does not exist. Create it?
[y] y

In what directory are the logs to be stored in?
[/home/inspircd/inspircd-2.0.23/run/logs] ->
/home/inspircd/inspircd-2.0.23/run/logs does not exist. Create it?
[y] y

In what directory do you want the build to take place?
[/home/inspircd/inspircd-2.0.23/build] ->
/home/inspircd/inspircd-2.0.23/build does not exist. Create it?
[y] y

You are running a Linux 2.6+ operating system, and epoll
was detected. Would you like to enable epoll support?
This is likely to increase performance.
If you are unsure, answer yes.

Enable epoll? [y] -> y

Detected GnuTLS version: 3.4.10
Detected OpenSSL version: 1.0.2

One or more SSL libraries detected. Would you like to enable SSL support? [n] -> y
Would you like to enable SSL with m_ssl_gnutls? (recommended) [n] -> y
Would you like to enable SSL with m_ssl_openssl? (recommended) [n] -> n

Using GnuTLS SSL module.
Would you like to check for updates to third-party modules? [n] -> n

Pre-build configuration is complete!

Base install path:		/home/inspircd/inspircd-2.0.23/run
Config path:			/home/inspircd/inspircd-2.0.23/run/conf
Module path:			/home/inspircd/inspircd-2.0.23/run/modules
GCC Version Found:		5.4
Compiler program:		g++
GnuTLS Support:			y
OpenSSL Support:		n

Important note: The maximum length values are now configured in the
                configuration file, not in ./configure! See the <limits>
                tag in the configuration file for more information.

Would you like to generate SSL certificates now? [y] -> y
Symlinking src/modules/m_ssl_gnutls.cpp from extra/
SSL certificates not found, generating..


*************************************************************
* Generating the private key may take some time, once done, *
* answer the questions which follow. If you are unsure,     *
* just hit enter!                                           *
*************************************************************

What is the hostname of your server?
[irc.example.com] -> irc.example.tld

What email address can you be contacted at?
[example@example.com] -> mail@example.tld (You can leave this blank.)

What is the name of your unit?
[Server Admins] -> Department Name (You can leave this blank if you want.)

What is the name of your organization?
[Example IRC Network] -> Network Name (You can leave this blank if you want.)

What city are you located in?
[Example City] -> City Name (You can leave this blank if you want.)

What state are you located in?
[Example State] -> State Name (You can leave this blank if you want.)

What is the ISO 3166-1 code for the country you are located in?
[XZ] -> Country Code, eg: GB, US, DE

How many days do you want your certificate to be valid for?
[365] -> 365

Generating a 3072 bit RSA private key...
Generating a self signed certificate...
Signing certificate...

Certificate generation complete, copying to config directory... Done.

Detecting modules ...
Ok, 145 modules.
Locating library directory for package gnutls for module m_ssl_gnutls.cpp... -lgnutls (version 3.4.10)
Writing inspircd_config.h
Writing GNUmakefile ...
Writing BSDmakefile ...
Writing inspircd ...
Writing cache file for future ./configures ...


To build your server with these settings, please run 'make' now.
Please note: for SSL support you will need to load required
modules in your config. This configure script has added those modules to the
build process. For more info, please refer to:
http://wiki.inspircd.org/Installation_From_Tarball
*** Remember to edit your configuration files!!! ***

b. Build the package:

$ make

This will take a couple of minutes.

*************************************
*       BUILDING INSPIRCD           *
*                                   *
*   This will take a *long* time.   *
*     Why not read our wiki at      *
*     http://wiki.inspircd.org      *
*  while you wait for make to run?  *
*************************************
	BUILD:              bancache.cpp
	BUILD:              base.cpp
	BUILD:              channels.cpp
	BUILD:              cidr.cpp
...

c. Install the package:

$ make install

This command should complete in less than a second.

*************************************
*       BUILDING INSPIRCD           *
*                                   *
*   This will take a *long* time.   *
*     Why not read our wiki at      *
*     http://wiki.inspircd.org      *
*  while you wait for make to run?  *
*************************************

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

Installation is now complete. Do not try to run your IRC server yet, you must make the configuration files first.

Step #4: Configuration Files

InspIRCd comes with a set of example configuration files, which you can use to configure your IRC server.

a. Copy the example configuration to the configuration directory.

$ cp docs/conf/inspircd.conf.example run/conf/inspircd.conf

Then you must edit the file to adjust/set the configuration parameters to your desired values. Please refer to the relevant InspIRCd documentation, either for InspIRCd version 2 or InspIRCd version 3.

b. Create your cloak key. This is what will be used to mask the IPs/hostnames of cloaked users. It is essentially a password. Anybody who has the cloak key will be able to reverse the cloak hashes and find the real IP/hostname, so it should be secure and kept private. I suggest generating a long, random password.

Place your cloak key in your configuration file. Edit the value "KEY_HERE", as seen in the example below:

<cloak mode="full" key="KEY_HERE" prefix="cloaked-">

c. Now it's time to start your server for the first time and set up hashed passwords for your operators.

$ run/inspircd start

InspIRCd should start as shown below:

Inspire Internet Relay Chat Server, compiled on May 15 2017 at 00:58:46
(C) InspIRCd Development Team.

Developers:
	Brain, FrostyCoolSlug, w00t, Om, Special, peavey
	aquanight, psychon, dz, danieldg, jackmcbarn
	Attila

Others:			See /INFO Output
InspIRCd Process ID: 1432


Loading core commands.....................................................
[*] Loading module:	m_ssl_gnutls.so
[*] Loading module:	m_sslinfo.so
[*] Loading module:	m_sslmodes.so
[*] Loading module:	m_cloaking.so
[*] Loading module:	m_conn_umodes.so
[*] Loading module:	m_password_hash.so
[*] Loading module:	m_sha256.so
[*] Loading module:	m_md5.so
[*] Loading module:	m_stripcolor.so
[*] Loading module:	m_permchannels.so
[*] Loading module:	m_conn_join.so
[*] Loading module:	m_securelist.so
InspIRCd is now running as 'irc.example.tld'[245] with 1024 max open sockets

Now you should be able to connect to your IRC server using your IRC client. This guide uses Irssi, so if you're using a different client, use the commands appropriate for that client.

Open Irssi:

$ irssi

You should see the Irssi interface take up your entire terminal.

Irssi v0.8.19 - http://www.irssi.org
17:45 -!-  ___           _
17:45 -!- |_ _|_ _ _____(_)
17:45 -!-  | || '_(_-<_-< |
17:45 -!- |___|_| /__/__/_|
17:45 -!- Irssi v0.8.19 - http://www.irssi.org

...

[17:46] [] [1]
[(status)]

Join your server by entering the connection information into the command bar (at the bottom):

[(status)] /connect -ssl <ip/hostname> <port> <password> <nickname>

For my example server, the command would be:

[(status)] /connect -ssl 127.0.0.1 7000 stuff JoeBloggs

Since you do not have a password, simply enter anything in the password field.

If you have connected successfully, you should see something similar to the following:

17:57 -!- Irssi: Looking up 127.0.0.1
17:57 -!- Irssi: Connecting to 127.0.0.1 [127.0.0.1] port 7000
17:57 -!- Irssi: Connection to 127.0.0.1 established
17:57 !irc.example.tld *** Looking up your hostname...
17:57 !irc.example.tld *** Found your hostname (localhost)
17:57 !irc.example.tld Welcome to My Network Name!
17:57 -!- Welcome to the My Network Name IRC Network JoeBloggs!jamie@localhost
17:57 -!- Your host is irc.example.tld, running version InspIRCd-2.0
17:57 -!- This server was created 00:58:57 May 15 2017
17:57 -!- irc.example.tld InspIRCd-2.0
17:57 -!- There are 1 users and 0 invisible on 1 servers
17:57 -!- 1 channels formed
17:57 -!- I have 1 clients and 0 servers
17:57 -!- Current Local Users: 1  Max: 1
17:57 -!- Current Global Users: 1  Max: 1
17:57 -!- cloaked-############.IP is now your displayed host
17:57 -!- Mode change [+xS] for user JoeBloggs
17:57 !irc.example.tld *** You are connected using SSL cipher "ECDHE-RSA-AES-256-GCM-AEAD"
17:57 -!- Mode change [+i] for user JoeBloggs

Once you are connected to your server, generate a password hash for your operator accounts. Repeat this for as many operator users as you have configured in your configuration file.

When using Irssi, you must use the quote command to send raw commands to the server. This is because Irssi handles unknown commands client-side, causing many useful commands not to be sent to the server.

[(status)] /quote mkpasswd hmac-sha256 <password>

Simply replace <password> with your desired password. This should be a very strong password since it gives anybody who has it administrator rights on your IRC server.

The command should output the hmac-sha256 hash for the password that you entered:

18:06 !irc.example.tld hmac-sha256 hashed password for helloworld is ERv6oMeU$qJHBXm+6fwMOvF/AJZUjb8Bkczk9XtPIZjw7IAaki5k

Copy the outputted hash to your clipboard.

Do not copy from the example above! That is an example hash of the password "helloworld".

Quit Irssi:

[(status)] /quit

Then, paste the password hash into your InspIRCd configuration file. Just like you did with the cloak key, replace "HASH_HERE" with the hash you copied.

password="HASH_HERE"

Restart your InspIRCd server to apply the new configuration.

$ run/inspircd restart

Now you can connect to you server and authenticate as an operator. Once connected:

[(status)] /oper <username> <password>

In my example, this command would be:

[(status)] /oper JoeBloggs helloworld

You should now be an operator:

19:20 -!- Mode change [+i] for user JoeBloggs
19:20 -!- Mode change [+o] for user JoeBloggs
19:20 -!- Mode change [-x] for user JoeBloggs
19:20 -!- irc.example.tld is now your displayed host
19:20 -!- You are now an Administrator

Now you can use any operator commands that you wish!

Server configuration is complete!

Step #5: Let's Encrypt SSL

Most IRC clients are configured to allow self-signed SSL certificates, but when making direct connections to an IRC server without using an IRC client (for example an IRC bot), it is common to run into SSL errors. It is easy to use a Let's Encrypt SSL Domain Validation certificate with InspIRCd, all you have to do is obtain the certificate and copy it to your InspIRCd configuration directory. I have checked the Let's Encrypt Terms of Service and it is perfectly fine to use their certificates for web services other than a web server.

If you are not running a web server on the same machine as your IRC server, you'll need to follow different steps. This guide on Such Security is fantastic and is what you need to follow. Come back here once you've obtained the certificate.

If you are already running a web server on the same machine as your IRC server, setup will be much easier. I'm going to assume that you already have Let's Encrypt set up and working too. If not, there are plenty of guides out there.

It is useful to have a web server running on the same hostname as your IRC server. This way, if anybody tries to visit your IRC server using http, they can be redirected to an information page. For example, redirect http://irc.example.tld to http://www.example.tld/irc.

I do not suggest hosting any actual web content on http://irc.example.tld, a redirection to your main site is much safer. This is because the SSL certificate used for irc.example.tld is also going to be used for your IRC server. This involves storing it in a location that I would consider less secure than the default location. If your IRC server were to be compromised and the private key for the SSL certificate were to leak, encrypted traffic to and from irc.example.tld could be tampered with. By redirecting users away from http://irc.example.tld as soon as they visit it, you are reducing the impact of such a breach. Of course the IRC traffic would be compromised too. It would be possible for this HTTP redirection to be modified by an attacker, but it's an extra step of protection anyway.

a. Obtain a Let's Encrypt certificate using certbot for the hostname of your IRC server. Certbot will configure your web server to use the SSL certificate.

b. Change directory back to your home folder, then create and edit the file "copy-certs.sh":

$ cd
$ nano copy-certs.sh

Let's Encrypt certificates are valid for only 90 days. This script will copy the SSL certificate and private key to your InspIRCd directory once per day in order to keep them up to date.

Copy the following script into the file:

#!/bin/bash
sudo cp /etc/letsencrypt/live/irc.example.tld/fullchain.pem /home/inspircd/inspircd-2.0.23/run/conf/cert.pem
sudo cp /etc/letsencrypt/live/irc.example.tld/privkey.pem /home/inspircd/inspircd-2.0.23/run/conf/key.pem
sudo chown inspircd:inspircd /home/inspircd/inspircd-2.0.23/run/conf/cert.pem /home/inspircd/inspircd-2.0.23/run/conf/key.pem

The values that must be edited to suit your server setup are marked with bold and underline.

Mark the script as executable:

$ chmod +x copy-certs.sh

This script requires sudo/root access to run successfully. This is because it has to be able to read and write in private directories.

Add this script to the crontab of any user that has unauthenticated sudo access, or the root account. This script is a simple copy and change owner operation so it is safe to run as root.

In order to edit root's crontab, log in as a user with sudo privileges and run the following:

$ sudo crontab -e

If prompted to select a text editor, choose your preferred one. Nano is easiest.

Add following entry to your crontab. Just add a new line, paste the following and edit the bolded/underlined sections to match your server configuration.

55 4 * * * /home/inspircd/copy-certs.sh

This will run the script once per day at 4:55 am. You can change these values to a different time of day if you wish.

Then run your script once to perform the initial copying of the certificates.

$ ./copy-certs.sh

Log back in as your InspIRCd user and restart InspIRCd:

$ sudo su inspircd
$ inspircd-2.0.34/run/inspircd restart

You can test your IRC server by connecting. If your new certificates have worked, you should see the SSL information upon joining:

23:30 !irc.example.tld *** You are connected using SSL cipher "ECDHE-RSA-AES-256-GCM-AEAD"

Now you should be able to connect to your IRC server using an application that does not allow self-signed certificates.

Step #6: Final Configuration

a. In order to start your InspIRCd server at boot, you must add an entry to your crontab.

Make sure you are logged in as your InspIRCd user, then run:

$ crontab -e

Add the following line to the bottom of the file, editing the bolded/unlined values:

@reboot sleep 20 && cd /home/inspircd/inspircd-2.0.23/run && /home/inspircd/inspircd-2.0.23/run/inspircd start

This will wait 20 seconds to ensure that the system is fully booted, then start InspIRCd.

Make doubly sure that you added this to the crontab of your InspIRCd user. If you added it to another user's or even root's, InspIRCd may not work and may be a security risk.

b. Place your message of the day into the file run/conf/motd.txt and your server rules into run/conf/rules.txt.

These files will be outputted when the commands /motd and /rules are used.

The MOTD should contain important information about your server such as who the owner is, available channels, commands, etc. ASCII art text is particularly appealing in an IRC MOTD, which can be generated using an ASCII art text generator.


Please let me know if you find any issues with this guide. Thanks for reading and good luck!

I have no affiliation with InspIRCd.

This article is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.