Ngircd Install Guide

In this guide, we'll setup ngircd, a free, portable, lightweight IRC server.

Overview

ngircd is an IRC server. It helps IRC clients send messages to one another.

Advantages:

The source code is written in modern, portable C.
The code compiles easily on all BSDs, Linux, and other platforms.
The code is easy to fork to add new features such as spam filters
The server has a very simple, easy-to-understand configuration
Documentation is short and easy to understand
The server is a clean implementation which was written from scratch
The lead developer po||ux actively hangs out on the IRC server ngircd.barton.de on #ngircd

Docs and references

Documentation for how to administer ngircd can be found on ngIRCd's website. After installation, these documentation files can be found in /usr/local/share/doc/ngircd/. You are also expected to read the ngircd(8) and ngircd.conf(5) man pages.

Installation

This guide assumes you are using OpenBSD 7.6.

Installing from OpenBSD packages

WARNING: Due to a security vulnerability, we no longer recommend using the default ngircd in packages. We must compile from source to disable the CHARCONV module.

$ doas pkg_add ngircd-27-ident

Note that we install the ident flavor of OpenBSD to enable IDENT support.

Next, copy the sample configuration file:

$ doas cp /usr/local/share/examples/ngircd/sample-ngircd.conf /etc/ngircd/ngircd.conf

You can now begin editing the file /etc/ngircd/ngircd.conf to configure the server. Consult documentation for ngircd.conf(5).

Building from source

Compiling from source is more work, but will allow us to disable a security vulnerability (CHARCONV) in the default package. It also allows us to fix issues with limited buffer sizes. Although the default package will work, those two issues should be fixed. Nevertheless, it's helpful to use packages at first so that ngircd's rc.d scripts are created automatically.

Note: Before building from source, make sure you have ngircd package installed using the instructions from above.

Download the IRC server, extract the code, and build it:

$ ftp https://ircnow.org/software/ircnowd.tgz
$ tar xvzf ircnowd.tgz
$ cd ircnowd/
$ sh build.sh

Currently, ircnowd only includes a few minor patches.

Testing ngircd version

Make sure your ngircd is compiled properly. You can test with:

$ ngircd --version
ngIRCd 27-IDENT+IPv6+IRCPLUS+SSL+SYSLOG+ZLIB-x86_64/unknown/openbsd7.6
Copyright (c)2001-2024 Alexander Barton (<alex@barton.de>) and Contributors.
Homepage: <http://ngircd.barton.de/>

This is free software; see the source for copying conditions. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

ngircd should be version 27, IDENT should be enabled, OpenBSD should be version 7.6, and CHARCONV should not be present.

Configuring ngircd

Edit /etc/ngircd/ngircd.conf as root:

Note: Lines that begin with # or ; are comments and will be ignored. You will need to remove # or ; to uncomment.

Typically, ";" precedes a line of code that has been commented, while a "#" precedes an actual note that should not be uncommented.

Global Block

[Global]
        Name = irc.example.com
        AdminInfo1 = Example Network
        AdminInfo2 = Planet Earth
        AdminEMail = admin@example.com
	HelpFile = /usr/local/share/doc/ngircd/Commands.txt
        Info = irc.example.com
        Listen = 127.0.0.1,::1,192.168.1.1,2001:db8::

Provide every IP address you want ngircd to listen on. This includes localhost (127.0.0.1 and ::1) and your public IPv4 and IPv6 addresses. Localhost is always 127.0.0.1 and ::1 on every server, but each server has a different public IP address, so replace 192.168.1.1 and 2001:db8:: with your real public IPs. When hosting a public service, avoid listing IPs that are not DDoS-filtered. IRC servers are heavily DDoSed and using an unfiltered IP may get your server taken offline.

Note: if you do not uncomment this line, ngircd will listen to all IPs by default. This is probably a mistake since it will end up listening to hundreds of IPv6 addresses.

        MotdFile = /etc/ngircd/ngircd.motd
        ;MotdPhrase = "Hello world!"
        Network = ExampleNet
        ;Password = abc

Note: The server name should be a domain name with periods, but the network name usually contains no periods.

Keep the MotdPhrase and Password commented out. Use a MotdFile instead. Comment out the password; if left enabled, users will be unable to connect without the password. We want to offer public IRC chat, not a private server.

	PidFile = /var/run/ngircd/ngircd.pid

The Pid file is where ngircd writes its process ID. This should be uncommented so the PID can be easily found.

        Ports = 6660, 6661, 6662, 6663, 6664, 6665, 6666, 6667, 6668, 6669, 7000, 16667
        ServerGID = _ngircd
        ServerUID = _ngircd

It's recommended to provide ports besides the standard 6667 to allow users to bypass network firewalls.

NOTE: Make sure ServerUID and ServerGID are set to _ngircd. Otherwise, by default, ngircd will run as the user nobody.

Limits Block

[Limits]
        MaxConnectionsIP = 0
        MaxJoins = 300
        MaxNickLength = 16
        MaxPenaltyTime = -1
        MaxListSize = 300
        PingTimeout = 120
        PongTimeout = 300

