Installing And Configuring sbnc

From SwiftIRC Wiki
Jump to: navigation, search

shroudBNC (sBNC) is amongst the most popular IRC proxy software. It's the author's view that sBNC is the easiest to configure and maintain of all other BNC software. This guide has been written for Debian Wheezy (7.0), though the process should be the same for other versions of Debian or Debian-based distributions.

Please remember that this is a basic guide. If you plan on running a BNC service, there are alterations you will want to make.


Before you “wget” the source, you need to make some preparations. Log in to where you will be running the Bouncer as root and issue the following command to install a Compiler and TCL & OpenSSL libraries

 apt-get install build-essential tcl8.5-dev libcurl4-openssl-dev

sBNC advises you not to run it on root and you will need to add another user to run the process on:

 adduser bnc

After using this bash command it will ask you for a few details. You only need to fill in the two passwords as you can press enter for details that follow it. You can now change to the new user by typing:

 su - bnc

Now that you’re on the added user you can download the tarball needed:


And extract it:

 tar -zxvf sbnc-1.3.9.tar.gz

Configuring sBNC 1.3.9

Now that the sBNC source has been downloaded and extracted, we can begin configuring it. First, change to the required directory:

 cd sbnc-1.3.9

As the default output directory is /home/USER/.sbnc (which may not be desirable), use the --prefix switch to specify the output directory of your choosing:

 ./configure --prefix=/home/bnc/bnc

This will check the build zone for the necessary files. If this stage is only small, and returns a lot of negative results you may need to go back to the beginning and find where you’ve gone wrong. Once this process has finished, it will output a list of enabled features and libraries. Check that 'SSL' and 'TCL' are enabled before continuing. If this is not the case, check that the OpenSSL and TCL libraries were installed as part of the pre-requisites section of this guide.

Now use the make commands. These may take a few minutes. Depending on where you’re running the program, you may need to use gmake instead.

 make install

Now go back to the home directory, and change to the sbnc directory.

 cd bnc/bin

