HOWTO Automatically configure bridge interfaces on VirtualBox

Version: 0.1
Author: Antonio Augusto da Silva (a.k.a. KhaoticMind)
Date: 2007/03/16

NOTE: as of kernel 2.6.18 and later (i.e. with Ubuntu 7.04) this stopped working, as now normal users are no longer allowed to dynamically create TAP devices. See the VirtualBox user manual for details of how to do this is done in current versions of VirtualBox (1.4.0 and later).

1. Introduction

This is a quick tutorial on how to setup your Linux environment and VirtualBox, so that it can automatically create network interfaces and put them in bridge when the VM is launched.

In fact the Vbox User Manual has all the details that you need to accomplish it, but I thought it would be better to give some more "hands on" for you guys ;)

I've tested this setup in my home computer, running Kubuntu 6.10. I've an ADSL modem to which I connect through my eth0 port. The modem has DHCP, so I get my IP automatically.

1.1 What is bridging anyway?

Well... I thought you would already know it (since you are reading this howto). But hey... let me try to give you a brief explanation. Bridging in the sense we are working here, is to configure your computer, so that, some (or all), of the networks it has connected to it will look like they are in fact one single network.

One example of its use is if you have a notebook that can connect to your home computer through a wireless adapter and the home computer is also connect to the Internet (or to any other network) through a cable. To make the notebook able to access the Internet you have to options: routing(ref 1) and bridging(ref 2). Both solutions will work, but if you do routing only TCP/IP packets will be able to be exchanged (ok, ok, 90% of the world uses TCP/IP but hang with me). On the other hand bridging will give you a lot more of flexibility, since now the notebook will appear is it were direct connect to the other network, just like you. Doing so the notebook can then get its own IP address with DHCP, and you (and anybody on the same network than you) will be able to exchange any packet with the notebook without any problem.

What happens here is that your computer was turned in a Switch (or a HUB), and simple connects all machines that are connected to it, like you had cables connection every one of them. To do this on linux you create a "virtual" interface, that will be the actual bridge, and simple "plug" all interfaces you want to be connect to it. So what we will do here is configure a single bridge, and say that our network interface (usually eth0), and all network interfaces created by the VMs, will be connected to it.

1.2 Prerequisites

Before continuing the first thing you're going to need is make sure you have tunctl and brctl in your machine (the program VBoxTunctl is shipped with VirtualBox starting from version 1.4.0). These are the programs that we will use in the next sections to create our virtual interfaces and our bridge.

In Ubuntu these two programs are on the uml-utilities and bridge-utils packages, respectively.

To install these packages issue the following command:

sudo apt-get install bridge-utils uml-utilities

2. Configuring the bridge

Ok, so lets start with the fun ;)

First of all, lets configure the network setup so that you will have a br0 interface at boot, and your network interface (eth0) will be part of it.

To accomplish this in Ubuntu I've configured my /etc/network/interfaces to look something like this:

auto br0
iface br0 inet dhcp
       bridge_ports eth0

auto eth0
iface eth0 inet manual

Quite simple huh? With this setup you should have what we want. To test it immediately run reinitialise the network:

sudo /etc/init.d/networking restart

After it finish its job, doing an

ifconfig

should show you something like this:

br0        Encapsulamento do Link: Ethernet  Endereço de HW 00:11:D8:37:D8:B9
          inet end.: 192.168.1.2  Bcast:192.168.1.255  Masc:255.255.255.0
          endereço inet6: fe80::211:d8ff:fe37:d8b9/64 Escopo:Link
          UP BROADCAST RUNNING MULTICAST  MTU:1500  Métrica:1
          pacotes RX:6973 erros:0 descartados:0 excesso:0 quadro:0
          Pacotes TX:7301 erros:0 descartados:0 excesso:0 portadora:0
          colisões:0 txqueuelen:0
          RX bytes:3557787 (3.3 MiB) TX bytes:932172 (910.3 KiB)

eth0       Encapsulamento do Link: Ethernet  Endereço de HW 00:11:D8:37:D8:B9
          endereço inet6: fe80::211:d8ff:fe37:d8b9/64 Escopo:Link
          UP BROADCAST RUNNING MULTICAST  MTU:1500  Métrica:1
          pacotes RX:184453 erros:75 descartados:0 excesso:0 quadro:0
          Pacotes TX:255573 erros:0 descartados:0 excesso:0 portadora:0
          colisões:0 txqueuelen:1000
          RX bytes:23372490 (22.2 MiB) TX bytes:136539269 (130.2 MiB)
          IRQ:217 Endereço de E/S:0x6000

Note that br0 is the interface that gets the IP. The eth0 is like a "dummy" interface.

3. Giving the needed access

Ok, now we need to give some permissions to devices and files. Note that, as everything involving permissions, there is always some risk involved on it. But hey, its for a good cause!

3.1 /dev/net/tun

First things first, to allow VBox to automatically create the virtual interface it needs to have write access to /dev/net/tun. The best way I thought of doing it (without doing a chmod 666), was to change the ownership of the device to the vboxusers group. Since everybody that will run VBox will already be part of that group, this looked like a good solution. After that we need to give write permissions to the members of the group. Following are the commands:

sudo chown root.vboxusers /dev/net/tun
sudo chmod g+rw /dev/net/tun

3.2 ifconfig and brctl

Besides that you (optionally) need to setuid in the "ifconfig" and "brtcl" commands. Setuid is necessary on these commands because you need to call them on the script used to configure your network, but they both need to be run as root to do what we want.

People concerned with this security (like me) would raise an eyebrow with this, since setuids always introduce some risk on the system. In my case I decided the risk was low, and decided to live with it.

But if you don't want to use setuid below I will show a way to make the bridging work without needing to do setuids (but having to put root password every time you boot/shutdown a VM).

So, to do the setuid run the following commands:

chmod +s /sbin/ifconfig
chmod +s /usr/sbin/brctl

4. The scripts

Now that everything is in place lets configure the scripts that will be called by VirtualBox every time a VM is turned on/off. I call these scripts tapUP and tapDown, but you can name them whatever you want. The commands i use are the same as described in the VirtualBox User Manual, with the exception that i don't use sudo (since i did a setuid in ifconfig and brctl).

TapUP:

#!/bin/sh
/sbin/ifconfig $2 up 
/usr/sbin/brctl addif br0 $2

TapDown:

#!/bin/sh
/usr/sbin/brctl delif br0 $2

If you decided to not do the setuid in step 3.2, you can use kdesu (for example), to ask root password when running these commands. The files would look something like this:

TapUP:

#!/bin/sh
kdesu "/sbin/ifconfig $2 up && /usr/sbin/brctl addif br0 $2"

TapDown:

#!/bin/sh
kdesu /usr/sbin/brctl delif br0 $2

I put both command between commas and use the "&&" so that it asks for the password only once.

5. Wrapping it up

Well, thats it! Quite easy huh? Now all you need to do is create and virtual machine, go on its "Network" options, change the "Attached to" to "Host Interface", give the Interface a name (each machine should use a different interface!), and point the "Startup Application" and "Terminate Application", to your TapUP and TapDown files.

I've tested it with a Windows guest, and everything worked like a charm.

6. Thanks

7. Changelog

0.1 -> Initial version
0.2 -> wikified it a bit more and added the note about Ubuntu 7.04 (klaus)

8. References

[1] ​http://en.wikipedia.org/wiki/Routing
[2] ​http://en.wikipedia.org/wiki/Bridging_%28networking%29