Fedd Commands

These are the various user level programs that the fedd package installs, including fedd itself.

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

Confirm_sshkey.py

The confirm_sshkey.py command is used by fedd to confirm that a local account can be accessed using an SSH public key. It does this by accessing the Emulab database, and must run on boss. It is included in the distribution for administrators who want to be able to confirm keys without patching addpubkey.

The command takes the same arguments as the extended version of addpubkey, which is to say the same arguments as the unextended addpubkey plus -C. Other than installing it and adjusting the confirmkey parameter in the [allocation] section of the configuration file users should rarely need this command. By default the fedd package confirm_sshkey.py in /usr/local/bin.

Exp_access_db.py

The exp_access_db.py command is a helper to generate experiment control component access databases. It can be run on 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.

Fedd_client.py

The fedd_client.py command is a simple command line interface to most of fedd's interfaces. It allows users to create terminate and interrogate experiments as well as to make access requests and request experiment splits. The access and splitting commands are primarily for debugging. Users who wish to make use of that function can consult the command's internal help message, by issuing one of

$ fedd_client.py split --help 
$ fedd_client.py access --help

The general syntax for invoking the command is:

$ fedd_client.py operation parameters

where operation is one of create, terminate, info, vtopo, vis, info, split, or access and the parameters are described below.

All commands take the following parameters:

--cert=filename

Certificate from which to derive the user's fedid. By default the contents of .ssl/emulab.pem in the user's home directory is used.

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

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

The create command takes the following additional parameters:

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

--file=filename

File containing the experiment description.

--project=export_project

The local project to export from the master testbed.

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

--sshKey=file

Use the contents of file as the SSH key for service access in the experiment. By default the contents of .ssh/id_rsa.pub is used.

An example of experiment creation is:

$ fedd_client.py create --file=test_fedd.tcl --master=deter --project=emulab-ops --url=https://users.isi.deterlab.net:23235 --transport=xmlrpc

The results are the local name of the experiment and its fedid printed to standard output. If --experiment_file is given an X.509 certificate and private key are saved to the given file that can be used as a capability to access the experiment state.

The commands to access data about an experiment or to terminate it all take only two non-generic options:

--experiment_file=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 terminate. Only the experiment creator can use this for access.

The informational commands are vtopo, vis, and info. Vtopo and vis are equivalent to the analogous Emulab XMLRPC commands, and fedd_client.py prints thier results in raw XML. Info provides more information about the experiment, and it is printed as a python hash. These are primarily used for debugging rather than operations.

The terminate command stops a federated experiment and removes the access granted from the federants.

The split and access commands are really only for developers. They are not described here, but

$ fedd_client.py access --help
$ fedd_client.py split --help

provides information on their use.

Fedid.py

The fedid.py command prints the [Feddabout#Globalidentifiers:Fedids 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

User_to_project.py

The user_to_project.py command exists to provide command line functionality that Emulab keeps in a web page. It attaches a user to a project. It is called by a fedd running on boss when a project is dynamically created. Its default installation destination and the default value for the [experiment_control] parameter user_to_project both default to /usr/local/bin/user_to_project.py. It is unlikely a user will ever need to run this command.