vde-2/README

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