planetlab/exp-tool/README

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