Running Tor Onion service with UnrealIRCd

This guide will show you how to setup UnrealIRCd and Tor, where your IRC server will get an .onion address so it can be used as a hidden service / Onion Service. This guide will put the Tor users on their own IP address (127.0.0.2) and disable some ban checks. Then we setup Tor as a hidden service, with correct settings for UnrealIRCd. Finally, it shows you how to limit Tor access only to users with a services account (optional).

Background

By default if you run an onion service, Tor will connect to the IRCd at 127.0.0.1 using IP 127.0.0.1. This is bad for two reasons:

1. You would be unable to separate Tor traffic from other localhost traffic
2. All tor users would be unbanable because 127.0.0.1 is exempt from all bans, including glines

So instead of connecting Tor over IP networking (like 127.0.0.1) we will connect Tor to UnrealIRCd over a UNIX socket (a file). Proceed with the rest of the guide below.

Install Tor

This is explained in https://support.torproject.org/apt/tor-deb-repo/ but in short, if you run Ubuntu/Debian, then:

1. Add the repository, see https://support.torproject.org/apt/tor-deb-repo/
2. Then apt install tor deb.torproject.org-keyring

Configure Tor

Open /etc/tor/torrc and add at the bottom of the file:

HiddenServiceDir /var/lib/tor/ircd
HiddenServicePort 6697 unix:/etc/tor/unrealircd/tor_ircd.socket

(we will create that /etc/tor/unrealircd in a later step, don't worry about it for now, it does not need to exist yet)

Restart Tor:

systemctl restart tor.service

Preparing the system

This needs to be done after installing Tor and before you reconfigure UnrealIRCd for tor use. So now is the right time.

First, become root, as all next commands need to be executed as root:

Creating the socket directory

Let's create the directory that both UnrealIRCd and Tor will access so they can share the socket file:

mkdir /etc/tor/unrealircd
chown unrealircd:debian-tor /etc/tor/unrealircd
chmod 750 /etc/tor/unrealircd

NOTE: This assumes your IRCd user is called unrealircd and that Tor runs as debian-tor (the default on Ubuntu/Debian). If not, change the unrealircd:debian-tor in the chown command of above.

Tweaking AppArmor

If you are on Debian/Ubuntu and have AppArmor installed (you probably do!) then run the next few commands. If you don't do this then everything will fail mysteriously later.

Still as root, run:

echo "/etc/tor/unrealircd/tor_ircd.socket rw," >>/etc/apparmor.d/local/system_tor
apparmor_parser -r /etc/apparmor.d/system_tor

Configure UnrealIRCd

Add this to your unrealircd.conf file:

listen {
        file "/etc/tor/unrealircd/tor_ircd.socket";
        mode 0777;
        spoof-ip 127.0.0.2;
        options { tls; }
}

/* Some ban checking should be turned off, otherwise all Tor
 * users could be banned by one user misbehaving.
 *
 * This also sets maxperip to unlimited. The alternative is to remove
 * 'maxperip' here and either change the generic allow block to allow
 * more users, or add a specific allow block specially for 127.0.0.2
 * with its own limit in allow::maxperip, so you can set a hard
 * limit on Tor users (eg: 100) instead of 'unlimited'.
 */
except ban {
        mask { ip 127.0.0.2; }
        type { blacklist; connect-flood; maxperip; handshake-data-flood; }
}

And then REHASH.

This will make any client that connects to /etc/tor/unrealircd/tor_ircd.socket come up with an IP of 127.0.0.2 and exempt them from some ban checking.

Get your onion address

Grab your .onion address:

cat /var/lib/tor/ircd/hostname

Decide on your server name

Is this server going to accept connections from both the Internet and from Tor? Then it is not really a "hidden" service, and you may want to go for Option 2: keep your normal server name.

Is the server going to ONLY accept connections from Tor and not from the regular Internet? Then see Option 1: set your server name as .onion

Option 1: set your server name as .onion

Do you really want to run as a hidden service? Like, you want to hide the name of your server, not reveal its location, and it should only reachable over Tor? Then this is the me::name that you want to use in UnrealIRCd.

Update the Me block in your unrealircd.conf, like:

me {
        name xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.onion;
--etc--

When you change the Me block you will have to restart the server. A rehash is not enough!

Option 2: keep your normal server name with a MapAddress

If your server is reachable from both the Internet and Tor, and thus you don't need to run a hidden service, then you could keep your me::name as normal (eg: irc1.example.net) and tell your users to edit their torrc file and add something like:

# torrc entry for irc1.example.net
MapAddress irc1.example.net xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.onion

And then tell your users to connect to irc1.example.net. This is what Libera does for instance. A benefit of this is that you can use regular internet-issued valid TLS certificates.

If you don't like this approach, then you can also go with Option 1 mentioned further up.

Let users connect via Tor

People should now be able to connect to your Onion server. Depending on the choice you made at Decide on your server name, users now connect to:

• Your .onion address directly (if you went for option 1), or
• To like irc1.example.net (if you went for option 2), which behind the scenes will connect to the onion address as well

TLS Certificate

It's good practice to have a valid TLS certificate.

If you went for option 1 (users connect directly to your .onion), then this is not possible for free yet. Here are some pointers:

• Get a TLS certificate for your onion site - The Tor Project
• A specific guide someone wrote when using the HARICA CA
• At some later stage Let's Encrypt may offer it, but they have not published a timeline

If you went for option 2 (with MapAddress) then you can use internet-issued certificates (for eg irc1.example.net). You can follow the Using Let's Encrypt with UnrealIRCd guide to get a free certificate if you haven't done so already.

Optional: require authentication

Since people are anonymous on Tor, there may be more abuse than usual. You may optionally require all Tor users to have a services account and use SASL.

To do so, add this to your unrealircd.conf:

require authentication {
	mask *@127.0.0.2;
	reason "Tor users need to authenticate to their services account using SASL";
};