SAMI CPOC 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 a CPOC. You can learn more about SAMI and the other components in the SAMI Overview document.
The CPOC daemon (cpocd) runs on a general workstation. It serves as the manager of a group of SAMI probes, controlling access to them. This sphere of control is referred to as the CPOC's 'administrative domain'. The cpocd listens for the following requests:
- "BOOTME" requests from SAMI probes assigned to the CPOC's administrative domain, which result in the CPOC downloading all software updates and tools that the CPOC has for the SAMI probe's O/S and release.
- "RESOURCE_POLICY" requests from researchers running an MC, which result in the CPOC downloading a "Capability Certificate". This Capability Certificate describes the constraints on the researcher's access to the resources on the SAMI probe.
- other secondary messages, e.g., a request from the MC for a list of all SAMI probes within the CPOC's domain.
Periodically, cpocd also checks on the status of the SAMI probes within the CPOC's administrative domain.
Prior to running a CPOC you must install the software. For instructions, please see the SAMI installation document.
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 and SRC_DIRECTORY represents the directory where the SAMI source was extracted from the tar file, typically sami-x.y.src/.
To be detected automatically, the private key that was generated during the installation phase must be named either 'id_rsa' or 'id_rsa-HOSTNAME', and must be installed in INSTALL_DIRECTORY/keys. Otherwise, you will need to specify the key filename and location explicitly via the command line argument -K key_file, as in:
INSTALL_DIRECTORY/bin/cpocd -K my_key_dir/my_key_name
Similarly, the CPOC's X.509 certificate must be named HOSTNAME.pem and installed in INSTALL_DIRECTORY/certs. Otherwise, you will need to specify the certificate filename and location explicitly, via the command line argument -C cert_file, as in:
INSTALL_DIRECTORY/bin/cpocd -C my_cert_dir/my_cert_name
SAMI uses Akenti for authorization. Akenti controls resource access by building a hierarchy of Akenti 'Stakeholder' certificates. These Stakeholder certificates comprise Policy, Attribute, and Use Condition certificates that together describe the policy and constraints for resources. It is this 'resource tree' that must be built on the CPOC.
Please note that although we will describe the SAMI-specific aspects of the Akenti resource tree, it is out of the scope of this document to describe the process of building the resource tree, as it is built using Akenti tools. Please see the Akenti documentation for more information.
SAMI treats the actual (measurement) tools on the SAMI probes as the resources. Hence, the root level of the SAMI resource tree on the CPOC is called 'tools'. Any tool requiring more specific policy requires a subdirectory (or sub-tree) under 'tools', and the appropriate Policy and Use Condition certificates installed. To allow users to transparently request resources by the subdirectory name, e.g., 'traceroute', as opposed to 'tools/traceroute', an Akenti resource map file should be installed (there is a sample one in INSTALL_DIRECTORY/akenti/conf).
Moreover, because the resource map file allows a hierarchy of arbitrary length, it is convenient to add a level of abstraction for tools that require similar policies. Hence, in the global SAMI infrastructure's CPOC, under the root 'tools' directory, subdirectories (sub-trees) of 'policed', 'audited', and 'unaudited' were added. Tools were classified under these three 'sub-trees': if the tool used a packet filter proxy, then they were placed under 'policed' in the resource map file; if you could determine the amount of traffic a tool would produce by its command line arguments, then that tool would be mapped to 'audited'; and if the tool was non-deterministic in the amount of traffic it generated, and didn't use a packet filter proxy, then it was mapped to 'unaudited'. For example, here is a sample resource map file from the global CPOC:
# $Id: cpoc-usage.txt,v 1.1 2005/03/10 19:06:01 akadams Exp $ ping tools/audited/ping traceroute tools/unaudited/traceroute zing tools/policed/zing httperf tools/unaudited/httperf iperf tools/unaudited/iperf
Since Use Conditions can be applied with a scope that includes all sub directories, unless a more specific policy is required for a tool, you only need to specify the Use Condition policy at the audited/unaudited/policed sub-tree level. And if a Use Condition should exist across all tools, it only needs to be specified at the root level.
Akenti does require that to assign a Use Condition to a sub-tree, e.g., 'audited', a Policy certificate needs to be generated for that sub-tree.
Currently, SAMI supports the following Use Condition certificate attributes values:
- used to limit the amount of disk space for a group. Note, the check is done prior to launching a request.
- the amount of time that the request is allowed to run. If the PID of the request still exists after lifetime seconds, it will be terminated.
The third Akenti certificate type that SAMI uses in the resource tree are Attribute certificates. Currently, SAMI supports the following Attribute certificate attribute values:
- users can be assigned to groups, and different Use Condition constraints can be applied for each group.
A sample Akenti.conf file is in INSTALL_DIRECTORY/akenti/conf. It should be reviewed, changed if necessary, and re-installed asINSTALL_DIRECTORY/akenti/conf/Akenti.conf
Note that the ServerCertFile and ServerKeyFile must be set to the cpocd's X.509 certificate and private key, as that certificate is used by SAMI probes to verify the Capability certificate presented by users.
Synchronizing the SAMI components, measurement tools, and wrapper scripts across many remote SAMI probes can be a daunting task for a CPOC administrator. To simplify this synchronization, the cpocd uses a directory hierarchy of binaries and scripts, classified by O/S and release. To utilize this feature, create a top-leveltools directory:
Then create a subdirectory for each O/S and release that you need unique binaries for. The name of the directory should be the O/S name followed by a hyphen and the O/S release. (This information can be determined on a unix system with the commands uname and uname -r, respectively.)
cd INSTALL_DIRECTORY/tools mkdir NetBSD-1.6.2 mkdir FreeBSD-4.10-RELEASE
Populate the directories with SAMI component binaries compiled for the appropriate system:
cd INSTALL_DIRECTORY/tools/FreeBSD-4.10-RELEASE cp /tmp/FreeBSD-4.10-RELEASE/sami/src/samid/samid .
Register the version number of the binary by adding its value to the config file for the appropriate SAMI component. For example, to register version 1.0.1 of the samid for FreeBSD 4.10:
cd INSTALL_DIRECTORY/tools/FreeBSD-4.10-RELEASE echo 1.0.1 > samid.cfg
Populate the directories with measurement tool binaries and their associated wrapper scripts compiled for the appropriate system:
cd INSTALL_DIRECTORY/tools/FreeBSD-4.10-RELEASE cp /tmp/httperf-0.6/src/obj/FreeBSD-4.10-RELEASE/httperf . cp SRC_DIRECTORY/tools/httperf-script .
To register the version number of the binary, e.g., 0.6, add the value to the tool's config file:
cd INSTALL_DIRECTORY/tools/FreeBSD-4.10-RELEASE echo 0.6 > httperf.cfg
The version number of the wrapper scripts, e.g. 1.0, must also be added to the script's config file:
cd INSTALL_DIRECTORY/tools/FreeBSD-4.10-RELEASE echo 1.0 > httperf-script.cfg
If versions of an O/S are similar enough to run the same executables, you can link the new release to a pre-existing one, e.g.,:
cd INSTALL_DIRECTORY/tools ln -s NetBSD-1.6.2 NetBSD-1.6.1
The cpocd records a SAMI probe's O/S and release when the SAMI probe starts. If the appropriate directory hierarchy exists, and the component binaries, tools, and wrapper scripts exist in that directory hierarchy, the cpocd can push those components, tools, or scripts out to the SAMI probe as needed.
Since the CPOC's X.509 certificate is used by all SAMI probes within the CPOC's administrative domain to verify all Capability certificates received, the private keyshould contain a passphrase. Thus, the cpocd will, under most circumstances, need to be started manually:
cd INSTALL_DIRECTORY bin/cpocd
A sample init.d script is provided. However, it simply sends e-mail requesting that the administrator of the system manually restart the cpocd.
Command line arguments can be used to alter the parameters used with cpocd.
Upon startup, the CPOC (cpocd) uses the current working directory as theINSTALL_DIRECTORY (see the SAMI Installation Guide). To run the cpocd from a location other than the current working directory, use the -B option (Base path):
/usr/sami/bin/cpocd -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/cpocd -vv INSTALL_DIRECTORY/bin/cpocd -q
To force 'verbose' logging to go to STDERR, and 'normal' logging to the log file:
INSTALL_DIRECTORY/bin/cpocd -Lstderr:verbose -Lfile:normal
To have the cpocd 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 include the username, e.g.,:
And then enable the cpocd to use it:
To specify a port other than 13500 for the cpocd to listen on, use the '-p' option:
bin/cpocd -p 13501
You can see a complete list of command line options by typing:
A 'status check' will be initiated by the cpocd at the time specified in SRC_DIRECTORY/src/common/cpocd_util.cc:
SAMI_PROBES_REPORT_HOUR 4 SAMI_PROBES_REPORT_MIN 15 // run at 4:15AM
The cpcod will check the versions of the SAMI components for all of its SAMI probes. The results of this check will be handed to the scriptINSTALL_DIRECTORY/etc/status-report. To specify the recipients of the report, edit it to include their usernames:
If it is determined that any SAMI probes are using out-of-date components, the cpocd will immediately push the new components out to that SAMI probe.
To request that all SAMI probes in the CPOC's administrative domain initiate a "BOOTME" request, which will result in an automatic download of CA certificates, and a download of measurement tool and wrapper scripts if they are out-of-date, type:
kill -HUP `cat INSTALL_DIRECTORY/etc/cpocd.pid`