+++ /dev/null
-========================================================================
-3G-UMTS-TOOLS
-========================================================================
-
-These tools give to users of a sliver the possibility to control a PPP
-connection over a 3G umts/hsdpa interface and set the kernel routes
-required to use it. Exploiting vsys features, they make use of wvdial,
-gcom and iproute2 wich require super user privileges. The scenario is
-that of a Onelab node with a primary, usually ethernet, interface, and
-a secondary 3G umts/hsdpa interface, where the primary interface is
-meant to be used for control data (i.e. to log into the sliver), and
-the 3G umts/hsdpa interface for the experiments.
-
-The users of the selected slivers can start, stop and see the status
-of the PPP connection over the 3G umts/hsdpa interface; they can also
-specify for which destinations they want their packets (packets
-generated inside their sliver) to be routed through the 3G umts/hsdpa
-interface. Please note that another method to have packets routed in
-the 3G umts/hsdpa interface is to force the application to bind to
-thse IP of that interface, as afterwards explained.
-
-========================================================================
-INSTALLATION
-
-Install the planetlab-umts-tools-VERSION.rpm package into the slice
-environment.
-
-========================================================================
-USAGE
-
-To start the PPP connection type as root in the guest system:
-
- umts start
-
-The output will show the ip address of the PPP connection just established,
-if everything went well.
-
-To stop the PPP connection:
-
- umts stop
-
-The output will show the connection time, if the PPP connection is
-successfully stopped.
-
-To check whether the PPP connection is still on (if the PPP link is still
-alive):
-
- umts status
-
-The answer is either Connected or Disconnected.
-
-To add a destination (packets directed towards this destination will go out
-of the node through the ppp interface):
-
- umts add ip_destination
-
-The answer is OK if everything went well.
-
-To del a destination previously added:
-
- umts del ip_destination
-
-The answer is OK if everything went well.
-
-
-========================================================================
-WHAT THE BACKEND DOES
-
-When the user issues the command "umts start" a program that runs in
-the host context (the back-end) executes the programs gcom and wvdial,
-and verifies if the 3G umts/hsdpa connection was properly established
-and a ppp device was created. In such a case, it adds a rule into the
-routing table in order to let all the packets having source IP address
-equal to that of the 3G umts/hsdpa interface to be routed through such
-interface. In this way, it is possible to use the 3G umts/hsdpa
-connection by forcing the required application to bind to the IP of
-the related interface (e.g. with wget it is possible to use the
---bind-address <ip> option). After the creation of the rule, the
-back-end program communicates to the front-end one that everything has
-gone all right. The user in the slice will then see an “OK” on the
-standard output. From this moment until the disconnection (see below),
-upon issuing the “ifconfig” command it should be possible to see a
-network interface called ppp0.
-
-When the user issues the command "umts add <ip_address/netmask>" the
-backend creates a route towards the <ip_address/netmask> specifying
-the 3g umts/hsdpa interface as a gateway, so that all packets directed
-toward such destinations will be routed through the 3g umts/hsdpa
-interface. The related "umts del" command, deletes the route
-previously added.
-
-"umts stop" makes the backend stop the connection (a SIGTERM signal is
-sent to wvdial).
-
-"umts status" makes the backend chech the status of the ppp
-connection. The connection is considered alive if wvdial is still
-running.
-
-
-========================================================================
-VSYS AND PLANETLAB-UMTS-TOOLS
-
-The communication between the sliver and the host environment of the
-node is made possible by vsys, a software created by PlanetLab
-developer Sapan Bhatia to allow PlanetLab users execute privileged
-commands in a normal sliver. The mechanism is meant to be safe, as it
-allows only a predetermined set of executable files to be invoked in
-the unprivileged context. vsys services are executable files placed in
-a specific directory in the root context. Slices that subscribe to
-these services are assigned a pair of FIFO pipes for each available
-service. These pipes respectively become the input and output channels
-to communicate with the service. By developing custom back-end
-(i.e. programs located and running in the root context) and front-end
-(i.e. programs located and running in the slice context) the developer
-provides normal users a set of hooks to execute privileged operations.
-
-We developed a pair of C programs acting as a vsys front-end (“umts”)
-and back-end (“umts_backend”). These two programs communicate by means
-of the pipes created by vsys. “umts” runs in the guest environment and
-writes in one of these two pipes; “umts_backend”, in its turn, reads
-the “umts” command and performs the requested operation, by executing
-a bash script (“umts.sh”).
-
-
-========================================================================
-AUTHORS:
-
-Giovanni Di Stasi <giovanni.distasi@unina.it>
-Alessio Botta <a.botta@unina.it>
-Roberto Canonico <roberto.canonico@unina.it>
-
-Comics Research Group
-University of Naples Federico II
-Naples, Italy
git://git.onelab.eu / planetlab-umts-tools.git / blobdiff