Below, you will see that the TUN/TAP, ethertap, and daemon interfaces allow you to specify hardware addresses for the virtual ethernet devices. This is generally not necessary. If you don't have a specific reason to do it, you probably shouldn't. If one is not specified on the command line, the driver will assign one based on the device IP address. It will provide the address fe:fd:nn:nn:nn:nn where nn.nn.nn.nn is the device IP address. This is nearly always sufficient to guarantee a unique hardware address for the device. A couple of exceptions are:

• Another set of virtual ethernet devices are on the same network and they are assigned hardware addresses using a different scheme which may conflict with the UML IP address-based scheme
• You aren't going to use the device for IP networking, so you don't assign the device an IP address

If you let the driver provide the hardware address, you should make sure that the device IP address is known before the interface is brought up. So, inside UML, this will guarantee that:

UML# ifconfig eth0 192.168.0.250 up

If you decide to assign the hardware address yourself, make sure that the first byte of the address is even. Addresses with an odd first byte are broadcast addresses, which you don't want assigned to a device.

Once the network devices have been described on the command line, you should boot UML and log in.

The first thing to do is bring the interface up:

UML# ifconfig ethn ip-address up

You should be able to ping the host at this point.

To reach the rest of the world, you should set a default route to the host:

UML# route add default gw host ip

Again, with host ip of 192.168.0.4:

UML# route add default gw 192.168.0.4

This page used to recommend setting a network route to your local net. This is wrong, because it will cause UML to try to figure out hardware addresses of the local machines by arping on the interface to the host. Since that interface is basically a single strand of ethernet with two nodes on it (UML and the host) and arp requests don't cross networks, they will fail to elicit any responses. So, what you want is for UML to just blindly throw all packets at the host and let it figure out what to do with them, which is what leaving out the network route and adding the default route does.

Note: If you can't communicate with other hosts on your physical ethernet, it's probably because of a network route that's automatically set up. If you run 'route -n' and see a route that looks like this:

                
Destination     Gateway         Genmask         Flags Metric Ref    Use Iface
192.168.0.0     0.0.0.0         255.255.255.0   U     0      0	    0   eth0

              

with a mask that's not 255.255.255.255, then replace it with a route to your host:

UML# route del -net 192.168.0.0 dev eth0 netmask 255.255.255.0

UML# route add -host 192.168.0.4 dev eth0

This, plus the default route to the host, will allow UML to exchange packets with any machine on your ethernet.

If you prefer not to have UML use uml_net (which is somewhat insecure), with UML 2.4.17-11, you can set up a TUN/TAP device beforehand. The setup needs to be done as root, but once that's done, there is no need for root assistance. Setting up the device is done as follows:

• Create the device with tunctl (available from the UML utilities tarball)
  

  host# tunctl -u uid

  where uid is the user id or username that UML will be run as. This will tell you what device was created.
• Configure the device IP (change IP addresses and device name to suit)
  

  host# ifconfig tap0 192.168.0.254 up

• Set up routing and arping if desired - this is my recipe, there are other ways of doing the same thing

  host# bash -c 'echo 1 > /proc/sys/net/ipv4/ip_forward'
  

  host# route add -host 192.168.0.253 dev tap0
  

  host# bash -c 'echo 1 > /proc/sys/net/ipv4/conf/tap0/proxy_arp'
  

  host# arp -Ds 192.168.0.253 eth0 pub

  Note that this must be done every time the host boots - this configuration is not stored across host reboots. So, it's probably a good idea to stick it in an rc file. An even better idea would be a little utility which reads the information from a config file and sets up devices at boot time.
• Rather than using up two IPs and ARPing for one of them, you can also provide direct access to your LAN by the UML by using a bridge.

  host# brctl addbr br0

  host# ifconfig eth0 0.0.0.0 promisc up

  host# ifconfig tap0 0.0.0.0 promisc up

  host# ifconfig br0 192.168.0.1 netmask 255.255.255.0 up

  host# brctl stp br0 off

  host# brctl setfd br0 1

  host# brctl sethello br0 1

  host# brctl addif br0 eth0

  host# brctl addif br0 tap0

  Note that 'br0' should be setup using ifconfig with the existing IP address of eth0, as eth0 no longer has its own IP.

