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.
   6
   7 The overlay network supported by the Makefile may consist of:
   8
   9 - at most one Open vSwitch bridge per sliver;
  10 - at most a pair of tunnels between each pair of slivers.
  11
  12 (Please note that these limitations are due to the simple naming scheme
  13 adopted by the Makefile, and are not limitations of sliver-openvswitch.)
  14
  15 Each bridge is connected to a tap device in the sliver. The tap device
  16 has an IP address chosen by the experimenter. The idea is to connect
  17 all the tap devices through the overlay network made up of Open vSwitch
  18 bridges and tunnels among them.
  19
  20 Please note that the tap device IP address is required for technical
  21 reasons, even if you do not plan to use it.
  22
  23
  24 * Installation
  25
  26 In new slices, sliver-openvswitch comes preinstalled together with
  27 the vsys scripts it needs. All you have to do is ask your administrator
  28 for a private IP subnet for your slice.
  29
  30 On older slices you may have to install sliver-openvswitch on each sliver
  31 and obtain the following tags:
  32
  33 NAME            VALUE
  34 vsys            fd_tuntap
  35 vsys            vif_up
  36 vsys            vif_down
  37 vsys            promisc
  38 vsys_net        (some subnet)
  39
  40
  41 On the experimenter box we need:
  42
  43 - GNU make
  44 - the openssh client
  45 - the host program (usually distributed in bind-tools)
  46 - (optionally) the dot program from the graphviz distribution
  47
  48 Then, we can simply copy the Makefile in a working directory on the
  49 experimenter box
  50
  51 $ mkdir work
  52 $ cp /path/to/Makefile work
  53 $ cd work
  54 $ make init
  55
  56 The last command creates some subdirectories that are later used by the Makefile.
  57
  58
  59 * Example usage
  60
  61 Assume we have a PlanetLab slice called 'example_slice' which
  62 contains four nodes:
  63
  64 1) onelab7.iet.unipi.it
  65 2) planet2.elte.hu
  66 3) planetlab2.ics.forth.gr
  67 4) planetlab2.urv.cat
  68
  69
  70 Assume we have obtained subnet 10.0.9.0/24 for our slice.  We are
  71 going to build the following overlay network:
  72
  73    10.0.9.1/24   10.0.9.2/24   10.0.9.3/24
  74         1 ----------- 2 ------------ 3
  75                       |
  76                       |
  77                       |
  78                       4
  79                   10.0.9.4/24
  80
  81
  82 In the same directory were we have put the Makefile we create a 'conf.mk'
  83 file containing the following variables:
  84
  85 ----------
  86 SLICE=example_slice
  87 HOST_1=onelab7.iet.unipi.it
  88 IP_1=10.0.9.1/24
  89 HOST_2=planet2.elte.hu
  90 IP_2=10.0.9.2/24
  91 HOST_3=planetlab2.ics.forth.gr
  92 IP_3=10.0.9.3/24
  93 HOST_4=planetlab2.urv.cat
  94 IP_4=10.0.9.4/24
  95
  96 LINKS :=
  97 LINKS += 1-2
  98 LINKS += 2-3
  99 LINKS += 2-4
 100 ----------
 101
 102 NOTE. In this example we have chosen to use numbers (1,2,3,4) as ids
 103 for nodes, you can use any other name that is convenient for you.
 104 See the example files in this directory for an example of this.
 105
 106
 107 Then, we can just type:
 108
 109 $ make -j
 110
 111 Assuming everything has been setup correctly, this command Will start
 112 the Open vSwitch servers, create the bridges and setup the tunnels. We
 113 can test that network is up by logging into a node and pinging some
 114 other node using the private subnet addresses:
 115
 116 $ ssh -l example_slice onelab7.iet.unipi.it ping 10.0.9.4
 117
 118 Links can be destroyed and created dynamically. Assume we now want the
 119 the topology to match the following one:
 120
 121    10.0.9.1/24   10.0.9.2/24
 122         1 ----------- 2
 123                       |
 124                       |
 125                       |
 126                       4 ----------- 3
 127                   10.0.9.4/24  10.0.9.3/24
 128
 129
 130 We can issue the following commands:
 131
 132 $ make -j U/2-3      # unlink nodes 2 and 3
 133 $ make -j L/4-3      # link nodes 4 and 3
 134
 135 The current state of the links is represented as a set of files in the 'L'
 136 directory.  If dot is installed, we can obtain a graphical representation
 137 of the topology by typing:
 138
 139 $ make graph.ps
 140
 141 The current state of the nodes and links can be obtained by typing
 142
 143 $ make snapshot > snapshot.mk
 144
 145 The snapshot.mk file follows the same format as conf.mk and can be used
 146 to recreate the topology at a later time:
 147
 148 $ make CONF=snapshot.mk
 149
 150 * Command reference
 151
 152 All targets can be issued with the '-j' flag to (greatly) speed up operations (*)
 153 It may also be useful to use the '-k' flag, so that errors on some nodes do not
 154 stop the setup on the other nodes.
 155
 156
 157 all:            do wathever is needed to setup all the links in the 'links' file.
 158
 159 clean:          tear down all existing links
 160
 161 L/N1-N2:        setup a link between nodes $HOST_N1 and $HOST_N2
 162
 163 U/N1-N2:        tear down the link (if it exists) between nodes $HOST_N1
 164                 and $HOST_N2
 165
 166 del-bridge.N:   delete the bridge running on node $HOST_N (this also tears down
 167                 all links that have an endpoint in $HOST_N)
 168
 169 graph.ps        create a postscript file containing a (simple) graphical
 170                 representation of the current topology
 171
 172 ====================================================
 173
 174 (*) To get the greatest speedup from make -j you should also enable
 175 connection reuse in your ssh setup, e.g., by having the following lines
 176 in your .ssh/config:
 177 host *
 178         ControlMaster auto
 179         ControlPath ~/.ssh/ssh_mux_%h_%p_%r
 180         ControlPersist 4h
 181
 182 Please note, however, that maximum concurrent per-node reuse is usually
 183 set to something low (typically 10), and this is a problem if some node
 184 in your topology has many links. In this case you should raise that limit
 185 on the slivers, or limit makefile concurrency (e.g., by using make -j10).