2.3.2/doc/vdeqemu-HOWTO

   1 Using VDE with Qemu HOWTO
   2 by Jim Brown
   3 5 Oct 2004
   4 Version 0.2
   5
   6 -----------------------------------------------------------------------------
   7
   8 Introduction
   9         Copyright
  10         What is qemu?
  11         What is VDE?
  12
  13 Configuring and Installing VDE
  14         Installation
  15         vdeq & vdeqemu
  16
  17 User-mode networking
  18         How to enable user-mode networking
  19         Firewall configuration
  20
  21 Slirp (rootless) networking
  22         What is slirp networking?
  23         How to enable slirp networking?
  24
  25 Setting up qemu
  26         How to set up the guest OS
  27
  28 Credits
  29
  30 -----------------------------------------------------------------------------
  31
  32 Introduction
  33
  34 Copyright
  35
  36 Copyright (c) 2004 Jim Brown.
  37 Permission is granted to copy, distribute and/or modify this document
  38 under the terms of the GNU Free Documentation License, Version 1.2
  39 or any later version published by the Free Software Foundation;
  40 with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
  41 Texts.  A copy of the license is available at http://www.gnu.org/licenses/fdl.txt
  42
  43 What is qemu?
  44
  45         Qemu is a FAST! processor emulator by Fabrice Bellard, available at
  46 http://fabrice.bellard.free.fr/qemu/. It is capable of emulationg the x86 and
  47 PowerPC processors with support for other processors on the way. The original
  48 purpose of qemu was to allow running x86-specific Linux applications, such as
  49 WINE or DosEmu, on non-x86 systems. However, qemu has expanded into becoming
  50 a full-fledged emulator. On the x86 side, it is capable of running Linux,
  51 MS-DOS, Windows 95/98/Me, Windows NT/2k, Windows XP, Solaris, OpenBSD, and
  52 FreeBSD. See http://fabrice.bellard.free.fr/qemu/ossupport.html for the full
  53 listing.
  54
  55         This howto assumes that you have already installed and set up qemu.
  56
  57 What is VDE?
  58
  59         VDE is short for Virtual Distributed Ethernet. VDE, written by
  60 Renzo Davoli, is based off of uml_switch by Jeff Dike. It is available at
  61 http://sourceforge.net/projects/vde/. It has many uses, the main one providing
  62 support for networking with emulated computers. (Not just qemu, but support
  63 for user-mode linux and Bochs also exists). VDE must be set up and installed by
  64 root, but the programs which use it do not need root privligies.
  65
  66         This howto will walk you through the simple process of installing
  67 VDE and setting up qemu to use it.
  68
  69 -----------------------------------------------------------------------------
  70
  71 Configuring and Installing VDE
  72
  73 Installation
  74
  75         You may obtain the source code at http://sourceforge.net/projects/vde/.
  76 The version of VDE which I used was 1.4.1, but this HOWTO should apply to all
  77 versions.
  78
  79         Once you have downloaded the source code, extract it. I assume you
  80 will have extracted it to /space/vde. Go into that directory, and simply type
  81 "make" followed by "make install". Now you should have vde_switch in /usr/bin.
  82
  83 vdeq & vdeqemu
  84
  85         Now cd into the qemu directory. Type "make". This will build vdeq.
  86 Qemu on its own only supports full networking with tuntap, which requires
  87 root priviliges or an exposed /dev/net/tun. There is a -user-net option, but
  88 that is not as useful as full networking. In order for qemu to use VDE, it must
  89 be passed the file descriptor for a tun device. Futhermore the tun device itself
  90 must already be configured to use VDE. vdeq sets this up and passes it to qemu
  91 via the -tun-fd switch.
  92
  93         There is no "make install". Instead, you just manually copy vdeq to
  94 /usr/bin. It might also be helpful to copy or link vdeq to vdeqemu. vdeq
  95 requires that the location of the qemu binary be passes to it as the first
  96 command line parameter, but vdeqemu only needs the options you want to pass to
  97 qemu. vdeqemu will locate the qemu binary itself (this requires that you install
  98 qemu system-wide or have the qemu directory in your PATH).
  99
 100 For example if you have:
 101 vdeq qemu -hda /mnt/myimage -m 64 -boot a
 102
 103 you can shorten this into
 104
 105 vdeqemu -hda /mnt/myimage -m 64 -boot a
 106
 107 -----------------------------------------------------------------------------
 108
 109 User-mode Networking
 110
 111 How to enable user-mode networking
 112
 113         The following commands will need to be run as root:
 114
 115 # vde_switch -tap tap0 -daemon
 116
 117 If you need to run a sniffer, just in case you want to analyze the traffic,
 118 you can also run it like this:
 119
 120 # vde_switch -hub -tap tap0 -daemon
 121
 122 (The -hub option is not available for version 1.4.1 of VDE, you will need a
 123 later version. I don't know what the minimal version is but 1.5.1 does support
 124 this option.)
 125
 126 Then you must run this:
 127
 128 # ifconfig tap0 <ip>
 129 # chmod 755 /tmp/vde.ctl
 130
 131         The vde_switch command will run VDE in the background. The -tap tap0
 132 parameter tells VDE to set up the device tap0 using tuntap. -daemon runs
 133 vde_switch in the background. -hub tells VDE to broadcast the message to all
 134 segment, just like real hub that you use on real network.
 135
 136         <ip> is the ip address of the gateway you want to use for the guest
 137 OS(es). For example:
 138
 139 # ifconfig tap0 192.168.254.254
 140
 141         will make 192.168.254.254 the gateway between guest and host, and your
 142 guest OS(es) will belong to the subnet 192.168.254.0 with a netmask of 255.255.255.0
 143 and an ip address of 192.168.254.XXX (where you get to pick the XXX). You must have
 144 the IP of the qemu guest and the IP of the gateway on the same subnet! While it
 145 may be possible to have them on separate subnets, it will certainly be harder
 146 to configure (and you won't like the way your routing tables will look either).
 147
 148 [Sidebar: The "gateway" is actually the host OS itself on the tap0 interface.
 149 The host on the tap0 interface, aka 192.168.254.254, routes between the guest
 150 OS and the host's eth0 interface (which on is the real network). The host on the
 151 eth0 interface (ex. 192.168.0.2) can then route between the tap0 interface and
 152 the real network / the internet.]
 153
 154 (Note that you might be required to do this:
 155
 156 # ifconfig tap0 192.168.254.254 netmask 255.255.255.0
 157
 158 Normally ifconfig should pick the correct netmask for you, but if it doesn't
 159 for some reason then you will have to specify it manually. See ifconfig(8) for
 160 details.
 161
 162 )
 163
 164 Note that you must run this before you run your firewall. I found it helpful
 165 to put this into a script, and have the script load before the firewall does.
 166
 167 Firewall configuration
 168
 169         You will need to enable masquerading between tap0 and your local area
 170 network (for example, eth0). You will also need to enable masquerading between
 171 tap0 and ppp0 if you use a dialup connection to the internet. The commands
 172
 173 # echo "1" > /proc/sys/net/ipv4/ip_forward
 174 # iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE
 175 # iptables -t nat -A POSTROUTING -o ppp0 -j MASQUERADE
 176
 177         will allow you to enable this manually.
 178
 179 -----------------------------------------------------------------------------
 180
 181 Slirp networking
 182
 183 What is slirp networking?
 184
 185 Slirp was an early program that existed before the masses knew of the internet.
 186 Back then, those who knew of it could access it only in one way: through a
 187 Unix shell account (or other such terminal account). This meant that one had to
 188 do all the things they wanted to in that terminal window. Back then, there were
 189 two dial up protocols: PPP and SLIP. PPP is now the standard but back then SLIP
 190 was more common (as it was cheaper).
 191
 192 Slirp was designed to turn those shell accounts into SLIP connections. It worked
 193 by converting SLIP packets into socket connections. What you had to do was to
 194 run slirp on the computer you had the shell account on, and then connect your
 195 SLIP driver/dialer to the terminal slirp was running on (normally this
 196 'terminal' was in fact a modem). Slirp would then interpret the data that SLIP
 197 sent and transfer the data between the user's computer and the internet. To
 198 the user, it looked like they were actually connected directly to the internet
 199 through a firewall.
 200
 201 Slirp is not used today (to the best of my knowledge) but the innovative idea it
 202 had is used by both qemu and vde. Instead of converting SLIP packets however,
 203 they convert ethernet packets. qemu's slirp networking is similar to vde's
 204 but it is simpler to use and also limited to a single qemu instance (you can
 205 not link multiple guest OSes together on the same network with slirp networking
 206 unless you use VDE).
 207
 208 How to enable slirp networking?
 209
 210 This is very similar to TUNTAP networking in the previous section, but the
 211 commands are slightly different. In addition, you do not need to set up
 212 routing or firewall rules.
 213
 214 First off, you load vde_switch (no parameters are required for this case,
 215 although you can pass the -unix parameter if you want to use a different
 216 socket - required if you already have tuntap networking on the default
 217 socket).
 218
 219 vde_switch
 220
 221 or
 222
 223 vde_switch -unix /tmp/unx.ctl
 224
 225 The latter is required if you are running both slirp and tuntap or multiple
 226 slirp networks (for that matter, if you are running multiple tuntap networks).
 227 More on that later.
 228
 229 Now you need the slirpvde command. slirpvde is the utilitry that provides the
 230 slirp functionality - it intercepts ethernet packets on the network and
 231 forwards them through the real network via emulation. To use it, you want
 232 to do this:
 233
 234 slirpvde -s /tmp/unx.ctl -n 192.168.2.0 -d
 235
 236 The -s tells slirpvde that vde_switch is running on /tmp/unx.ctl [this switch
 237 can be omitted if you called vde_switch by itself]. The -d switch tells
 238 slirpvde to emulate a DHCP server. This is not required but it allows for
 239 automatic configuration of the guest OS (it is basicly the same as qemu's
 240 builtin DHCP server). Depending on your needs, you may be better off running
 241 a real DHCP server in one of the guest OSes.
 242
 243 The last option, -n, tells slirpvde
 244 what subnet the network should be on (this is also used by the DHCP server to
 245 figure out what ip addresses to assign). The gateway ip when using slirpvde
 246 is X.X.X.2 (where X.X.X equals the first 3 parts of the subnet you passed to
 247 it via -n, in this example 192.168.2) and the default DNS server is X.X.X.3
 248
 249 You can not change the gateway ip to something other than .2 and the DNS ip
 250 to something other than .3 unless you change the source in slirpvde and
 251 recompile.
 252
 253 -----------------------------------------------------------------------------
 254
 255 Setting up qemu
 256
 257 How to set up the guest OS
 258
 259         Set up the guest OS so that the default route is through the gateway
 260 ip, <ip> (for example 192.168.254.254). Also set up the subnet and netmask
 261 parameters as appropriate (for example 192.168.254.0 and 255.255.255.0).
 262 The guest OS should see the ethernet device and be able to use it to access
 263 the gateway. (Caveat: I haven't been able to do this for MS-DOS, and for Minix
 264 2.0.4 I had to apply a patch to qemu since Minix is broken. Uodate: Minix 2.0.4
 265 is still broken but a patch has been released to fix it. Using this patch,
 266 Minix works on a vanilla qemu.) Also don't forget to set up the IP of the guest
 267 OS itself (for example 192.168.254.1).
 268
 269 -----------------------------------------------------------------------------
 270
 271 Credits
 272
 273         This HOWTO relied heavily on the documentation that Renzo wrote for
 274 vde-1.4.1.
 275         Thanks to Mulyadi Santosa for helping with the first revision of
 276 this document, and to Renzo for his input. (P.S. Will add info for ale4net
 277 and slirpvde as soon as I figure out how to use it ;)
 278