README.User

   1 ========================================================================
   2 PLANETLAB-UMTS-TOOLS
   3 ========================================================================
   4
   5 These tools give to users of a sliver the possibility to control a PPP
   6 connection over a 3G umts/hsdpa interface and set the kernel routes
   7 required to use it. Exploiting vsys features, they make use of wvdial,
   8 gcom and iproute2 wich require super user privileges. The scenario is
   9 that of a Onelab node with a primary, usually ethernet, interface, and
  10 a secondary 3G umts/hsdpa interface, where the primary interface is
  11 meant to be used for control data (i.e. to log into the sliver), and
  12 the 3G umts/hsdpa interface for the experiments.
  13
  14 The users of the selected slivers can start, stop and see the status
  15 of the PPP connection over the 3G umts/hsdpa interface; they can also
  16 specify for which destinations they want their packets (packets
  17 generated inside their sliver) to be routed through the 3G umts/hsdpa
  18 interface. Please note that another method to have packets routed in
  19 the 3G umts/hsdpa interface is to force the application to bind to
  20 thse IP of that interface, as afterwards explained.
  21
  22 ========================================================================
  23 INSTALLATION
  24
  25 Install the planetlab-umts-tools-VERSION.rpm package into the slice
  26 environment.
  27
  28 ========================================================================
  29 USAGE
  30
  31 To start the PPP connection type as root in the guest system:
  32
  33   umts start
  34
  35 The output will show the ip address of the PPP connection just established,
  36 if everything went well.
  37
  38 To stop the PPP connection:
  39
  40   umts stop
  41
  42 The output will show the connection time, if the PPP connection is
  43 successfully stopped.
  44
  45 To check whether the PPP connection is still on (if the PPP link is still
  46 alive):
  47
  48   umts status
  49
  50 The answer is either Connected or Disconnected.
  51
  52 To add a destination (packets directed towards this destination will go out
  53 of the node through the ppp interface):
  54
  55   umts add ip_destination
  56
  57 The answer is OK if everything went well.
  58
  59 To del a destination previously added:
  60
  61   umts del ip_destination
  62
  63 The answer is OK if everything went well.
  64
  65
  66 ========================================================================
  67 WHAT THE BACKEND DOES
  68
  69 When the user issues the command "umts start" a program that runs in
  70 the host context (the back-end) executes the programs gcom and wvdial,
  71 and verifies if the 3G umts/hsdpa connection was properly established
  72 and a ppp device was created. In such a case, it adds a rule into the
  73 routing table in order to let all the packets having source IP address
  74 equal to that of the 3G umts/hsdpa interface to be routed through such
  75 interface. In this way, it is possible to use the 3G umts/hsdpa
  76 connection by forcing the required application to bind to the IP of
  77 the related interface (e.g. with wget it is possible to use the
  78 --bind-address <ip> option). After the creation of the rule, the
  79 back-end program communicates to the front-end one that everything has
  80 gone all right. The user in the slice will then see an “OK” on the
  81 standard output. From this moment until the disconnection (see below),
  82 upon issuing the “ifconfig” command it should be possible to see a
  83 network interface called ppp0.
  84
  85 When the user issues the command "umts add <ip_address/netmask>" the
  86 backend creates a route towards the <ip_address/netmask> specifying
  87 the 3g umts/hsdpa interface as a gateway, so that all packets directed
  88 toward such destinations will be routed through the 3g umts/hsdpa
  89 interface. The related "umts del" command, deletes the route
  90 previously added.
  91
  92 "umts stop" makes the backend stop the connection (a SIGTERM signal is
  93 sent to wvdial).
  94
  95 "umts status" makes the backend chech the status of the ppp
  96 connection. The connection is considered alive if wvdial is still
  97 running.
  98
  99
 100 ========================================================================
 101 VSYS AND PLANETLAB-UMTS-TOOLS
 102
 103 The communication between the sliver and the host environment of the
 104 node is made possible by vsys, a software created by PlanetLab
 105 developer Sapan Bhatia to allow PlanetLab users execute privileged
 106 commands in a normal sliver. The mechanism is meant to be safe, as it
 107 allows only a predetermined set of executable files to be invoked in
 108 the unprivileged context. vsys services are executable files placed in
 109 a specific directory in the root context. Slices that subscribe to
 110 these services are assigned a pair of FIFO pipes for each available
 111 service. These pipes respectively become the input and output channels
 112 to communicate with the service. By developing custom back-end
 113 (i.e. programs located and running in the root context) and front-end
 114 (i.e. programs located and running in the slice context) the developer
 115 provides normal users a set of hooks to execute privileged operations.
 116
 117
 118 ========================================================================
 119 AUTHORS:
 120
 121 Giovanni Di Stasi <giovanni.distasi@unina.it>
 122 Alessio Botta <a.botta@unina.it>
 123 Roberto Canonico <roberto.canonico@unina.it>
 124
 125 Comics Research Group
 126 University of Naples Federico II
 127 Naples, Italy