X-Git-Url: http://git.onelab.eu/?p=planetlab-umts-tools.git;a=blobdiff_plain;f=frontend%2FREADME.User;fp=frontend%2FREADME.User;h=0000000000000000000000000000000000000000;hp=cbbd2a669a80678687ee796abfbc404a15bd4d1b;hb=29a8ad81f201bb3c538057dd174c31c9ae551e78;hpb=46cf404603955fa122ad50cfe9a72b82491f9b4d diff --git a/frontend/README.User b/frontend/README.User deleted file mode 100644 index cbbd2a6..0000000 --- a/frontend/README.User +++ /dev/null @@ -1,134 +0,0 @@ -======================================================================== -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 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 " the -backend creates a route towards the 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 -Alessio Botta -Roberto Canonico - -Comics Research Group -University of Naples Federico II -Naples, Italy