IRC with UnrealIRCd

Written for Debian (based on Bullseye)

Commands shown following # need to be run either as root or using sudo.

Commands shown following $ need to be run as your regular user.

Any time text is shown inside < > , it denotes text that must be replaced with your own. For example, <password> would simply be replaced by your password. No not include < > .

Fairly comprehensive Official UnrealIRCd Documentation is available on UnrealIRCd's site.

This tutorial will walk you through:

You will need:

  • an online server, preferably with a static IP
  • a domain name
  • a wildcard SSL certificate that matches your domain name OR an SSL certificate that matches the full domain including the subdomain you will use
  • a wildcard DNS record for the domain OR a specific DNS record for the subdomain you will use
  • a terminal text editor (Nano or Vim, for example)

A terminal multiplexer such as Screen, Tmux, or Byobu will be handy, although it's not necessary. If you have one, open it before you start this process. I usually have at least one multiplexer session logged in as root, and at least one for each user account or active procedure under a user account.

---------------------------------------------------

System Preparation

First, there are some packages that are required to be installed before you can install UnrealIRCd and Anope from source code. Run the following command to be sure you have all the required packages and libraries.
# apt install build-essential pkg-config libssl-dev libpcre2-dev libargon2-0-dev libsodium-dev libc-ares-dev libcurl4-openssl-dev cmake wget

Anope stores all its settings in a database. By default, it uses what's called a "flatfile database", which is simply a file, usually called "anope.db". Usually this works just fine, although I have had settings suddenly disappear for no apparent reason and had to recover from a backup file.
If you already have a MySQL or MariaDB database server set up, and prefer to use it versus a flatfile database, or you simply anticipate having a large amount of users and channels, you can set up Anope to use the MySQL or MariaDB database. Anope should work with MySQL without any additional packages, although I use MariaDB, which needs one additional package.

Of course, you do need mariadb-server and associated packages installed.

The one package that needs to be installed for Anope to work with MariaDB is libmariadb-dev-compat. Install it with
# apt install libmariadb-dev-compat

Neither UnrealIRCd or Anope should be installed by or run as the root user. You can install and run both under your own user if you like. What I have done so far is to create a complete new user account, under which I install and from which I run both UnrealIRCd and Anope.

To create a new user, run
# adduser <myircserver>
where <myircserver> is the name of the new user account. Set a password when asked, and go through the rest of the prompts. You can simply press the Enter key at each prompt to leave the fields blank.

Switch to the new user with
$ su - <myircserver>
and entering the password you just set for that account.

---------------------------------------------------

Install UnrealIRCd

Steps taken from UnrealIRCd.org.

  1. Download the source code.
    $ wget --trust-server-names https://www.unrealircd.org/downloads/unrealircd-latest.tar.gz
    This will download the source code package for the latest stable version.
  2. Extract the source code from the .tar.gz package. Watch the version number in the file you downloaded and replace the one below with the one you have (if necessary).
    $ tar xzvf unrealircd-6.0.5.tar.gz
    This will create a new folder (usually called, for example, unrealircd-6.0.5) and extract all the files into it.
  3. Enter that folder.
    $ cd unrealircd-6.0.5
  4. Run the Config script, which will ask a series of questions.
    $ ./Config
    Unless you know you want to change from default settings, pressing Enter at each question works fine.
  5. Next you'll compile the source code.
    $ make
    This may take a couple or a few minutes, depending on your hardware.
  6. Finally, install.
    $ make install
    UnrealIRCd will be installed to the folder you chose while running the ./Config script. Now you need to set a bunch of settings so that it will start and run!

---------------------------------------------------

Configure UnrealIRCd Before Starting

Again, steps are taken from UnrealIRCd.org. On that page we're now in the "Creating a configuration file" section. I'm going to try to add a few notes on sections and lines I edited to make things work.

  1. So now you need to move into the folder that UnrealIRCd was installed into. If you didn't change any settings, and are still in the same user session as above, the command will be
    $ cd ~/unrealircd
    You should now be in /home/myircserver/unrealircd.
  2. Copy the example config file and rename it at the same time.
    $ cp conf/examples/example.conf conf/unrealircd.conf
    You'll now be able to edit the main config for UnrealIRCd.
  3. Open the above config file in your text editor. I use Vim.
    $ vim conf/unrealircd.conf
  4. Read the short article on Configuration file syntax. There are a few helpful tips in there. Linked at the bottom of that page is another page that describes each configuration block.
  5. Now we'll go through unrealircd.conf and I'll point out the parts you need to edit. This will take some time.
    1. There are a number of notes from line 1 to line 25. Read them for reference. The actual config starts at line 27 with info on the setting on line 39.
    2. The description for the first setting block you need to worry about starts at (about) line 60: /* This is the me { } block...
      You need to edit the name and info lines appropriately. the sid line you only have to worry about if you're joining a network, and in that case you will most likely be assigned an sid number.
      For example, the "me" block for my main IRC server is: 
      
	  me {
	      name "irc.bbclancloud.com";
	      info "Bracham's Public IRC";
	      sid "001";
	  }
    3. The Admin block description starts at (about) line 66, and the settings at (about) line 69.
      The three lines should respectively be the (full) name you publish for yourself online, your nick on the server, and an email address you can be contacted at. Make sure to keep the quotes around the text, and leave the semi-colon at the end of each line.
    4. Now you may want to skip down to the "Allow" blocks, the description of which starts at (about) line 116. There are some different blocks here.
      The first one is just a general block to allow up to three clients per IP, which can help prevent spamming.
      The next example block allows users on a set IP to connect with a password, and allows more users for that IP.
      For my main IRC server, I've adjusted that last block to allow up to ten clients to connect from a specific IP, and removed the password line.
    5. Next, the oper block description starts at (about) line 141, and the settings lines start below that at (about) line 156.
      In the line oper bobsmith, bobsmith must be replaced with a real nick on the server, which may be yours.
      Two lines down, replace "test" with the password that you want to use to log in as oper.
      "vhost", the last line in that block, should be edited to match your domain.
    6. At about line 170, the description for the listen blocks starts. Following that are two blocks which are the main blocks we're worried about right now.
      If this is your first IRC server on this server, then you will want to leave the first two listen blocks alone. These are the Standard IRC port 6667 and the Standard IRC SSL/TLS port 6697. If you do want to change these port designations, this is where you do it. For example, I now have three IRC servers set up on the same system, and each of those three must use a different pair of ports. You will also have to adjust firewall settings to allow traffic to the selected ports, whether you leave the default ports or change them. If you're running a bouncer or Weechat service on the same system, you may leave the non-SSL port 6667 set to listen, but not open it at the firewall, which would mean that any external connections are only over SSL.
      The third "listen" block is the Special SSL/TLS servers-only port for linking. If you are not linking to other servers, this is not required. Simply insert # in front of each line in that block to "void" it. If you are linking to other servers, you will have to go directly to UnrealIRCd's documentation for help.
    7. Immediately after that is the block for setting up server linking. If this is a standalone server, comment out this whole block as well by inserting a # in front of each line in the block to "void" it. Again, if you are linking with other servers, please use UnrealIRCd's documentation.
    8. Line 238 (as long as you haven't added or removed any lines) starts describing the link block for services. You'll see this area later on in this tutorial. Just comment out this whole block (as described previously), Anope will give you a block with a few more settings later on.