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 theINSTALL_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