bitlbee over SSL using stunnel

What is this?

I prefer IRC as communication protocol for multi-user chat and instant messaging. To keep in contact with users of other protocols/clients I use BitlBee which is a gateway connecting other chat networks like Jabber/XMPP and ICQ to your own IRC server.

IRC is a well-established open protocol, but unfortunately it lacks encryption or other measures to secure the transmission of information. I don’t want to run an open BitlBee server, but password protection in plaintext is quite useless if you are in an untrusted network. Authentication should be done with a challenge-response method to avoid leaking passwords, but IRC as a very old protocol does not offer anything like this. And again communication itself would still be unencrypted.

Many people use their terminal-based IRC client irssi over SSH. This way the client runs on the same machine as bitlbee, so a very simple solution would be to bind the server socket to localhost only in this case. For me this is not an option as I am using a GUI-based IRC client xchat locally.

Fortunately it’s possible to secure any TCP connection using SSL!

Unfortunately BitlBee itself does not have builtin SSL support for the server. But a general solution for this problem exists: stunnel. This program acts as a general wrapper around any stream socket based program and is often in use for inetd based services.

Setup instructions

The following instructions are for setting up bitlbee over xinetd with stunnel to secure the connections. Be aware that this inetd approach will spawn a new process for each incoming connection. This setup is not meant to serve many users at once, but works fine for personal use.

First we have to generate and self-sign a new certificate to be used with SSL:

# openssl req -new -newkey rsa:1024 -days 365 -nodes -x509 -keyout /etc/stunnel/bitlbee.pem -out /etc/stunnel/bitlbee.pem

Usually you need to be root to write to /etc/stunnel. Of course you can also use a pre-existing certificate signed by a well-known CA or request a new one.

Only stunnel for BitlBee needs to read the certificate file, so we will need a new user bitlbee for this purpose. On my Debian system the package management already added such a user, so your mileage may vary.

# adduser --system --group --disabled-login --disabled-password --home /var/lib/bitlbee/ bitlbee
# chmod 700 /var/lib/bitlbee/
# chown bitlbee:bitlbee /etc/stunnel/bitlbee.pem

Then we need to set up xinetd to secure the connection using stunnel. I modified the basic configuration file provided with the BitlBee source for this; changes are marked in bold text below. The following file should be saved as /etc/xinetd.d/bitlbee:

## xinetd file for BitlBee. Please check this file before using it, the
## user, port and/or binary location might be wrong.

## This file assumes you have ircd somewhere in your /etc/services, if things
## don't work, check that file first.
service ircd
        socket_type     = stream
        protocol        = tcp
        wait            = no

        ## You most likely want to change these two
        user            = bitlbee
        server          = /usr/bin/stunnel
        server_args     = -p /etc/stunnel/bitlbee.pem -l /usr/local/sbin/bitlbee

        ## You might want to limit access to localhost only:
        # bind            =

        ## Thanks a lot to for telling us about the type
        ## argument, so now this file can be used without having to edit
        ## /etc/services too.
        type            = UNLISTED
        port            = 6667

After the file is in place, xinetd configuration files need to be read again:

# /etc/init.d/xinetd reload

Now you should be able to connect to bitlbee using your favorite IRC client! Make sure you enable SSL for this connection. If you are using a self-signed certificate you will have to verify it, of course.

For bitlbee usage, you should refer to the official documentation. And maybe I will also write down some basic setup instructions for a closed server in the near future…

2 thoughts on “bitlbee over SSL using stunnel

  1. PierLuigi

    I would love a basic setup instruction for a closed server. I’ve been hunting and this is the most concise instructional on bitlebee SSL use I’ve found. Cheers for this.

  2. Tommy


    I’m running a gentoo on my server and want to set up bitlbee and stunnel. Of course, i experimented on my pc first, to avoid fucking up my server.
    So I found out that your tutorial is a little bit outdated 😉

    I add the relevant lines of my configs to this comment, so you can update your tutorial:


    accept = 6667
    connect = localhost:6668
    cert = /etc/stunnel/bitlbee.pem


    socket_type = stream
    protocol = tcp
    wait = no
    user = bitlbee
    server = /usr/bin/stunnel
    type = UNLISTED
    port = 6667


    RunMode = Inetd
    User = bitlbee
    DaemonInterface = localhost
    DaemonPort = 6668

    As you can see, stunnel is listening at the irc port and forwarding to 6668 where bitlbee is listening:
    # netstat -taupen | grep 666
    tcp 0 0* LISTEN 0 221564 20390/stunnel
    tcp 0 0* LISTEN 106 233065 21515/bitlbee
    tcp 0 0 ESTABLISHED 106 235720 21535/bitlbee
    tcp 0 0 ESTABLISHED 107 234017 20390/stunnel
    tcp 0 0 ESTABLISHED 107 234904 20390/stunnel
    tcp 0 0 ESTABLISHED 1000 235718 21455/xchat

    I’m capturing with wireshark and it works fantastic.


Leave a Reply

Your email address will not be published. Required fields are marked *


This site uses Akismet to reduce spam. Learn how your comment data is processed.