HOWTO: Run UML with VLANs

When testing different VLANs, it is common to have multiple computers on a VLAN with similar or same configurations. Other times, hardware is lacking to build sufficiently similar machines. Using Linux and User-Mode-Linux, you can use a clone of the same filesystem to connect to different VLANs.

1. Requirements
2. Getting the files
3. Setting it all up      
3.1 Host Kernel      
3.2 UML utilities      
3.3 UML kernel      
3.4 Root filesystem image      
3.5 TAP device
4. Starting it up

1. Requirements

   1. It is assumed that you are familiar with compiling kernels and software.

   2. -Linux Kernel 2.4.x, 2.6.x with 802.1q VLAN, 802.1d Bridging, Universal TUN/TAP, Loopback block device
      -vconfig (apt-get install vlan)
      -Access to root (or equivalent) on the target machine.

   3. Why you shouldn't use the “Debian Way” (apt-get install whatever)
      This set up requires some kernel customizations as well as some custom settings for some portions of the UML.
      Debian has limited version support and may or may not do things that work with the newer kernels. The safest way is to compile your own kernel, UML, and utilities.

2. Download the following files from the User-Mode-Linux webpage.
   ( http://user-mode-linux.sourceforge.net )

   1. UML Patch for kernels
      Choose which kernel you wish to run as the UML. This can be any version provided there is a patch available for it.

   2. UML Utilities
      Download the most recent version. These tools are required to make use of many UML features.

   3. Root filesystem
      I would recommend the Debian image as it is the easiest to work with and update/upgrade.

   4. Host SKAS patch (optional)
      This patch allows the UML software to use Seperate Kernel Address Space. It is not known to cause any problems in the host, and gives a great performance boost to the UML (and consequently the software running in it).
      
      Download the patch most appropriate to your kernel version. (highest version equal to or below your kernel)

   5. You will also need one or more kernels from http://www.kernel.org as your computer's kernel (host kernel) and your UML's kernel. They can be the same or different versions as long as UML/host patches are available for them.

3. Set up.

   1. Download and compile the Host kernel (if necessary). If your kernel lacks any of the requirements in 1.2, or you wish to use SKAS, you will probably need to recompile your kernel. I have tested these procedures with the stock kernels from kernel.org. Your mileage may vary with vendor modified kernels.

      1. Apply the SKAS patch (optional)
         e.g.
         $ cd linux-2.6.7
         $ patch -p1 < ../host-skas3-2.6.7-v1.patch

      2. On 2.4.x, they can either be compiled as modules or included into the kernel.

         1. Using make menuconfig
            Networking Options -> 802.1q VLAN support, 802.1d Ethernet Bridging
            Network Device Support -> Universal TUN/TAP device driver support
            Block Devices -> Loopback device support
            (this is for SKAS mode): Processor type and features -> /proc/mm support

         2. Using make config
            CONFIG_TUN, CONFIG_VLAN_8021Q, CONFIG_BRIDGE, CONFIG_BLK_DEV_LOOP, CONFIG_PROC_MM

      3. On 2.6.x, they can either be compiled as modules or included into the kernel.

         1. Using make menuconfig
            Device Drivers -> Networking Support -> Universal TUN/TAP device driver support
            Device Drivers -> Networking Support -> Networking Options -> 802.1d Ethernet Bridging, 802.1Q VLAN support
            Device Drivers -> Block Devices -> Loopback device support
            (this is for SKAS mode): Processor type and features -> /proc/mm support

         2. Using make config
            CONFIG_TUN, CONFIG_VLAN_8021Q, CONFIG_BRIDGE, CONFIG_BLK_DEV_LOOP, CONFIG_PROC_MM

      4. Compile the kernel as you would normally do (i.e. make, or make dep ; make bzImage) and install it. Reboot.

   2. Compile and install the UML utilities. You can change the install destination in Makefile (BIN_DIR and LIB_DIR) if you so wish.
      Your UML Utilities version may be different.
      $ tar xjf uml_utilities_20040406.tar.bz2
      $ cd tools
      $ make
      $ su -
      # make install

   3. Build the UML “kernel”, which is actually just a binary to start the UML. I have tested these procedures with the stock kernels from kernel.org. Your mileage may vary with vendor modified kernels.
      $ cd linux-2.4.26
      $ patch -p1 < ../uml-patch-2.4.26-1
      $ make menuconfig ARCH=um
      $ make linux ARCH=um
      
      This will create a binary called 'linux'. Move it to another directory. As this is for testing, I decided not to compile anything as modules and anything I wished to include were compiled into the 'kernel'. Be sure to include 802.1q VLAN support if you wish to test multiple VLANs inside the UML (i.e. the UML sees the tagged VLANs).

   4. Set up the image
      Ensure the 'linux' binary is in the same directory as where you will decompress the UML image.
      $ cd uml
      $ bunzip2 -dc Debian-3.0r0.ext2.bz2 > root_fs
      $ mkdir mnt
      
      If you need to install additional packages, or preconfigure the image, follow:
      $ su -
      # mount root_fs mnt -o loop
      # chroot mnt
      
      Ensure that the DNS server is correct
      # vi /etc/resolv.conf
      
      Install packages, you may want to get vlan, dhclient, ssh, and a console web browser, such as lynx. You will have to create a larger image file or create a second image file if you want to use X.
      # apt-get update
      # apt-get install <packages>
      # exit
      # umount mnt
      # exit

   5. Configure the tap device and the bridge
      $ su -
      # tunctl -u <UML-user>
      
      where UML-user is the user who will be running the UML. This user must also have write access to /dev/net/tun
      tunctl will tell you what tap device it has created/assigned. You will need to add this to the bridge.
      
      # brctl addbr br0 #create a bridge
      # brctl addif br0 tap0 #add the TAP device to it
      
      You may use method 1 or method 2, not both. (You can't join a bridge to a bridge, nor is it wise to join a piece of a bridged interface to another bridge).

      1. Method 1 (preferred): Host untags the VLANs for the UML
         This simulates a more “real” environment in the UML (most OSes don't have VLAN support built in!)
         
         # vconfig add <physical-interface> <vlan-number>
         i.e.
         # vconfig add eth0 192
         
         This will create a device called eth0.192
         # brctl addif br0 eth0.192
         
         Bring it all up
         # ifconfig eth0.192 up; ifconfig tap0 up; ifconfig br0 up
         
         To add another host to the same VLAN, create a new tap device and add it to the bridge
         # tunctl -u <UML-user>
         # ifconfig tap1 up
         # brctl addif br0 tap1
         
         To add another host to a different VLAN, create a new tap device and repeat the method 1 steps.

      2. Method 2: Host bridges all VLANs to the UML
         
         remove ip address from eth0
         # ifconfig eth0 0.0.0.0
         
         add eth0 to bridge and configure
         # brctl addif br0 eth0
         # ifconfig eth0 up; ifconfig tap0 up; ifconfig br0 129.97.15.xx netmask 255.255.255.0 ; route add default gw 129.97.15.x
         
         To add another host to this set up, create a new tap device and add it to the bridge.
         # tunctl -u <UML-user>
         # ifconfig tap1 up
         # brctl addif br0 tap1

      3. Check
         If you're using kernel 2.4.x with ebtables/bridge-netfilter or 2.6.x, check for the prescence of /proc/sys/net/bridge ... by default this feature is disabled in the stock kernel.
         bridge-nf-call-arptables - pass (1) or don't pass (0) bridged ARP traffic to arptables' FORWARD chain.
         bridge-nf-call-iptables - pass (1) or don't pass (0) bridged IPv4 traffic to iptables' chains.
         bridge-nf-filter-vlan-tagged - pass (1) or don't pass (0) bridged vlan-tagged ARP/IP traffic to arptables/iptables.
         (from the bridge-nf FAQ on http://ebtables.sourceforge.net/ )
         
         By default, all bridged ARP, IP and VLAN traffic are filtered through ebtables if these entries are present, and are not filtered if these entries are not present.
         
         For Method 1 to work, bridge-nf-call-arptables and bridge-nf-call-iptables must be 0, OR you must have ebtables entry permitting traffic to the UML ARP/IP address(es).
         
         For Method 2 to work, bridge-nf-filter-vlan-tagged must be 0 OR you must have an ebtables entry permitting the tagged vlan to pass through.
         
         For testing purposes, it is safe to set all three to 0.

4. Start the UML!
   This starts a UML with 128MB of RAM and using tap0 as its eth0
   $ ./linux mem=128M eth0=tuntap,tap0
   
   Once the UML starts up, you can log in and use it like any other Linux system. You can even install X and try stuff out! Read the 'Running X' section on http://user-mode-linux.sourceforge.net to find out how.

-- SevernTsui - 19 Jul 2004