Running coLinux on linux[]

This document describes how to compile, run and set up networking with the Linux port of coLinux. The procedure as described here was tried with Debian Unstable as the host OS and the linux 2.6.10 kernel as guest. Furthermore the Debian filesystem image was used.


The latest release at the time of this writing (0.6.2) doesn't seem to compile on Linux. A snapshot release (colinux-20050301.src.tar.gz) obtained from did work fine however.

The instructions in doc/building.txt can be followed for compiling on Linux and using Linux as both host and guest. Insert the kernel module as indicated in this file. You need to be root to run coLinux.

Verify that you can run colinux now (although no networking yet).


Getting networking up and running is the most challenging part. These steps are derived from the documentation of the User-Mode Linux project at The steps required for coLinux are similar.

This will configure coLinux to use a bridged ethernet connection using a tap device. These instructions are valid for Debian Linux, you may need to adapt them to your Linux distribution. This procedure was tested on a workstation on an internal network with DHCP enabled.


You need to install the 'bridge-utils' package and the 'uml-utilities' package (you do not need to install user-mode linux itself). These packages provide the tunctl and brctl programs you need for the further steps.

First take down your normal network devices, so that dhcp client daemons do not interfere with the setup procedure:

host# /etc/init.d/networking stop

Next you will create a TUN/TAP device:

host# tunctl -u root

This previous step needs to be done at each boot before the network comes up. You could put a shell script in /etc/network/if-pre-up.d that will do this for you.

Edit the file /etc/network/interfaces to create a bridge connection, comment out the current definitions for your network card. The following will create a bridge that obtains its network information from dhcp:

auto br0
iface br0 inet dhcp
    bridge_ports eth0 tap0

You can also set up a static IP address, just use the corresponding directives. These are documented in the interfaces(5) man page

If you are using dhcpcd as your dhcp client daemon, you'll have to edit some files. You will namely have to edit /etc/dhcpc/config and /etc/dhcpc/dhcpcd.exe to mention br0 as a valid interface. You might need to make similar modifications if you're using other dhcp client software.

In /etc/dhcpc/config:

case ${INTERFACE} in

should be changed to:

case ${INTERFACE} in
eth0 | br0)

In /etc/dhcpc/dhcpcd.exe:

case ${INTERFACE} in
  eth*) ;;
 wlan*) ;;
*****) logger -s -p local0.err -t dhcpcd.exe "wrong interface name \"${INTERFACE}\""
        exit 1

Should be changed into:

case ${INTERFACE} in
  eth* | br*) ;;
 wlan*) ;;
*****) logger -s -p local0.err -t dhcpcd.exe "wrong interface name \"${INTERFACE}\""
        exit 1

Other Linux Distributions[]

This procedure was performed on Debian Linux, it might work differently on other distributions where some of the steps aren't needed or other steps must be performed. You will need the brctl and tunctl programs. In debian the relevant packages are bridge-utils and uml-utilities respectively.

You need to be root to execute this procedure on the host machine.

Take down your normal network devices, so that dhcp client daemons do not interfere with the setup procedure (if using dhcp then shut down any dhcp client daemons too):

host# ifconfig eth0 down

Then create a TUN/TAP device: host# tunctl -u root

Next you will create a bridge:

host# brctl addbr br0 host# ifconfig eth0 promisc up host# ifconfig tap0 promisc up

In the next step the bridge will be assigned a static IP. If you are not using DHCP currently then you can assign the bridge your current IP. Otherwise you might want to select an IP that is not in the DHCP server pool to prevent ip address collisions. You will want to make sure that the coLinux guest gets assigned a different IP than the bridge we are creating now. Replace $IP with the ip address you want to assign, you may need to tweak the netmask as well.

host# ifconfig br0 $IP netmask up

Now add the interfaces to the bridge:

host# brctl addif br0 eth0 host# brctl addif br0 tap0

You might need to fix up routing so that everything still works, replace $GW with your default gateway's ip address.

host# route add -host $GW dev br0 host# route add default gw $GW

You might want to make changes to your distribution's init scripts so that these steps are carried out automatically at bootup.


Launch colinux as normal, but add the line eth0=tuntap,tap0. Example:

host# colinux-daemon kernel=vmlinux cobd0=root_fs cobd1=swap_fs \ root=/dev/cobd0 eth0=tuntap,tap0

Configure the coLinux (guest) side of networking as normal, this is described in coLinuxNetworking. The short version is that you might be able to use a dhcp client to configure your network for you.

MassTranslated on Sun Apr 23 17:35:52 UTC 2006