SAMI Probe 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 setup and configure a SAMI probe or samid/scheduled. You can learn more about SAMI and the other components in the SAMI Overview document.

The samid is a server daemon that runs on a SAMI probe and listens for resource (currently, only measurement) requests. A scheduled is samid’s partner daemon. It also runs on a SAMI probe. Scheduled’s sole responsibility is to execute measurement requests (previously vetted by the samid) at their specific requested time.

Prior to running a SAMI probe you must install the software. For instructions, please see the document SAMI Installation Guide.

Please note that in this document, INSTALL_DIRECTORY represents the SAMI root directory.

Configuring the SAMI Probe

To configure a SAMI probe, you must have a valid private key, an X.509 certificate, and specify a CPOC to use.

Private key

To be detected automatically, the private key generated during installation must be named either ‘id_rsa’ or ‘id_rsa-HOSTNAME’, and must be installed inINSTALL_DIRECTORY/keys. Otherwise, you will need to specify the key filename and location explicitly. This can be done either by editing the configuration file or via a command line argument.

 key = my_key_dir/my_key_name 

 samid -K my_key_dir/my_key_name 

X.509 certificate

Similarly, the samid’s X.509 certificate must be named HOSTNAME.pem and must be installed in INSTALL_DIRECTORY/certs to be detected automatically. If not, then you will need to specify the certificate filename and location explicitly. Again, this can be done in two ways, either by editing the configuration file or via a command line argument.

cert = my_cert_dir/my_cert_name 

samid -C my_cert_dir/my_cert_name 

Specifying a CPOC

You must specify the name of the samid’s CPOC. This can be done in three ways: by having the CPOC’s URL in cpoc.url; by editing the configuration file; or by using a command line argument.

CPOC URL

Add an entry for the CPOC’s URL to the file INSTALL_DIRECTORY/etc/cpoc.url, e.g.,:

http://cpoc.psc.edu/ 

Configuration file

Add an entry to the samid’s configuration file (INSTALL_DIRECTORY/etc/samid.conf) that specifies the CPOC’s URL, e.g.,:

cpoc = http://cpoc.psc.edu:13500/ 

Command line argument

Use the command line argument -c CPOC_URL, as in:

samid -c cpoc.psc.edu:13500 

You must use the command line argument each time that samid is started.

Starting the SAMI probe

The samid and scheduled can be started manually:

cd INSTALL_DIRECTORY bin/samid  

The samid will start the scheduled if it is not running.

Or, samid and scheduled can be started via an init.d-like shell scriptINSTALL_DIRECTORY/bin/sami. The script accepts the options start, stop, andrestart, as well as arguments to be passed along to the samid and scheduled. For example:

INSTALL_DIRECTORY/bin/sami start 

The provided init.d script (INSTALL_DIRECTORY/etc/rc.d/sami) can also be called on system startup either by placing the init.d script in the appropriate directory (e.g., /etc/rc.d), or simply calling it from rc.local. As these two options require superuser privileges, we will not cover them in this document.

Upon startup, the samid will download all certificates and measurement tools that the CPOC currently has for the samid’s O/S and release. Updates of the samid, scheduled, master-script, and system invocation wrappers are downloaded by the CPOC at set intervals.

You can check etc/samid.log and etc/scheduled.log to verify that the daemons are running correctly. If they are, you should see tools being being downloaded from the CPOC.

Secondary Command Line arguments

Command line arguments can be used to alter the parameters used with samid/scheduled.

Upon startup, the SAMI probe (samid/scheduled) uses the current working directory as the INSTALL_DIRECTORY (see the SAMI Installation Guide). To run the samid and scheduled from a location other than the current working directory, use the -B option (Base path):

/usr/sami/bin/samid -B /usr/sami /usr/sami/bin/scheduled -B /usr/sami 

To see more or fewer messages in the log file, add “v”s for more verbose or “q”s to make the output more quiet:

INSTALL_DIRECTORY/bin/samid -vv INSTALL_DIRECTORY/bin/scheduled -q 

To force ‘verbose’ logging to go to STDERR, and ‘normal’ logging to the log file:

INSTALL_DIRECTORY/bin/samid -Lstderr:verbose -Lfile:normal 

To have the samid e-mail a user any log messages above a certain level (the levels are: ERROR, REMOTE, WARN, QUIET, NORMAL, VERBOSE), rename the sample report script (INSTALL_DIRECTORY/etc/error-report.samp):

 mv etc/error-report.samp etc/error-report 

Then edit it to included the username, e.g.,:

 USERS="user@system" 

and enable the samid to use it:

INSTALL_DIRECTORY/bin/samid -Lscript=etc/error-report:warn 

A complete list of options for either component is displayed by typing:

bin/samid -H bin/scheduled -H 

Restart Config File

Upon receiving a new version of itself from the CPOC, the samid will attempt to restart itself. Occasionally, some hardware, O/S, and version combinations will require exceedingly long times to relinquish the port that the samid was using. By default, the samid will sleep for 60 seconds prior to attempting to restart itself. If this time is not sufficient for a particular host, you can set a different time out period via the restart-timer config file. Use the following commands:

touch INSTALL_DIRECTORY/etc/restart-timer 

Then add the appropriate amount of seconds that you want the samid to wait:

echo 360 > INSTALL_DIRECTORY/etc/restart-timer