[Qemu-devel] notes on tun networking

[Eric S. Johansson]

I have been stymied by the networking of qemu and I really want to try
and solve my problems and hopefully document them so the solution is
useful to others.

Almost all the documentation I've seen so far makes the assumption
that the end-user is network engineer level knowledgeable.  While this
is an understandable focus, it does not help the user who sees QEMU as
a tool to get a job done.  Approaching the narrative from a task
oriented perspective may help QEMU be more accessible and reduce the
support load.

I hope these notes help.  Writing them certainly helped clarify a bunch 
of details in my head.

-----

Some of the partially formed requirements going through the users mind
might be:

I want the guest OS to be able to access machines on the local LAN
I want the guest OS to be able to access the Internet
I want machines on the local LAN to access the guest OS
I want machines on the Internet to access the guest OS

A related thought which is an attempt to find a solution to all of the
above is "I want the guest OS to have an address on the local LAN

the four basic requirements can be collapsed into two (one inbound,
one outbound) but the explanation must show how the two requirements
are equivalent to the four basic requirements.

as I understand the basic tun configuration, the network configuration
looks something like the graphic below.

                   +--------+
                   |  host  |
                ======      |
   LAN +-------+ eth0       |         +--------+
                ======      |         |  guest |
                   |     ====== vlan ====      |
                   |      tun0 +----+eth0      |
                   |     ======      ====      |
                   |        |         |        |
                   +--------+         +--------+

in this configuration the lan and the vlan are different subnets.
(Note to network beginners, don't question, don't change, just accept
this.)

In achieving the outbound requirement, the guest OS uses the tun0
interface as its gateway to the outside world.  Packets from the guest
OS eth0 are routed through the tun0 interface then traverse the host
and are delivered to the LAN via the host eth0.  If the packets are
going further, than they are handed off to the gateway device for
delivery

Satisfying inbound requirement requires some vehicle for routing
packets on the LAN to the VLAN subnet.  The most convenient place is
the LAN gateway device (e.g. router, firewall etc.).  but if it's only
necessary to enable a single external host, one can add the a point to
point route on both the lan machine and the host machine.

(note: while this basic outline works fine with Lennox, for some
reason connections initiated from windows don't work.)

implementation example:

Fill in these values (suggested values between parenthesis):

IP address on host machine:

Network definition for virtual LAN

Subnet:  (172.20.0.0)

netmask: (255.255.0.0)

host tun address (172.20.0.1)

guest address (172.20.0.10)


network definition for host

public host address:

with all of these values defined, it's possible to start building a
working configuration.  First, look at the default qemu ifup script:

#!/bin/sh
sudo -p "Password for $0:" /sbin/ifconfig $1 172.20.0.1

as you can see, it's very simple but it's not complete if you want the
guest machine accessible from the outside world.  When the script runs
it creates tun0 with the host tun address.  As you can see, the
default script uses the default value 172.20.0.1.  if you are using a
different value as document above, change the script to reflect that
new value now.

The reason I say it's not complete is that if you are trying to pass
packets from eth0 to tun0, the default settings of most Linux
distributions don't allow for packet forwarding.  The reason for this
is security so that your host can't relate traffic for others.

One should have IP tables entries to block any traffic except what is
passing between the eth0 and tun0 interfaces but... (I've been
wrestling with this problem on and off for a couple of days.  And as
much as it has been fun, it doesn't put food on the table.  I need
to get on with what I get paid for.  if someone wants to volunteer
rules, I'll fit them into this document)

in order to enable forwarding, add this line to the end of the default
qemu_ifup script.  Because it does increase the risk to your machine
and network, only do this if and when you want the qemu guest OS
accessible from the outside world.:

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

but once you do this, don't expose your machine to hostile networks.
If you wish to eliminate this capability, simply type:

 echo 0 > /proc/sys/net/ipv4/ip_forward

and the forwarding feature will turn off isolating your guest machine from
the network.

Following the installation instruction's documented elsewhere, install
your distribution of Linux or Windows and when it comes time to set up
a network interface, use the guest address and virtual network netmask
for the ethernet interface.  The gateway address for the guest OS will
be the tun address

Once the guest OS is running, see if the interfaces are reachable from
the host machine.  Use ping to see of the tun and guest interfaces are
alive.  Don't even think of trying this from an external machine.  It
just won't work.

the next stage is changing routing to make it possible to access the
virtual network.  There are a couple ways to do this but I'm only
going to cover the systemwide version.  Go to your gateway router.
This is typically the box that connects you to the Internet.  If you
do not have permission to modify this box, find someone who can or
work solely on the host machine.

what we want to do is route the guest network to the IP address of the
host machine.  Using our sample data from above:

route 172.20.0.0 gateway 192.168.0.10

a real example under Linux is:

route add -net 172.20.0.0 netmask 255.255.0.0 gw 192.168.0.10

from the router box, you should be able to ping the tun and guest
addresses.  additional tests you may want to perform are ssh into and
out of the guest machine as well as the usual http services.  One
caution, I have found with this configuration that Linux machines can
access the guest without problem but for some reason Windows machines
don't work very well.

If you have any problems, check routing, use TCP dump to verify that
packets get to where they're supposed to go and that there are return
packets coming back.  Most common failure is IP forwarding and
improper gateway address set ups on the guest machine.  At least,
those of the mistakes I made most often.