Trick: Headless Routing Server

From BitWise DocuWiki

Table of contents

What this will do for you

Allow you to run the BitWise Routing Server where it's meant to be -- on a headless linux server. Right now, though, it's just a hackish thing using XVFB. I hope at some point in the future, there may be a better way other than loading the full compliment of X and GTK libraries on your computer.

Notes: This is not intended to replace the BRS howto linked from the download page. It only covers changes which need to be made because it is running on a headless server.

Since this was tested on ClarkConnect, the instructions are geared toward that distribution. Change the steps accordingly.


Get BitWise Routing Server [BRS] running on some monitor-less linux box by:

  1. Loading the needed packages for your distro
  2. Copying over the BRS config file
  3. Test it out
  4. Configure your router for port forwarding
  5. Load it on boot

Step-By-Step Instructions

Loading the needed packages for your distro

You will need to get gtk, X and xvfb installed. On my computer, the command was:

apt-get install gtk+ xorg-x11 xorg-x11-Xvfb

You will also need the BRS itself (duh). Go get that, and dump it to some directory (I just untarred to /root)

Copying over the BRS config file

Since you will not have a monitor to configure the BRS, you will need to copy over the file from some other computer. The file is, in linux, "~/.BitWiseRoutingServer". As an example, my file is as follows:


I use port 4137 rather then the default 4200, since it simplifies setup for port forwarding if you will not use the BW client on this computer. You will probably need to adjust the LocalIP line, as well.

Test it out

Start Xvfb:

Xvfb :0 -screen 0 640x480x16 -nolisten tcp

The screen argument is so that it starts up with a 16-bit depth -- the BRS appears to segfault with an 8-bit depth.

Now, at another console/shell window... cd into your BitWiseRoutingServer folder. set the DISPLAY variable:

export DISPLAY=:0.0

and,at the same window, start the BRS:


If all goes well, you should now have the BRS running on your headless computer!

Configure your router for port forwarding

The ways to do this can differ a lot. You may want to consult the Router Setup guides. If you used port 4137, you will want to redirect internally to port 4137, rather then 4200.

Get it to load on boot

At this point, it's all going to die if you close those shell windows. You will need to get it to run in the background and load on boot to truly make this useable.

The way I did this was to create a small script which loads Xvfb and the BRS. After doing that, I linked to this script in /etc/rc.local.

The script I used:

Xvfb :0 -screen 0 640x480x16 -nolisten tcp 2>/dev/null 1>/dev/null&
sleep 5
export DISPLAY=:0.0

I saved this as startbrs, and put it in /root/BitWiseRoutingServer. I am sure there is a better way to wait for Xvfb to load then to wait 5 seconds, but it seems to work for me. Also note that it does not check for already an already running BRS, that would probably be a wise thing to do in your script, as well.

I added the following line to /etc/rc.local so it would start on boot:


Note: Xvfb may not need the complete X server installed to function properly. If you do try this, please add your experiences!

Other Distributions

As previously mentioned, the above instructions are based off of ClarkConnect. Unfortunately not all distributions operate the same, some have optimized ways of handling things, etc. Listed below are other common distributions and any special notes. Note to contributors: Please mention both the distribution and version(s) you've tested on as package names can change between distributions.

Debian Linux Etch

This is for Debian Etch (v4.0). Machine this was based off of is running "stable" and had no X services prior to this.

Installing Required Files

aptitude install xvfb xbase-clients xfonts-base libgtk2.0-0

Using xvfb-run

Debian's version of Xvfb comes with a utility script called xvfb-run. This script runs an Xvfb instance and also runs the specified program in one command. Start out by following the Copying over the BRS config file section above making changes as necessary. Then you can test it out by running the following from the BRS installation directory

xvfb-run -s "-screen 0 640x480x16" ./BitWiseRoutingServer

If it just stays a blank line and doesn't exit out, then the server is probably running. You should then follow Configure your router for port forwarding.

To have it run at boot, you just have to add the following three lines to /etc/rc.local above where it says "exit 0." You change into the directory BRS is installed (/root/BitWiseRoutingServer in this case) and start BRS and make it a background task using the &.

echo "Starting BitWise Routing Server..."
cd /root/BitWiseRoutingServer
xvfb-run -s "-screen 0 640x480x16" ./BitWiseRoutingServer &

If you need to stop the server and it was backgrounded, you can get the proper process id with the following:

ps aux | grep "BitWiseRoutingServer"

Look for the line that just says "./BitWiseRoutingServer" and then give that process id the TERM signal (this example assumes the PID is 1234

kill -term 1234


This is a very "quick and dirty" method to get a BRS up and running. Preferably you should create an init file in /etc/init.d that can handle start, stop, and restart. See /etc/init.d/README for more information. Until an example is added here.