SAMI MC Usage Guide
The Secure and Accountable Measurement Infrastructure (SAMI) is a collection of software tools designed to aid researchers and engineers in managing internet measurements from various vantage points within the internet. SAMI has several different components: the SAMI probe (samid/scheduled); the Configuration Point of Contact (CPOC), or cpocd; the Data Analysis Client (DAC), or dacd; and the Measurement Client (MC). This document describes how to set up and configure an MC and a DAC. You can learn more about SAMI and the other components in the SAMI Overview document.
The MC application runs on a variety of systems, e.g., general workstations, laptops, etc. It communicates with one or more SAMI probes in order to schedule and manage measurements. If necessary, it first contacts the SAMI probes' CPOC(s) to request resource policies (Capability Certificates). These Capability Certificates are used to authorize the MC when it submits resource requests to the SAMI probes. Included in the measurement request that is sent to the SAMI probes is a URL identifying the DAC daemon (dacd), which specifies where the SAMI probes should direct the results of the measurement.
If you intend to have the MC run until it receives the results, there is no need to run the dacd. The dacd is only necessary if the MC will not be running at the time results are expected to be delivered, e.g., if the measurement request is scheduled far in advance.
Please note that our charter for SAMI was to develop the infrastructure, - i.e., the SAMI probe and CPOC software - and that the MC was developed simply to provide a mechanism for "proof of principal" of the infrastructure. As such, the MC is simply a bare-bones command-line driven tool with the minimum utility necessary to request resources and receive results from the infrastructure. We have always envisioned a more fully featured GUI to replace our MC, but, unfortunately, we can not provide the development effort needed for the task.
Prior to using an MC you must install the software. Please see the SAMI Installation Guide to install an MC.
For security considerations in using any SAMI component, please see the security document.
Please note that in this document, INSTALL_DIRECTORY represents the SAMI root directory.
Configuring the MC
To run an MC, you need a X.509 certificate for the CA; a USER X.509 certificate signed by the CA; and the private and public keys used by the USER certificate. These are generated during installation.
You must specify the key filename and location explicitly. This can be done via the command line argument -K key_file, as in:
mc -K keys/id_rsa-USERNAME
Similarly, you need to specify the USER certificate filename and location explicitly. Again, this can be done via the command line argument -C cert_file, as in:
mc -C certs/USERNAME.pem
Configuring the DAC
If you need to run a dacd, simply call the MC with the -X dac option, as in:
mc -K keys/id_rsa-USERNAME -C certs/USERNAME.pem -X dac
Operating the MC
The MC can perform different functions, depending on the command line arguments presented to it. For example, an MC can request measurements, request a list of SAMI probes from a CPOC, etc. Here is a list of the arguments required to perform various functions.
- To request a list of SAMI probes from the CPOC, use the -X who
option:
mc -c cpocname -X who
The CPOC will return a list of SAMI probes that the MC is allowed to contact, and the MC will store this in the file INSTALL_DIRECTORY/cpocs/cpocname
- To request a single measurement from one of the SAMI probes
administered by cpocname, now that we have a list of them,
use -i to specify the measurement, -s to specify the
SAMI probe, and -a to specify parameters to the measurement
program. Say that foo.psc.edu is one such SAMI probe. Here we
request a traceroute to cnn.com:
mc -i traceroute -s foo.psc.edu -a "-n www.cnn.com"
Assuming that the CPOC granted you a resource policy, foo.psc.edu will return a tar file to you, using the naming convention of HANDLE-INVOCATION_REQUEST-YYYYMMDDHHMMSS-UNIQUE_ID.tar.gz.
This tar file will consist of a directory (with the same name, sans the .tar.gz extension), and at least two files. One file will be called 'info', and will contain meta-data (e.g., time stamps, stdin, stderr, etc.). The second file will be called 'output', and will contain STDOUT from the program's execution. If the program generated any additional data files, they will be in the directory, as well, e.g.:
generic-traceroute-20050304183237-0 generic-traceroute-20050304183237-0/info generic-traceroute-20050304183237-0/output
- To request a single measurement, but at a time in advance,
specifying a 'handle', and to be delivered to a DAC, use the -t,
-h, and -d arguments, e.g.,:
mc -i ping -s foo.psc.edu -a "-c 5 www.cnn.com" -t +3600 -h test1 \ -d dac.somewhere.edu
In one hour from now, ping will be executed on foo.psc.edu, to www.cnn.com, for a count of 5. The resulting tar file will be delivered to dac.somewhere.edu:13500, and will have the name test1-ping-YYYYMMDDHHMMSS-0.
- To request a single measurement, from behind a firewall, use the
-N option, e.g.,:
mc -i traceroute -s foo.psc.edu -a "-n www.cnn.com" -h test2 -N -t +30
Upon completion of the measurement, foo.psc.edu will return the results via the connected socket that the request came from. It is important to realize that if you use the -N option, you must leave the MC running long enough to get your results!
- To request multiple measurements you can
set up a generic test file, which should have a line for each
measurement like:
sami_probe_URL start_time invocation_request arguments_to_request
For example:
foo.psc.edu now traceroute '-n www.cnn.com' bar.psc.edu +30 ping -c 5 www.cnn.com baz.psc.edu 2005:01:05:06:00:00 httperf "--server www.cnn.com --port 80"
Then call the MC with the -G filename option, e.g.,:
mc -h test3 -G measurement.list
- To request any results from a SAMI probe that have not yet been
delivered (perhaps the MC was shutdown prematurely), use the -X
flush argument, e.g.,:
mc -s foo.psc.edu -X flush
Secondary Command Line Arguments
Command line arguments can be used to alter the parameters used with the MC.
Upon startup, the MC uses the current working directory as the INSTALL_DIRECTORY (see the SAMI Installation Guide). To run the MC from a location other than the current working directory, use the -B option (Base path):
/usr/sami/bin/mc -B /usr/sami
To see more or fewer messages, add "v"s for more verbose or "q"s to make the output more quiet:
INSTALL_DIRECTORY/bin/mc -vv INSTALL_DIRECTORY/bin/mc -q
To have 'verbose' logging go to STDERR, but 'normal' logging to the log file:
INSTALL_DIRECTORY/bin/mc -Lstderr:verbose -Lfile:normal
To specify a port other than 13500 for the MC to listen on, use the -p option, e.g.,:
bin/mc -p 13501
You can see a complete list of command line options by typing:
bin/mc -H