• Also, the /dev/net/tun device must be writable by the user running UML in order for the UML to use the device that's been configured for it. The simplest thing to do is

  host# chmod 666 /dev/net/tun

  Making it world-writeable looks bad, but it seems not to be exploitable as a security hole. However, it does allow anyone to create useless tap devices (useless because they can't configure them), which is a DOS attack. A somewhat more secure alternative would to be to create a group containing all the users who have preconfigured tap devices and chgrp /dev/net/tun to that group with mode 664 or 660.
• Once the device is set up, run UML with

  eth0=tuntap,devicename

  i.e.

  eth0=tuntap,tap0

  on the command line (or do it with the mconsole config command).
• Bring the eth device up in UML and you're in business.

If you don't want that tap device any more, you can make it non-persistent with

host# tunctl -d tap device

Finally, tunctl has a -b (for brief mode) switch which causes it to output only the name of the tap device it created. This makes it suitable for capture by a script:

host# TAP=`tunctl -u 1000 -b`

Ethertap is the general mechanism on 2.2 for userspace processes to exchange packets with the kernel.

To use this transport, you need to describe the virtual network device on the UML command line. The general format for this is

eth<n>=ethertap,<device>,<ethernet address>,<host IP address>

So, the previous example

eth0=ethertap,tap0,fe:fd:0:0:0:1,192.168.0.254

attaches the UML eth0 device to the host /dev/tap0, assigns it the ethernet address fe:fd:0:0:0:1, and assigns the IP address 192.168.0.254 to the host side of the tap device.

The tap device is mandatory, but the others are optional. If the ethernet address is omitted, one will be assigned to it.

The presence of the tap IP address will cause the helper to run and do whatever host setup is needed to allow the virtual machine to communicate with the outside world. If you're not sure you know what you're doing, this is the way to go.

If it is absent, then you must configure the tap device and whatever arping and routing you will need on the host. However, even in this case, the uml_net helper still needs to be in your path and it must be setuid root if you're not running UML as root. This is because the tap device doesn't support SIGIO, which UML needs in order to use something as a source of input. So, the helper is used as a convenient asynchronous IO thread. If you're using the uml_net helper, you can ignore the following host setup - uml_net will do it for you. You just need to make sure you have ethertap available, either built in to the host kernel or available as a module.

If you want to set things up yourself, you need to make sure that the appropriate /dev entry exists. If it doesn't, become root and create it as follows (the $[ ... ] is bash syntax for adding 16 to the minor number) :

mknod /dev/tap<minor> c 36 $[ <minor> + 16 ]

For example, this is how to create /dev/tap0:

mknod /dev/tap0 c 36 $[ 0 + 16 ]

You also need to make sure that the host kernel has ethertap support. If ethertap is enabled as a module, you apparently need to insmod ethertap once for each ethertap device you want to enable. So,

host# insmod ethertap

will give you the tap0 interface. To get the tap1 interface, you need to run

host# insmod ethertap unit=1 -o ethertap1

Note: This is the daemon formerly known as uml_router, but which was renamed so the network weenies of the world would stop growling at me.

The switch daemon, uml_switch, provides a mechanism for creating a totally virtual network. By default, it provides no connection to the host network (but see -tap, below).

The first thing you need to do is run the daemon. Running it with no arguments will make it listen on a default unix domain socket.

If you want it to listen on a different socket, use

-unix socket

If you want it to act as a hub rather than a switch, use

-hub

If you're planning on putting it in hub mode so you can sniff UML traffic from a tap device on the host, it appears that you need to assign the tap an IP address before you'll see any packets on it.

If you want the switch to be connected to host networking (allowing the umls to get access to the outside world through the host), use

-tap tap0

Note that the tap device must be preconfigured (see "TUN/TAP with a preconfigured tap device", above). If you're using a different tap device than tap0, specify that instead of tap0.

uml_switch can be backgrounded as follows

host% uml_switch [ options ] < /dev/null > /dev/null

The reason it doesn't background by default is that it listens to stdin for EOF. When it sees that, it exits.

The general format of the kernel command line switch is

ethn=daemon,ethernet address,socket type,socket

You can leave off everything except the 'daemon'. You only need to specify the ethernet address if the one that will be assigned to it isn't acceptable for some reason. The rest of the arguments describe how to communicate with the daemon. You should only specify them if you told the daemon to use different sockets than the default. So, if you ran the daemon with no arguments, running the UML on the same machine with

eth0=daemon

will cause the eth0 driver to attach itself to the daemon correctly. The socket argument is the filename of a Unix domain socket which is used for communications between uml_switch and the UMLs on its network. If you do specify a different socket from the default, which you will need to do if you want multiple, separate uml_switch networks on the host, you need to make sure that you name the same path for the socket on both the uml_switch and UML command lines.

Currently the only supported value for the socket type is "unix".

Slip is another, less general, mechanism for a process to communicate with the host networking. In contrast to the ethertap interface, which exchanges ethernet frames with the host and can be used to transport any higher-level protocol, it can only be used to transport IP.

The general format of the command line switch is

ethn=slip,slip IP

The slip IP argument is the IP address that will be assigned to the host end of the slip device. If it is specified, the helper will run and will set up the host so that the virtual machine can reach it and the rest of the network.

There are some oddities with this interface that you should be aware of. You should only specify one slip device on a given virtual machine, and its name inside UML will be 'umn', not 'eth0' or whatever you specified on the command line. These problems will be fixed at some point.

slirp uses an external program, usually /usr/bin/slirp, to provide IP only networking connectivity through the host. This is similar to IP masquerading with a firewall, although the translation is performed in user-space, rather than by the kernel. As slirp does not set up any interfaces on the host, or changes routing, slirp does not require root access or setuid binaries on the host.

The general format of the command line switch for slirp is:

ethn=slirp,ethernet address,slirp path

The ethernet address is optional, as UML will set up the interface with an ethernet address based upon the initial IP address of the interface. The slirp path is generally /usr/bin/slirp, although it will depend on distribution.

The slirp program can have a number of options passed to the command line and we can't add them to the UML command line, as they will be parsed incorrectly. Instead, a wrapper shell script can be written or the options inserted into the ~/.slirprc file. More information on all of the slirp options can be found in its man pages.

The eth0 interface on UML should be set up with the IP 10.2.0.15, although you can use anything as long as it is not used by a network you will be connecting to. The default route on UML should be set to use 'eth0' without a gateway IP:

UML# route add default dev eth0

slirp provides a number of useful IP addresses which can be used by UML, such as 10.0.2.3 which is an alias for the DNS server specified in /etc/resolv.conf on the host or the IP given in the 'dns' option for slirp.

Even with a baudrate setting higher than 115200, the slirp connection is limited to 115200. If you need it to go faster, the slirp binary needs to be compiled with FULL_BOLT defined in config.h.

The pcap transport is attached to a UML ethernet device on the command line or with uml_mconsole with the following syntax:

ethn=pcap,host interface,filter expression,option1,option2

The expression and options are optional.

The interface is whatever network device on the host you want to sniff. The expression is a pcap filter expression, which is also what tcpdump uses, so if you know how to specify tcpdump filters, you will use the same expressions here. The options are up to two of 'promisc', 'nopromisc', 'optimize', 'nooptimize'. 'promisc' and 'nopromisc' control whether pcap puts the host interface into promiscuous mode. 'optimize' and 'nooptimize' control whether the pcap expression optimizer is used.

Example:

eth0=pcap,eth0,tcp
eth1=pcap,eth0,!tcp

will cause the UML eth0 to emit all tcp packets on the host eth0 and the UML eth1 to emit all non-tcp packets on the host eth0.

If you don't specify an address for the host side of the ethertap or slip device, UML won't do any setup on the host. So this is what is needed to get things working (the examples use a host-side IP of 192.168.0.251 and a UML-side IP of 192.168.0.250 - adjust to suit your own network):

• The device needs to be configured with its IP address. Tap devices are also configured with an mtu of 1484. Slip devices are configured with a point-to-point address pointing at the UML ip address.

  host# ifconfig tap0 arp mtu 1484 192.168.0.251 up

  host# ifconfig sl0 192.168.0.251 pointopoint 192.168.0.250 up

• If a tap device is being set up, a route is set to the UML IP.

  UML# route add -host 192.168.0.250 gw 192.168.0.251

• To allow other hosts on your network to see the virtual machine, proxy arp is set up for it.

  host# arp -Ds 192.168.0.250 eth0 pub

• Finally, the host is set up to route packets.

  host# echo 1 > /proc/sys/net/ipv4/ip_forward