We allow unlimited connections per IP. Abuse from spambots are better handled with firewalls and open proxy monitors like hopm.

MaxNickLength: must be identical for all servers on the network. On IRCNow, MaxNickLength is 16.

Options Block

[Options]
        AllowRemoteOper = yes
        ChrootDir = /var/ngircd
	;CloakHost = %x
	CloakHostModeX = %x
	CloakHostSalt = abcdefghijklmnopqrstuvwxyz
        ConnectIPv6 = yes
        ConnectIPv4 = yes
	DefaultUserModes = ix
	DNS = yes
	Ident = yes

We will turn on AllowRemoteOpers so that GLINEs function properly.

We want to chroot to /var/ngircd to prevent a security compromise.

We will cloak the host using a unique salt; contact another sysadmin for the salt used on IRCNow. If not linked to another network, you can leave it commented to use a random salt each time it runs, or you can generate your own random salt.

We use CloakHostModeX so that users are cloaked when mode +x is set. Users can then turn off mode x in order to remove the cloak (to show a custom hostmask). If we had used CloakHost instead, uncloaking a user would not be possible.

User mode +i keeps the user invisible so that /whois does not show all channels a user has joined. This helps reduce stalking and harassment.

We want to perform DNS lookups when a client connects so that we can validate a user's hostmask. We also want to perform IDENT lookups.

	NoticeBeforeRegistration = yes
	OperCanUseMode = yes
	OperChanPAutoOp = no 
	PAM = no
	RequireAuthPing = yes
	SyslogFacility = daemon

Receiving a notice before registration can help when debugging with netcat. Notices are also necessary for proper functioning of hopm.

OperCanUseMode will allow opers the ability to use mode commands when needed. Opers should use this power sparingly: use only if the channel owner is unable to moderate his channel.

OperChanPAutoOp should be set to no so that opers are not automatically op'd in every channel they join. Opers should avoid interfering with normal channel operation.

Set PAM to no because enabling PAM on OpenBSD causes issues.

We set RequireAuthPing to yes because it may help reduce spam.

Allow syslog (see below) to log events.

SSL block

;[SSL]

For now, comment out this entire block. When you are ready to set up SSL/TLS encryption, you will un-comment the entire block. Disabling SSL helps simplify the setup of your first ngircd instance.

WARNING: Do not send passwords or sensitive data over this server until SSL is set up.

Operator Block

Create one Operator block for each operator on the server:

[Operator]
        Name = username
        Password = password
	;Mask = *!ident@somewhere.example.com

Please use a long, random string for your password.

If you uncomment Mask, your hostmask must match the operator hostmask in order for the /OPER command to work. If the hostmask differs by even a single character, then your /OPER command will be rejected. It's best to leave Mask commented out until you are familiar with ngircd.

Once your configuration is tested and stable, you can uncomment Mask and have it match your vhost. However, please be aware that this will make it impossible to become IRC Operator if you connect from a different IP address.

Server Block

;[Server]

The server block is used to connect to other servers to form a network. You can have multiple server blocks. For now, leave it commented out until you are ready to link ngircd.

MOTD file

The Message Of The Day (MOTD) goes in /etc/ngircd/ngircd.motd. You are welcome to customize the MOTD for your server.