You’re now ready to set options. The --config switch is used to specify the configuration directory (in this instance, we've used the same location as the install directory) :

 ./sbnc --config /home/bnc/bnc
Configuring shroudBNC

“1. Which port should the bouncer listen on (valid ports are in the range 1025 - 65535):”

Pick a port, and try not to forget it.


“2. What should the first user's name be?”

This will be your first login user, and default admin.


“3. Please enter a password for the first user:”

This is the password for our first login user.


 Writing main configuration file... DONE
 Writing first user's configuration file... DONE
 Configuration has been successfully saved. Please restart shroudBNC now.

Now, you need to restart shroudBNC by issuing:

 ./sbnc  --config /home/bnc/bnc
 shroudBNC (version: 1.3.9) - an object-oriented IRC bouncer
 Configuration directory: /home/bnc/bnc
 Log directory: /home/bnc/bnc
 Data directory: /home/bnc/bnc
 PID path: /home/bnc/bnc/
 [Wed May 28 2014 12:47:11]: Log system initialized.
 [Wed May 28 2014 12:47:11]: Created main listener.
 [Wed May 28 2014 12:47:11]: Starting main loop.
 Daemonizing... DONE

The BNC daemon is now listening on the system port specified during the configuration and should be connectible from your IRC client. This can be verified by issuing:

 ps aux | grep sbnc
 bnc       7665  0.0  0.2   6304   596 pts/0    R+   14:17   0:00 grep sbnc
 bnc      26662  0.0  2.7  55552  6768 ?        Ssl  12:47   0:00 ./sbnc --config /home/bnc/bnc

You can now connect to the BNC server in your IRC client using:


So in our example, that would be:

 /server IP:8000 Benjy:testpass

Additional configuration

This section of the guide contains information that can be used to extend the functionality of shroudBNC.

TCL Scripts

sBNC has the option to add TCL scripts, and if you’re running your BNC on SwiftIRC there are a few TCL scripts you should add. You can add scripts by uploading them to the directory in which you installed the sBNC program, which by default is /home/USER/sbnc. sBNC comes with a custom list of scripts that are not already on the Bouncer. To see these, go to the directory /home/USER/bnc/share/sbnc/scripts/, and to edit which scripts are used, you need to add the name to the sbnc.tcl file in /home/USER/bnc. To see a list of scripts you can use, go to the scripts directory.

On SwiftIRC, the rules state that users must not be able to change their vhost freely, which means you must deploy a TCL module lock.tcl.
Add TCL scripts to shroudBNC

A good repository for TCL scripts is Khobbit's website.

To add additional TCL scripts to shroudBNC, copy the direct link to the TCL file and navigate to the scripts folder within the sBNC install directory:

 cd bnc/share/sbnc/scripts 

Alternatively, you could upload the file into the aforementioned directory using a file manager.

Go back to the home directory, and using a text editor, open sbnc.tcl

 cd bnc
 pico sbnc.tcl

Add the source to the TCL file in sbnc.tcl (in this example, "source scripts/offlinereply.tcl") and save your changes.

Here is an example of how your sbnc.tcl file should look.

 # This is an example configuration file for shroudBNC's TCL module
 # It will be sourced whenever you (re-)load the tcl module or
 # use the tcl command 'rehash' (e.g. /sbnc tcl :rehash)
 # You should not modify this block
 source "scripts/alltools.tcl"
 source "scripts/namespace.tcl"
 source "scripts/timers.tcl"
 source "scripts/misc.tcl"
 source "scripts/variables.tcl"
 source "scripts/pushmode.tcl"
 source "scripts/channel.tcl"
 source "scripts/bind.tcl"
 source "scripts/usys.tcl"
 source "scripts/socket.tcl"
 source "scripts/botnet.tcl"
 source "scripts/iface2.tcl"
 source "scripts/ifacecmds.tcl"
 source "scripts/partyline.tcl"
 source "scripts/defaultsettings.tcl"
 source "scripts/auth.tcl"
 source "scripts/offlinereply.tcl"

For the changes to take effect, you must reload the TCL file. This is done by connecting to your BNC and issuing:

 /sbnc tcl :rehash

Creating executable sBNC shortcut

Having to issue ./sbnc --config /home/bnc/bnc every time you wish to start the sBNC daemon is not extremely convenient. One solution that the author recommends is to create a simple file inside the sBNC installation directory, where sBNC can be started by just entering ./sbnc.

This can be achieved by following the steps below:

 cd bnc
 pico sbnc

Inside the newly created file, enter:

 ./bin/sbnc --config /home/bnc/bnc

Save the file and make it executable:

 chmod 755 sbnc

Now the sBNC daemon can be started by simply navigating to the install directory and issuing ./sbnc. For example:

 cd bnc

Web Interface

You must first install a web-server with PHP support BEFORE continuing with this section of the guide.
Web interface for shroudBNC

A user-friendly web interface can be used to control elements of shroudBNC. This would be especially useful to novice users as it means the most frequent settings can be changed without having to query -sBNC through IRC.

Firstly, navigate to the web root for your webserver.

 cd /var/www/

Download and extract the package.

 tar zxvf sbnciface-1.3.0.tar.gz

Rename the folder to "panel" (change as appropriate)

 mv sbnciface-sbnciface-9a81ad2/ panel

Change to the "panel" directory

 cd panel

Copy the example settings file into settings.php and open it for editing

 cp settings.php.example settings.php
 pico settings.php

You will need to edit the $bncServers array to reflect the Name (cosmetic), IP and Port of the machine running the sBNC instance. For example:

 $bncServers = array(
   $sbncsrv0 = array(
       'name'  =>  'BNC 1',
       'ip'    =>  '',
       'port'  =>  '8000'

The rest of settings.php can be left to the defaults. Save the changes and then access the web interface using your web browser. In the author's example, this would be done by navigating to and then logging in with the credentials of my account (as created in the Configuring sBNC 1.3.9 section of this guide).


Q. /sbnc tcl :rehash returns Unknown command.

A. You have not installed TCL properly on the server that you’re running sBNC on. Some providers may limit the ability to use “apt-get install tcl”, therefore you may need to download the source and compile it yourself. Once it is sorted you will need to delete and redo the whole installation for it to work correctly.

Q. How do I set up bvhosts?

A. Although not needed, it is recommended that you use an IPv6 range. You can get your own at Hurricane Electric, which offers a free tunnel broker service if your VPS does not have native IPv6. There are instructions on the website on setting up the tunnel on your VPS. Next, you'll have to find the domain to use as your bvhost. is a free DNS service that has a repository of domains that you can use. After setting up an account, you'll need to find the domain you want and add an AAAA zone record that points to the IPv6 address that you want to use.

Q. Where can I see what the rules are regarding BNCs are on SwiftIRC?

A. See the SwiftIRC BNC provider rules here.

Q. My users are quitting with message Ping Timeout, why is this?

A. Either your server or the SwiftIRC server's network connectivity is experiencing issues. Try a different SwiftIRC server and/or ping an external IP to check your network connectivity.

Q. I get connection refused when trying to connect to a server on my BNC, why is that?

A. This means that the IRC server you have set is not accepting connections. You will get this error if you attempt to connect to a IPv4-only server when trying to connect using IPv6. To see a list of IPv6 enabled SwiftIRC servers, click here.

Q. My BNC disconnects almost immediately after attempting to connect to an IRC server with no error, why?

A. This is likely because you have set SSL on, but have not set the BNC to connect to the IRC server's SSL port. Do /sbnc set server

Q. My bvhosts don’t work and am receiving a "DNS request (vhost) for user <user> failed" error, why is this?

A. If the bvhost has had time to be added both sides, reverse and forward then you’ll need to check that both of the records are the same and correct. If they are both correct and they have both had time to sort themselves out then you should check that the IPv6 is added to your VPS. If all else fails try a different IPv6 address. If the IP address does not resolve, it may have been cached on the server you are connected to.

Q. My IPv6 address has been banned from SwiftIRC, why?

A. This is probably because the bvhost you’ve chosen is against the SwiftIRC rules. You should re-read the rules. You will still be able to connect on a different IP address, provided you don't have your whole IPv6 range banned.

Q. How do I get rid of the ~ in my BNC user's ident's?

A. You need to set up Oidentd. A guide on how to do this can be found here. Note that oidentd is not always installed on your VPS, so you may need to install it yourself.

 This page was created by SwiftIRC user Alexandra and expanded by Benjy.