vde/README

   1 VDE : Virtual Distributed Ethernet.
   2
   3 (c) 2003/2004/2005 Renzo Davoli
   4 Based on uml-router Copyright 2002 Yon Uriarte and Jeff Dike
   5 qemu-vde-HOWTO is (c) by Jim Brown
   6
   7 Notice: Virtual Distributed Ethernet is not related in any way with
   8 www.vde.com ("Verband der Elektrotechnik, Elektronik und Informationstechnik"
   9 i.e. the German "Association for Electrical, Electronic & Information
  10 Technologies").
  11
  12 Components of the VDE architecture:
  13 - VDE switches: virtual counterpart of ethernet switches.
  14 - VDE cables: virtual counterpart of a crossed-cable used to connect two switches.
  15
  16 Using VDE:
  17 - All units connected to the VDE see each other as they were on a real ethernet.
  18 - A real Linux box can be connected to the VDE using a tap interface (TUNTAP)
  19   (packets can be further routed using standard linux methods).
  20 - It is possible to join two VDE switches -- also running on different
  21   real conputers -- using virtual VDE cables
  22 - UML (user-mode-linux) virtual machines can be connected to the VDE
  23 - MPS (MIPS emulated machines (c) Morsiani/Davoli) can be connected
  24 to the virtual VDE.
  25
  26 Examples of VDE uses:
  27 - With VDE it is possible to create a virtual network of UML machines running
  28 on several real computer
  29 - VDE can be used to create tunnels (even crossing masquerated networks)
  30 - VDE can provide mobility support. Changing a VDE cable with another does not
  31 affect the communications in place. The new VDE cable can use a completely
  32 different path on the real net. VDE supports also multiple concurrent VDE cables
  33 between a pair of VDE-switches during the hand-off. This eliminates when possible
  34 hich-ups of communications due to hand-offs.
  35
  36 HOWTO and command syntax:
  37
  38 vde-switch [ -unix control-socket ] [ -tap tuntap-device ] [ -hub ] [-daemon]
  39 This command creates a VDE switch.
  40 -unix control-socket
  41         The control socket is the socket used for local processes to create a new
  42         connection. The default value is /tmp/vde.ctl.
  43         User-mode-linux default value is /tmp/uml.ctl, so if you want to use vde
  44         with UML you can: (1) use "-unix /tmp/uml.ctl" for vde-switch (2) use
  45         "eth0=daemon,,/tmp/vde.ctl" for UML
  46 -tap tuntap-device
  47         the vde-switch is connected to the specified tap interface.
  48         Ususally it is reserved for root as /dev/net/tun is not writable.
  49         (It is dangerous to have /dev/net/tun writable by ordinary users).
  50 -hub
  51         the vde-switch works as a hub (all packets are broadcast on all interfaces.
  52 -daemon
  53         the switch works as a daemon: it runs in background, it uses syslog
  54         for error management.
  55
  56 vde-plug [-g num] [socketname]
  57 A vde-cable is composed by two vde-plug and a "cable". A vde-plug connects its
  58 standard input and output to a switch.
  59 socketname is the control-socket of the switch the plug must be connected to
  60 (default value /tmp/vde.ctl).
  61 -g num (num > 0, num < 256) is a group number. Cables without a group number are
  62 independent cables, cables with the same group number represent several path
  63 for the same destination. Packet reaching a switch on a cable are never forwarded
  64 on another cable of the same group.
  65
  66 dpipe cmd1 [arg1] = cmd2 [arg2]
  67 it is the double pipe command (it is here just becouse it is not provided by
  68 shells).
  69 cmd1 and cmd2 are executed, the stdout of cmd1 if pipe connected to the stdin of
  70 cmd2 and viceversa. (the symbol = is intended as a pair of communication pipes
  71 between the two processes.
  72
  73 HOW TO:
  74 - (1) SETUP A DAEMON:
  75 (as root)
  76 # vde_switch -tap tap0 -daemon
  77 # ifconfig tap0 192.168.0.254
  78 # chmod 777 /tmp/vde.ctl
  79
  80 if you want to have routing to the Internet you can use standard routing
  81 commands on the host machine e.g.:
  82 # echo "1" > /proc/sys/net/ipv4/ip_forward
  83 # iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE
  84
  85 for ipv6
  86 # echo "1" > /proc/sys/net/ipv6/conf/eth0/forwarding
  87 # radvd
  88
  89 radvd must be configured to broadcast the correct prefix for the tap0 subnet
  90
  91 ----- example of /etc/radvd.conf file
  92 interface tap0
  93 {
  94    AdvSendAdvert on;
  95    MaxRtrAdvInterval 120;
  96 #put here your prefix.
  97    prefix 1111:2222:3333:4444::/64
  98    {
  99            AdvOnLink on;
 100            AdvAutonomous on;
 101            AdvRouterAddr on;
 102
 103    };
 104 };
 105 ------ end of example
 106
 107 - (2) SETUP A SECOND DAEMON
 108 (no need for root access)
 109
 110 % vde_switch /tmp/my.ctl
 111
 112 (add - daemon if you want to run it in background)
 113
 114 - (3) CONNECT TWO LOCAL SWITCHES TOGETHER
 115
 116 % dpipe vde_plug = vde_plug /tmp/my.ctl
 117 (or
 118 % dpipe vde_plug /tmp/my.ctl = vde_plug
 119 )
 120
 121 connects the vde_switch with ctl socket /tmp/vde.ctl with the other using
 122 /tmp/my.ctl.
 123
 124 - (3) CONNECT TWO REMOTE SWITCHES TOGETHER
 125
 126 You need a tool to interconnect stdin stdout of two remote processes.
 127 e.g.
 128
 129 % dpipe vde_plug /tmp/my.ctl = ssh remote_machine vde_plug
 130
 131 connects the vde_switch with ctl socket /tmp/vde.ctl on the remote_machine
 132 with the local switch using /tmp/my.ctl.
 133
 134 It is possible to use other tools in place of ssh like netcat.
 135 In this latter case the communication is not secure.
 136
 137 - (4) CREATION OF TUNNELS.
 138 (it needs kernel support for policy routing)
 139
 140 Setup two daemon as described in (1).
 141 In this example 192.168.0.1 is the tap0 address on the server side.
 142 Route the traffic to the Internet on the tunnel server side.
 143
 144 On the tunnel client side:
 145         - in the example 100.200.201.202 is the IP address on eth0
 146         and 100.200.201.254 is the default gateway.
 147         - create a specific rule for the eth0 routing
 148                 ip rule add from 100.200.201.202 table eth0-table
 149         (please note that eth0-table must be listed in /etc/iproute2/rt_tables)
 150                 ip route del default via 100.200.201.254
 151                 ip route add default via 100.200.201.254 table eth0-table
 152         the previous default route will be the def. route just for the
 153         packets originated with the eth0 inteface address.
 154         - connect the two vde-switch together:
 155                 dpipe vde-plug = ssh -b 100.200.201.202 server-machine vde-plug
 156         - setup an appropriate IP address for tap0 interface (or get it by dhcp
 157                 if set up on server side). (e.g. 192.168.0.10)
 158         - use tap0 as the default interface:
 159                 ip route add default via 192.168.0.1
 160
 161 - (5) SUPPORT FOR MOBILITY
 162
 163 Create a tunnel like in 4 using a group number on the vde-cable:
 164         dpipe vde-plug -g 1 = ssh -b 100.200.201.202 server-machine vde-plug -g 1
 165
 166 Create a second tunnel (say on ppp0 addr. 100.100.101.102 gateway 100.100.101.254)
 167         # ip rule add from 100.100.101.102 table ppp0-table
 168         # ip route add default via 100.100.101.254 table ppp0-table
 169
 170 Connect the a second cable using the same group number:
 171         # dpipe vde-plug -g 1 = ssh -b 100.100.101.102 server-machine vde-plug -g 1
 172 Disconnect the first cable (kill the processes of the first cable)
 173
 174         All the traffic get rerouted on the new vde-cable (thus to another path
 175         on the rel network. Connections in place are unaffected by the change.
 176         Several cables of the same group can be in place during the handoff phase
 177         but note that this ends up in duplicated packets that can slow down
 178         the communication.
 179
 180 Please note also that the vde-switches do not manage (yet) the minimum spanning
 181 tree protocol thus a loop in the topology can lead to inconsistent MAC forward
 182 tables and to network saturation.
 183
 184 Copyright 2003/2004 Renzo Davoli
 185 Acknowlegments:
 186 Thanks to Marco Giordani, Leonardo Macchia for their useful help for debugging.
 187 Imported code by Danny Gasparovsky, Fabrice Ballard.
 188 Code organization, bugfixes, autotool support Mattia Belletti.