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