planetlab/exp-tool/README

   1 * Introduction
   2
   3 The Makefile contained in this directory can be used by an experimenter
   4 to dynamically create an overlay network in a PlanetLab slice, using the
   5 sliver-openvswitch distribution. At present, the Makefile only supports
   6 the creation of the basic topology (nodes and links). All the additional
   7 configuration of the bridges/switches (in particular, connecting the
   8 switches to OpenFlow controllers or enabling the STP) has to be done
   9 using the tools available in the Open vSwitch distribution. This may
  10 change in the future.
  11
  12 The overlay network supported by the Makefile may consist of:
  13
  14 - at most one Open vSwitch bridge per sliver;
  15 - at most a pair of tunnels between each pair of slivers.
  16
  17 (Please note that these limitations are due to the simple naming scheme
  18 adopted by the Makefile, and are not limitations of sliver-openvswitch.)
  19
  20 Each bridge is connected to a tap device in the sliver. The tap device
  21 has an IP address chosen by the experimenter. The idea is to connect
  22 all the tap devices through the overlay network made up of Open vSwitch
  23 bridges and tunnels among them.
  24
  25
  26 * Installation
  27
  28 On each sliver we need to install sliver-openvswitch and obtain the
  29 following tags:
  30
  31 NAME            VALUE
  32 vsys            fd_tuntap
  33 vsys            vif_up
  34 vsys            vif_down
  35 vsys_net        (some subnet)
  36
  37
  38 On the experimenter box we need:
  39
  40 - GNU make
  41 - the openssh client
  42 - the host program (usually distributed in bind-tools)
  43 - (optionally) the dot program from the graphviz distribution
  44
  45 Then, we can simply copy the Makefile in a working directory on the
  46 experimenter box. The directory must also contain subdirectories 'L'
  47 and 'cache':
  48
  49 $ mkdir work
  50 $ cp /path/to/Makefile work
  51 $ cd work
  52 $ mkdir -p L cache
  53
  54
  55 * Example usage
  56
  57 Assume we have a PlanetLab slice called 'myslice' which
  58 contains four nodes:
  59
  60 1) onelab7.iet.unipi.it
  61 2) planet2.elte.hu
  62 3) planetlab2.ics.forth.gr
  63 4) planetlab2.urv.cat
  64
  65
  66 Assume we have reserverd subnet 10.0.9.0/24 using vsys_net.  We are
  67 goint to build the following overlay network:
  68
  69    10.0.9.1/24   10.0.9.2/24   10.0.9.3/24
  70         1 ----------- 2 ------------ 3
  71                       |
  72                       |
  73                       |
  74                       4
  75                   10.0.9.4/24
  76
  77
  78 In the same directory were we have put the Makefile we create a 'conf.mk'
  79 file containing the following variables:
  80
  81 SLICE=myslice
  82 HOST_1=onelab7.iet.unipi.it
  83 IP_1=10.0.9.1/24
  84 HOST_2=planet2.elte.hu
  85 IP_2=10.0.9.2/24
  86 HOST_3=planetlab2.ics.forth.gr
  87 IP_3=10.0.9.3/24
  88 HOST_4=planetlab2.urv.cat
  89 IP_4=10.0.9.4/24
  90
  91 And a 'links' file containing the following lines:
  92
  93 1-2
  94 2-3
  95 2-4
  96
  97 Then, we can just type:
  98
  99 $ make -j
 100
 101 Assuming everything has been setup correctly, this command Will start
 102 the Open vSwitch servers, create the bridges and setup the tunnels. We
 103 can test that network is up by logging into a node and pinging some
 104 other node using the private subnet addresses:
 105
 106 $ source conf.mk
 107 $ ssh -l $SLICE $HOST_1 ping 10.0.9.4
 108
 109 Links can be destroyed and created dynamically. Assume we now want the
 110 the topology to match the following one:
 111
 112    10.0.9.1/24   10.0.9.2/24
 113         1 ----------- 2
 114                       |
 115                       |
 116                       |
 117                       4 ----------- 3
 118                   10.0.9.4/24  10.0.9.3/24
 119
 120
 121 We can issue the following commands:
 122
 123 $ make -j U/2-3      # unlink nodes 2 and 3
 124 $ make -j L/4-3      # link nodes 4 and 3
 125
 126 The current state of the links is represented as a set of files in the 'L'
 127 directory.  If dot is installed, we can obtain a graphical representation
 128 of the topology by typing:
 129
 130 $ make graph.ps
 131
 132 Or we can save the current state in the 'links' file (so that we can
 133 recreate it later):
 134
 135 $ ls L > links
 136
 137
 138 * Command reference
 139
 140 All targets can be issued with the '-j' flag to (greatly) speed up operations.
 141 It may also be useful to use the '-k' flag, so that errors on some nodes do not
 142 stop the setup on the other nodes.
 143
 144
 145 all:            do wathever is needed to setup all the links in the 'links' file.
 146
 147 clean:          tear down all existing links
 148
 149 L/N1-N2:        setup a link between nodes HOST_N1 and HOST_N2
 150
 151 U/N1-N2:        tear down the link (if it exists) between nodes HOST_N1
 152                 and HOST_N2
 153
 154 del-bridge.N:   delete the bridge running on node HOST_N (this also tears down
 155                 all links that have an endpoint in N)
 156
 157 graph.ps        create a postscript file containing a (simple) graphical
 158                 representation
 159                 of the current topology