README.User

   1 ========================================================================
   2 3G-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 Copy the file umts in the sliver filesystem (in a directory contained
  26 in the PATH variable).
  27
  28
  29 ========================================================================
  30 USAGE
  31
  32 To start the PPP connection type as root in the guest system:
  33
  34   umts start
  35
  36 The output will show the ip address of the PPP connection just established,
  37 if everything went well.
  38
  39 To stop the PPP connection:
  40
  41   umts stop
  42
  43 The output will show the connection time, if the PPP connection is
  44 successfully stopped.
  45
  46 To check whether the PPP connection is still on (if the PPP link is still
  47 alive):
  48
  49   umts status
  50
  51 The answer is either Connected or Disconnected.
  52
  53 To add a destination (packets directed towards this destination will go out
  54 of the node through the ppp interface):
  55
  56   umts add network_address/netmask
  57
  58 The answer is OK if everything went well.
  59
  60 To del a destination previously added:
  61
  62   umts del network_address/netmask
  63
  64 The answer is OK if everything went well.
  65
  66
  67 ========================================================================
  68 WHAT THE BACKEND DOES
  69
  70 When the user issues the command "umts start" a program that runs in
  71 the host context (the back-end) executes the programs gcom and wvdial,
  72 and verifies if the 3G umts/hsdpa connection was properly established
  73 and a ppp device was created. In such a case, it adds a rule into the
  74 routing table in order to let all the packets having source IP address
  75 equal to that of the 3G umts/hsdpa interface to be routed through such
  76 interface. In this way, it is possible to use the 3G umts/hsdpa
  77 connection by forcing the required application to bind to the IP of
  78 the related interface (e.g. with wget it is possible to use the
  79 --bind-address <ip> option). After the creation of the rule, the
  80 back-end program communicates to the front-end one that everything has
  81 gone all right. The user in the slice will then see an “OK” on the
  82 standard output. From this moment until the disconnection (see below),
  83 upon issuing the “ifconfig” command it should be possible to see a
  84 network interface called ppp0.
  85
  86 When the user issues the command "umts add <ip_address/netmask>" the
  87 backend creates a route towards the <ip_address/netmask> specifying
  88 the 3g umts/hsdpa interface as a gateway, so that all packets directed
  89 toward such destinations will be routed through the 3g umts/hsdpa
  90 interface. The related "umts del" command, deletes the route
  91 previously added.
  92
  93 "umts stop" makes the backend stop the connection (a SIGTERM signal is
  94 sent to wvdial).
  95
  96 "umts status" makes the backend chech the status of the ppp
  97 connection. The connection is considered alive if wvdial is still
  98 running.
  99
 100
 101 ========================================================================
 102 VSYS AND PLANETLAB-UMTS-TOOLS
 103
 104 The communication between the sliver and the host environment of the
 105 node is made possible by vsys, a software created by PlanetLab
 106 developer Sapan Bhatia to allow PlanetLab users execute privileged
 107 commands in a normal sliver. The mechanism is meant to be safe, as it
 108 allows only a predetermined set of executable files to be invoked in
 109 the unprivileged context. vsys services are executable files placed in
 110 a specific directory in the root context. Slices that subscribe to
 111 these services are assigned a pair of FIFO pipes for each available
 112 service. These pipes respectively become the input and output channels
 113 to communicate with the service. By developing custom back-end
 114 (i.e. programs located and running in the root context) and front-end
 115 (i.e. programs located and running in the slice context) the developer
 116 provides normal users a set of hooks to execute privileged operations.
 117
 118 We developed a pair of C programs acting as a vsys front-end (“umts”)
 119 and back-end (“umts_backend”). These two programs communicate by means
 120 of the pipes created by vsys. “umts” runs in the guest environment and
 121 writes in one of these two pipes; “umts_backend”, in its turn, reads
 122 the “umts” command and performs the requested operation, by executing
 123 a bash script (“umts.sh”).
 124
 125
 126 ========================================================================
 127 AUTHORS:
 128
 129 Giovanni Di Stasi <giovanni.distasi@unina.it>
 130 Alessio Botta <a.botta@unina.it>
 131 Roberto Canonico <roberto.canonico@unina.it>
 132
 133 Comics Research Group
 134 University of Naples Federico II
 135 Naples, Italy