Fedd Commands
These are the various user level programs that the fedd package installs, including fedd itself.
Table of Contents
Fedd
This is the daemon itself, which is either an experiment controller or access controller (or both) depending on its configuration. After the fedd description, we cover the various support scripts included in the distribution, before addressing the command line interface.
fedd.py
The main federation daemon; when this documentation refers to fedd
is is the fedd.py
executable that is running. It can run on any host as any user, provided permissions and keys are correct. Most of fedd
's behavior is controlled by its configuration files and databases, there are a few command line arguments.
- --config=filename
-
Use filename as the configuration file rather than the default
/usr/local/etc/fedd.conf
- --debug
- Produce additional error output
- --logfile=filename
- Redirect log output to filename rather than the default standard output
Command Line
These scripts make up the command line interface to the federation system. They remain the most versatile and powerful way to create and manage federated experiments. Most of these commands communicate with the experiment controller through either a SOAP or XMLRPC interface to carry out their functions.
All these programs will print a summary of their arguments if given the --help argument. Though all accept the --url option, that value is more easily set by setting the FEDD_URL environment variable.
All are installed in /usr/local/bin
by default.
All the command line tools accept the following arguments:
- --cert=filename
-
Certificate from which to derive the user's fedid. By default the contents of
.ssl/fedid.pem
or.ssl/emulab.pem
in the user's home directory is used.fedid.pem
is preferred. - --debug
- Produce additional debugging output.
- --serializeOnly
-
Do not contact the
fedd
, but just print the SOAP or XMLRPC message to the standard output. - --trusted=filename
- Use the certificates in filename as certificate authorities to confirm the server's identity. Optional.
- --url=fedd_url
- Fedd to contact. If this is not given, the contents of the FEDD_URL environment variable is used.
- --transport=[xmlrpc|soap]
- Use the given encoding of the service request.
- --trace
- Print the SOAP exchanges to stderr. Currently only the SOAP transport is supported.
fedd_create.py
This command creates a federated experiment from an experiment description. It does the equivalent of a call to fedd_new.py to make an allocation and then attaches resources and services as described in the description file. On completion it returns the name of the experiment, and if requested using the --experiment_cert parameter, a certificate that grants access to the experiment.
When fedd_create.py
returns, the experiment has not yet fully been created, it is simply in progress. Users can poll the experiment controller by issuing fedd_multistatus.py commands or wait for the experiment to be instantiated using fedd_spewlog.py.
fedd_create.py
takes the following arguments:
- --experiment_cert=filename
- Store the certificate used to access the resulting experiment in filename. This certificate can be used as an input parameter to the terminate and informational commands below, but is an output parameter here.
- --experiment_name=exp_name
-
Suggest exp_name to the
fedd
as a local identifier for the federated experiment. The actual local name chosen will be returned from the command. - --delegate
- Delegate the rights of the user to the experiment fedid created by the experiment controller. This is the default, and only developers or serious power users will want anything else. The --no-delegate option turns it off.
- --file=filename
- File containing the experiment description.
- --gen_cert
- If this is specified, the fedd_create.py code generates the experiment certificate. One can use this if there is any reason to doubt the experiment controller's fedid creation algorithm.
- --map=spec
-
Map a testbed identifier in the experiment description into a URI for its access controller. Format for spec is testbed_id:access_uri. For example, --map=deter:http://localhost:11123 will try to install nodes in the experiment description with a label of "deter" on to the controller at http://localhost:11123 . A node label is usually set with the
tb-set-node-testbed
command in the description. - --master=master_testbed
-
The master testbed. This should correspond to one of the annotations used for testbed names in the experiment. The
fedd
will use its experiment name mapping DB to resolve that name to a testbed. Deprecated in favor of explicit service requests. - --project=export_project
- The local project to export from the master testbed. Deprecated in favor of explicit service requests.
- --service=spec
-
Add the given service to the experiment being created. This parameter may be specified multiple times. Spec has the format:
name:exporter:importer1,importer2:attribute1=value1;attribute2=value2
Names are specified in the discussion of services in the overview.
These lines can also be specified in the experiment description file as comments prefixed with the tag SERVICE:
fedd_ftopo.py
Returns a mapping between the virtual element names in the experiment description and a physical name that can be used to access the resource. Right now all the plug-ins that return such a mapping return a DNS name as the physical name.
fedd_ftopo.py
takes the following parameters in addition to the standard ones:
- --experiment_cert=filename
- The filename must contain a certificate valid for the experiment's fedid. If so it is used to authenticate access to the experiment. A password may be required if one has been added to the private key.
- --experiment_name=name
- The local name of the experiment to query. Only the experiment creator can use this for access.
The output has the format:
element_name:physical_name:status:supported_ops:testbed
The fields are:
- The node name from the experiment layout file
- The local names that the individual testbed has given to the node. These are testbed dependent. If there is more than one name assigned by the testbed, they will be comma-separated.
- The status of the individual node
- Operations allowed on the node
- The testbed name on which the node is instantiated
fedd_image.py
fedd_image.py
creates visualizations of federated experiments at a box and lines level, showing the interconnections between elements. The visualizations can be generated from an active federated experiment, a topdl description, or an ns2 description. fedd-image.py
calls out to graphviz's neato
program to draw the graphs, so it or a compatible program must be available.
Internally, the various representations are converted to topdl and from there into the neato
specification. An active experiment's topdl description must be pulled from the experiment controller it was created on and a local ns2 description must be translated by a fedd into topdl. Topdl descriptions can be drawn without contacting a fedd.
fedd_image.py
takes the following arguments in addition to the standard ones:
- --experiment_cert=filename
- The filename must contain a certificate valid for the experiment's fedid. If so it is used to authenticate access to the experiment. A password may be required if one has been added to the private key.
- --experiment_name=name
- The local name of the experiment to query. Only the experiment creator can use this for access.
- --file=filename
- File containing the experiment description.
- --format=fmt
- The image format to use. Valid choices are jpg, png, svg, and dot. dot is graphviz input.
- --group=attribute
- Group nodes by an attribute attached to them and outline them in the output. This may be given more than once.
- --labels
- Include node names and IP address information in the image. This is the default.
- --no_labels
- Omit node names and IP address information in the image.
- --output=file
- A file to store the image in. If --format is given, otherwise the last three characters of the filename are taken as a --format specification.
- --pixels=pix
- Output an image that is pix pixels, square.
- --program=path
-
A
neato
compatible program to draw the graph. This may be helpful if graphviz is installed in a non-standard place or with a non-standard name.
fedd_info.py
This program provides various information about running (or failed) federated experiments. Many of the types of data it can return are accessible in more user-friendly ways by other commands. It is largely used for debugging.
The data types accessible are:
- id
- The local name and fedid of this experiment. Just the fedid is returned, not a certificate representing it, or its key.
- experimentdescription
- A topdl description of the global virtual topology of this experiment. Portal nodes and other elements that are transparent to the experiment (and potentially unknown to the experiment controller) are omitted.
- log
- The experiment controller log from the experiment's creation or failed creation attempt.
- status
- The experiment status. See below for details.
- vtopo
- vis
- Emulab compatible descriptions of the virtual topology and visualization of the experiment. These are used to debug these compatibility interfaces.
An experiment's status can be one of the following values:
- active
- The experiment has resources allocated to it and has been successfully configured.
- empty
- The experiment exists, but no attempt has been made to attach resources to it.
- failed
- The experiment could not be started. This state allows users to retrieve logs and federant information from failed experiments. Once information is retrieved, this experiment should be terminated.
- starting
- The experiment is having resources allocated and elements configured.
- terminating
- The experiment is being terminated.
fedd_info.py
takes the standard arguments and:
- --experiment_cert=filename
- The filename must contain a certificate valid for the experiment's fedid. If so it is used to authenticate access to the experiment. A password may be required if one has been added to the private key.
- --experiment_name=name
- The local name of the experiment to query. Only the experiment creator can use this for access.
- --data=sel
- Print the data given by sel, which can be any of the values above. The --data argument may be specified multiple times.
fedd_multiinfo.py
fedd_multiinfo.py
is a batch version of fedd_info.py that returns the selected data for all experiments that the caller can access. It takes the standard arguments and a ---data=sel argument that has the same meaning as for fedd_info.py
.
fedd_multistatus.py
fedd_multistatus.py
provides a summary of status information for all experiments that the caller can access. It takes the standard arguments. Output is one line per experiment of the form:
local_name:fedid:status
fedd_new.py
This command creates an experiment but does not attach any resources to it. This function is also carried out by fedd_create.py before it attaches resources to the experiment. For most users that command is more useful. It takes the standard arguments and:
- --experiment_cert=filename
- Store the certificate used to access the resulting experiment in filename. This certificate can be used as an input parameter to the terminate and informational commands below, but is an output parameter here.
- --experiment_name=exp_name
-
Suggest exp_name to the
fedd
as a local identifier for the federated experiment. The actual local name chosen will be returned from the command. - --gen_cert
- If this is specified, the fedd_new.py code generates the experiment certificate. One can use this if there is any reason to doubt the experiment controller's fedid creation algorithm.
fedd_ns2topdl.py
Translates an ns2 experiment description into a topdl one. It takes standard arguments as well as:
- --file=filename
- File containing the ns2 experiment description.
- --output=file
- A file to store the result.
fedd_operation.py
Request that the given operation be carried out on the federated nodes. This is part of the ongoing information and operation interface development, and is currently very rough. The command takes the following arguments:
- --experiment_cert=filename
- The filename must contain a certificate valid for the experiment's fedid. If so it is used to authenticate access to the experiment. A password may be required if one has been added to the private key.
- --experiment_name=name
- The local name of the experiment to query. Only the experiment creator can use this for access.
- --target=localname
- The node to operate on. This may be specified multiple times.
- --operation=op
- The operation to carry out
- --param=name=value
- Parameters to the operation as name/value pairs. May be specified multiple times.
fedd_spewlog.py
This command waits for an experiment to finish being created and prints its status. As the creation log is updated, that log is printed to standard out. The result is a running view of the progress of the experiment's creation until it succeeds or fails. Because it is the experiment controller's log, it is less informative of the process on federants until they succeed or fail.
It takes the standard parameters and:
- --experiment_cert=filename
- The filename must contain a certificate valid for the experiment's fedid. If so it is used to authenticate access to the experiment. A password may be required if one has been added to the private key.
- --experiment_name=name
- The local name of the experiment to query. Only the experiment creator can use this for access.
- --logfile=path
- A file to store the log in rather than printing to the standard output
- --update_time=secs
- Time between updates of the log. The experiment controller is queried for each update.
fedd_terminate.py
Deallocate resources from an experiment and remove the experiment structures from the experiment controller. It takes the standard arguments and:
- --experiment_cert=filename
- The filename must contain a certificate valid for the experiment's fedid. If so it is used to authenticate access to the experiment. A password may be required if one has been added to the private key.
- --experiment_name=name
- The local name of the experiment to query. Only the experiment creator can use this for access.
- --force
- Remove the experiment if at all possible. Experiments in starting or terminating states cannot be terminated without this option.
- --logfile=path
- A file to store the log in rather than printing to the standard output.
- --print_log
- Print a log of the experiment controllers actions. This causes fedd_terminate.py to act as a feddd_sppewlog.py for termination.
fedd_client.py
The fedd_client.py
command was the original command line interface to most of fedd
's interfaces. It has been superceded by the individual scripts above. There are one or two functions it still provides, but these are very specialized debugging functions, and most users will not need it.
fedid.py
The fedid.py
command prints the fedid of the public key of an X.509 certificate to the standard output. This is handy in getting fedids for the various databases that fedd
uses. The command is invoked with 0 or more --attribute=attr parameters and 0 or more filenames. The command prints the fedids and the attributes in the format of a global access database and can be used directly to construct those files. For example, this invocation:
$ fedid.py --attribute=split --attribute=allocate fedd.pem deterboss.pem
produces
fedid:ce90957dd5b7d20f9c3890c4599313b7f1cf31ea split,allocate fedid:9b8e7f2b114956ad516befc93fa7e7eae3751bf9 split,allocate
Configuration Utilities
There are several utilities used in the process of setting up a new controller on a DETER-style testbed. These generate federation databases from the main testbed database.
The fedid.py command can also be useful in configuration. It is described with other general command line utilities.
access_exp_access_db.py
The access_exp_access_db.py
command is a helper to generate access controler component access databases. It can be used to export access to a subset of testbed users.
It can be run on a DETER testbed's boss
to print datathat can be redirected into a file for use as a database. With no options it converts the entire users table of the testbed database into an access controller access database with an entry for each local project of which the user is a member. The fedid of the experiment controller that will assert the attributes is required.
That behavior can be constrained using the following options.
- --user=username
- Extract the information for username. Once --user is given once, only the users selected will be output. The option may be specified more than once.
- --project=projectname
- Extract information only for the given project. The option may be specified multiple times.
- --cert_dir=dir
-
Use dir as the directory containing user certificates. The
fedd
expects this to be a full pathname. It is just an output parameter; the directory does not need to exist. - --experiment_controller=cert
- The certificate of the experiment controller that will be asserting these credentials. Required.
Multiple user constraints are or-ed with each other as are multiple project constraints. Then the resulting or clauses are and-ed together. For example, the invocation
$ access_exp_accessdb.py --user faber --project Deter --project Virtual --experiment_controller ./fedd.pem --cert_dir /usr/local/etc/fedd/access/certs
produces output like
# users faber # projects Deter,Virtual (fedid:e630047380b1060ce03d19e373b8047bb785031a,Deter,faber)-> access, (Deter,faber,/usr/local/etc/fedd/access/certs/faber.pem) (fedid:e630047380b1060ce03d19e373b8047bb785031a,Virtual,faber)-> access, (Virtual,faber,/usr/local/etc/fedd/access/certs/faber.pem)
If the users are in other projects, those lines are suppressed; if the projects contain other users, those lines are suppressed. The comment lines before each cluster of output help administrators understand which data corresponds to a given user.
As with other commands in the fedd package, it is installed in /usr/local/bin
by default.
db_to_certs.py
This utility extracts the credentials needed to make local testbed requests from individual users to the local DETER testbed from the testbed database and stores them in a directory. It is helpful to do this when setting up a DETER access controller.
The arguments are:
- --user=username
- Extract the information for username. Once --user is given once, only the users selected will be output. The option may be specified more than once.
- --project=projectname
- Extract information only for the given project. The option may be specified multiple times.
- --cert_dir=dir
- Use dir as the directory containing user certificates. The directory must exist.
exp_access_db.py
The exp_access_db.py
command is a helper to generate experiment control component access databases. That is, it makes the file of attributes that an experiment controller exports.
It can be run on a DETER testbed's boss
to print data in that database's format that can be redirected into a file for use as a database. With no options it converts the entire users table of the database into an experiment control access database with an entry for each local project of which the user is a member. The fedid's are generated from the user's SSL certificates as they appear in the Emulab database.
That behavior can be constrained using the following options.
- --user=username
- Extract the information for username. Once --user is given once, only the users selected will be output. The option may be specified more than once.
- --project=projectname
- Extract information only for the given project. The option may be specified multiple times.
- --no-project-access
-
Do not generate a line for any of the projects a user is in. Only generate lines of the form
fedid:xxx -> user
- --no-user-access
-
Do not generate a line without an enclosing project. Only generate lines of the form
fedid:xxx -> (project,user)
Multiple user constraints are or-ed with each other as are multiple project constraints. Then the resulting or clauses are and-ed together. For example, the invocation
$ exp_access_db.py --user=faber --user=lahey --project=Deter --project=emulab-ops
produces output like
# faber fedid:12ecc7415746281efa0ed58e180c51a5cba13a57->faber fedid:12ecc7415746281efa0ed58e180c51a5cba13a57->(Deter,faber) fedid:12ecc7415746281efa0ed58e180c51a5cba13a57->(emulab-ops,faber) # lahey fedid:d7da471ff2ba5b205d31ae379b1cf634c8dce1c6->lahey fedid:d7da471ff2ba5b205d31ae379b1cf634c8dce1c6->(emulab-ops,lahey)
If the users are in other projects, those lines are suppressed; if the projects contain other users, those lines are suppressed. The comment lines before each cluster of output help administrators understand which data corresponds to a given user.
As with other commands in the fedd package, it is installed in /usr/local/bin
by default.
ABAC Utilities
There are several utilities for converting text-based configurations to ABAC and manipulating ABAC logic statements directly.
access_to_abac.py
access_to_abac.py
converts access controller policies into ABAC and generates a DB for mapping the derived attributes into an appropriate credential mapping database, the target of the accessdb configuration directive. Keys and certificates are required parameters as well as a directory for the ABAC authorizer and a file for the access DB.
It takes the following arguments:
--cert=
file- A file containing an X.509 certificate in pem format. This is the identity that will assert the attributes and should probably be the same as the experiment controller's identity. It may be a combination certificate and key file.
--key=
file-
The key for signing attributes. It should be a pem file with an RSA key in it. This can be omitted if
--cert
specifies a combination file. --dir=
dir- The output directory for the authorizer. (This must be an absolute pathname).
--type=
type- The type of access controller used by the access_type configuration directive. Used to parse the various formats of the old accessDB.
--quiet
- Do not produce extra output
--no_create_creds
- Do not create the authorizer (debugging only)
--file=
old_accessdb- The accessDB to convert. May also be specified as a bare parameter after the named parameters have been given.
--mapfile=
new_accessdb- The new accessDB to create. It must be a different file name than the file being converted.
--no_delegate
- By default the ABAC created attributes include a layer of delegation for a standalone fedd running with a different principal. Specifying this parameter eliminates a layer of delegation. Even for single-user experiment controllers, this option is rarely necessary.
--no_auth
- Do not create an authorizer. For debugging only.
--debug
- Just produce debugging output.
If --file
is not given, the accessDB to convert must follow.
cert_to_fedid.py
The fedd tools expect the identity of the user to be a self-signed certificate. This is accomplished using the command:
$ cert_to_fedid.py --cn $USER --out $HOME/.ssl/fedid.pem $HOME/.ssl/emulab.pem
The cert_to_fedid.py utility will list other parameters, but most are not needed for users. The fedid_tools search for .ssl/fedid.pem
as a default identity, so putting the output there will make things simple.
creddy_split.py
Split a combination PEM file (that contains both a key and a certificate) into a key and a certificate file. Early versions of ABAC were finicky about combination PEM files. It takes a single parameter, the combination to split. By default the output files are ./cert.pem
and ./key.pem
.
The arguments are:
- --cert=filename
- Store the certificate in filename
- --force
- Overwrite existing output files
- --key=filename
- Store the key in filename
dump_abac_authorizer.py
The dump_abac_authorizer.py
program prints the contenst of an abac authorizer. It takes one parameter, the directory containing the authorizer, and prints the contents of the authorizer. The first line is the keyid of the fedd that uses the authorizer. Each line after that is an ABAC credential in RT0 logic (the logic described here).
For example:
$ dump_abac_authorizer.py abac/ b9325180cc55b2af23bbfed6435d365449ab4afa b9325180cc55b2af23bbfed6435d365449ab4afa.new <- d18901f621eaa03507867212cd48c2b8d686d742 b9325180cc55b2af23bbfed6435d365449ab4afa.create <- d18901f621eaa03507867212cd48c2b8d686d742 b9325180cc55b2af23bbfed6435d365449ab4afa.faber <- d18901f621eaa03507867212cd48c2b8d686d742 b9325180cc55b2af23bbfed6435d365449ab4afa.feduser <- d18901f621eaa03507867212cd48c2b8d686d742
fedd_to_abac.py
fedd_to_abac.py
converts an fedd experiment controller configuration into an ABAC configuration. A certificate and key are required as well as an output directory for the ABAC authorizer (target of the auth_dir parameter in the configuration file.
It takes the following arguments:
--cert=
file- A file containing an X.509 certificate in pem format. This is the identity that will assert the attributes and should probably be the same as the experiment controller's identity. It may be a combination certificate and key file.
--key=
file-
The key for signing attributes. It should be a pem file with an RSA key in it. This can be omitted if
--cert
specifies a combination file. --dir=
dir- The output directory for the authorizer. (This must be an absolute pathname).
--make_dir
- If given, make the output directory.
--debug
- Just output the creddy commands that would be issued to create the certificates.
--policy_only
- Only output the ABAC certificates, not the full ABAC authorizer. This is primarily for debugging.
--update
- Update the output directory rather than creating it. This allows the authorizer to remember credentials it has learned or issued while updating the policy.
After the named arguments are given, the aceess DB file is a required argument.
import_abac_creds.py
The import_abac_creds.py program adds ABAC credential held in X.509 certificates directly to an ABAC authorizer used by fedd. This authorizer is created by either fedd_to_abac.py or access_to_abac.py. The command takes an argument of the form:
--dir=
dir- The output directory for the authorizer. (This must be an absolute pathname).
The remaining parameters are a list of files containing the certificates to add. These can be identity or attribute certificates. To add an attribute certificate signed by issuer.pem and contained in attr.der to an authroizer in /usr/local/etc/fedd/abac
the command is:
$ import_abac_creds.py --dir /usr/local/etc/fedd/abac issuer.pem attr.der
You can confirm the addition of the certificates using dump_abac_authorizer.py.