+------------------------------------------------------------------------+
|  _   ____   ___          ______,-.--.-._____     _   _                 |
| | | | |\ \ | |\|         |     |  __  |     |   | | | |   _   _  _  _  |
| | | | |/ / | |          /      |_/  \_|      \  | |\| | /| |\| || || | |
| |_| |_|\_\ |_|/|       /   ..#//;;;;;;;;;..   \ |_| |_| \|_|/ \_\_/_/  |
|_______________________/  .##//;;;;;;;;;;;;;;.  \_______________________|
|                        ./#//::::::::::::::::::                         |
| https://ircnow.org    ./#/:;;;;;;;;;;;;;;;;;;;;.                       |
|                       /#//::::::::::::::::::::::     IRC Server        |
| The Users' Network    //:/::::::::::::::::::::::     IRC Bouncers      |
|                       //:/::::::::::::::::::::::     IRC Bots          |
| Of the users,         //:/:::::: :::::::::::::::     E-mail            |
| By the users,        .//:/::::::-:::::::::::::::.    VPN               |
| For the users        ///:/:::::: ::::::::::::::::    Code hosting      |
|                      ///:/:::::: ::::::::::::::::    File storage      |
|                     .///:/:::::: ::::::::::::::::.   Shell accounts    |
|                     ////:/:/:::: :::::::::::::::::                     |
| designed by        .////:/:/:/::. ::::::::::::::::.                    |
|    bitreich        /#///:/:/:/:/::: :::::::::::::::                    |
|                 .###//////////////// ';/;/;;;;;;;;;;;.                 |
|                /###//////////////////-'/:/:/:::::::::::                |
|               ////////////:/:/:/;;;;;; ;;;;;;;;;;;;;;;;;               |
|               ""     ""        [_    .:        ""     ""               |
|                                  |_.:                                  |
|                                                                        |
|            irc.ircnow.org 6667 for plaintext, 6697 for TLS             |
|              6660-6670, 16667 for plaintext, 16697 for TLS             |
|                                                                        |
|            * No porn / illegal drugs / threats of violence *           |
|            * No slander / libel / gambling *                           |
|            * No spam, illegal cracking, or DDoS *                      |
|            * No copyright infrigement                                  |
|            * Max 3 connections per IP address.                         |
|                                                                        |
|   Terms of service: https://wiki.ircnow.org/index.php?n=Terms.Terms    |
|                                                                        |
|   Opers are available on #help.                                        |
+------------------------------------------------------------------------+

Configuring syslog

All log messages from ngircd should go to /var/log/ngircd.log. Insert these three lines starting at line 3 (at the top) in /etc/syslog.conf:

!!ngircd
*.*                                                     /var/log/ngircd.log
!*

This directs all logs from ngircd to go straight to /var/log/ngircd.log.

Syslogd expects all logfiles to already exist with the correct permissions. So, we will create the file /var/log/ngircd.log and restart syslogd:

$ doas touch /var/log/ngircd.log
$ doas rcctl restart syslogd

Chroot

We need to set up the chroot for ngircd. Copy the files into the chroot:

$ doas mkdir /var/ngircd/etc/
$ doas cp /etc/resolv.conf /var/ngircd/etc/
$ doas cp -R /etc/ngircd /var/ngircd/etc/
$ doas chown -R _ngircd:_ngircd /var/ngircd/
$ doas rm -r /etc/ngircd
$ doas ln -s /var/ngircd/etc/ngircd /etc/ngircd
$ doas mkdir -p /var/ngircd/usr/local/share/doc/
$ doas cp -R /usr/local/share/doc/ngircd/ /var/ngircd/usr/local/share/doc/
$ doas chown -R _ngircd:_ngircd /var/ngircd/usr/local/share/doc/ngircd/
$ doas mkdir -p /var/ngircd/var/run/ngircd/
$ doas chown -R _ngircd:_ngircd /var/ngircd/var/

This creates a symlink so that only one set of configuration files needs to be maintained inside and outside of the chroot. Otherwise, two sets of configuration files would need to be maintained, one inside and the other outside of the chroot.

Automation

To automatically restart ngIRCd if it was terminated unexpectedly, create a script in /usr/local/libexec/ngircd/restart.sh:

$ doas mkdir -p /usr/local/libexec/ngircd/
$ doas touch /usr/local/libexec/ngircd/restart.sh
$ doas chmod +x /usr/local/libexec/ngircd/restart.sh

Edit /usr/local/libexec/ngircd/restart.sh:

#!/bin/sh

SERVICE_NAME="ngircd"
SERVICE_USER="_ngircd"
SERVICE_PID="/var/ngircd/var/run/ngircd/ngircd.pid"

if ! pgrep -u $SERVICE_USER -x "$SERVICE_NAME" > /dev/null
then
  if [ -f $SERVICE_PID ]; then
    rm -f $SERVICE_PID
    rcctl -d start $SERVICE_NAME
  fi
fi

Add this as a cronjob:

$ doas crontab -e

*/5       *       *       *       *       /usr/local/libexec/ngircd/restart.sh > /dev/null 2>&1

For the script to work, the PidFile must be specified in ngircd.conf(5).

Starting ngircd

To start ngircd via rcctl:

$ doas rcctl enable ngircd
$ doas rcctl start ngircd

To test ngircd, use your IRC client to connect to the server. Join a few channels and chat inside. You will need to invite your friends, since your new IRC server will have no other users on it.

Troubleshooting

If you run into any errors, you can test to see if your configuration file has errors:

$ doas ngircd -t

To run ngircd in debug mode:

$ doas ngircd -n

Check /var/log/ngircd.log to see if ngircd is listening on the correct IP addresses and ports. Connect to those ports using your IRC client to verify that the server is working as intended.

Remember, if you are connecting using port 6667 without SSL, any eavesdropper can read all your text, including your passwords. Don't send any sensitive information until you have upgraded to SSL.

Reloading and Restarting ngIRCd

After you edit ngircd.conf(5) for a running ngircd server, you will need to reload the configuration file:

$ doas rcctl reload ngircd

Alternatively, you can run:

$ doas pkill -HUP ngircd

Reloading a configuration file will not disconnect any active connections. On the other hand, restarting a service causes netsplits and is very disruptive. So, always reload instead of restarting wherever possible.

To restart the ircd:

$ doas rcctl restart ngircd

WARNING: Restarting the ircd will disconnect all existing connections and cause netsplits. So, try to restart ngircd only when absolutely necessary.

WARNING: ngircd appears to have a bug where the ircd will crash if you reload the configuration file while a message is being sent. Be careful to avoid reloading configuration files when many users are chatting.