This is a patched version of the uml_switch program from the
UML Project (http://user-mode-linux.sourceforge.net) implementing
libpcap capturing features, developed by Esteban Martn for the VNUML
Project (http://wwww.dit.upm.es/vnuml).

Requeriments to compile
-----------------------

- libpcap-dev >= 0.8

Compilation and installation instructions
-----------------------------------------

- cd to uml_router directory

- use 'make' command. As result, the uml_switch binary file is generated

- put the uml_switch binary in a path suitable for you, for example
  /usr/local/bin

  SUGGESTION: change the name of the uml_switch when moving to its
  definitive pathname, in order not to miss it with the original
  uml_switch from the UML Project. For example

  # mv uml_switch /usr/local/bin/uml_switch4capture

Using it with vnumlparser
-------------------------

Although this patched uml_switch can be used as stand-alone program (well,
we know we have to work on the TODO in next section :) it has been
developed to be used in conjuntion with vnumlparser.pl >= 1.7.0

In this case, you need to install the Pcap Perl module (for example, 
from http://search.cpan.org/~saper/Net-Pcap-0.11/Pcap.pm) and use the
suitable <net> tag attributes (please, see 
http://www.dit.upm.es/vnuml/doc/current/reference/index.html#net for
details).

Note that the pathname where you put the uml_switch need to be specified
in the uml_switch_binary attribute. For example:

<net ... uml_switch_binary="/usr/local/bin/uml_switch4capture" />

Command line interface
----------------------

In the case you want to use this patched uml_switch as stand alone
application, this is its CLI (Command Line Interface):

uml_switch [ -unix control-socket ] [ -hub ] [ -tap tap-device ] [ -f capture] [ -expression exp ] [ -dev capture_dev] [ -simulation_name sim_name net]
or : uml_switch -compat-v0 [ -unix control-socket data-socket ] [ -f capture] [ -expression exp ] [ -dev capture_dev] [ -hub ] [ -simulation_name sim_name net ] [ -tap tap-device ]

New possibilities are : 

   - "-f capture" to set the file where captured traffic will be written. File must not exist, or at least, you have to have write permissions. File will be overwritten, of course.

   - "-expression exp", only can be used with "-f capture" option. "exp" is the filter expression that will be applied. These expressions use the tcpdump syntax.

   - "-dev capture_dev", defines the interface name that can be used for live capture with tools like ethereal, for example. You must be root to use this option.

   - "-simulation_name sim_name net", establishs the simulation name and the net which will be performed using this uml_switch. It is necessary if you want to send messages to uml_switch when it is running.

In addition to uml_switch software, there are two new programs you can use to send messages to an uml_switch running process, umlctl and umlswitchd. In order to do this, you need run uml_switch with the following option :

          "-simulation_name sim_name net".

In this way, umlctl have to be executed like

         "umlctl direct command -sim_name sim_name net",

where sim_name and net specifies the simulation and net where you want to capture traffic.

Possibles commands are:

    - set-capture_file /path/to/file
    - set-capture_dev interface_name
    - start-capture_file
    - start-capture_dev
    - stop-capture_file
    - stop-capture_dev
    - set-capture_filter
    - get-capture_file
    - get-capture_dev
    - get-capture_filter

Note that set-capture_file or set-capture_dev only set the file or the interface name, so in order to start the capture you have to use start-capture_file or start-capture_dev.

Other possibility to send messages to uml_switch is through the umlswitchd program. To use this, umlswitchd have to be running when you execute uml_switch, and you have to run umlctl in this way :

       "umlctl daemon command -sim_name sim_name net"

Commands are the same ones, but you have a new possibility,

       "umlctl daemon show"

to list all the net and simulations running in the host that have been executed with the option -simulation_name.


For bug reports/suggestions/comment please write 
to vnuml at dit dot upm dot es or subscrite to the 
vnuml-users mailing list 
(https://lists.dit.upm.es/mailman/listinfo/vnuml-users)

Enjoy it!

------
Esteban Martn (esteban at cuatrocientoscuatro dot com)
Fermn Galan (galan at dit dot upm dot es)
VNUML Project Development Team
