= 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 [FeddConfig configuration files] and [FeddDatabases 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 ofr 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 [FeddConfig#AllocationOptions 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 [FeddDatabases#ExperimentControlComponentAccessDB 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 [FeddAbout#GlobalIdentifiers:Fedids 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 [FeddAbout#GlobalIdentifiers:Fedids 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_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 [FeddExperiment experiment description].
 '''--project='''''export_project''::
  The local project to export from the master 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.
 '''--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 [FeddDatabases#ExperimentNameMappingDB experiment name mapping DB] to resolve that name to a testbed.

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:23234 --transport=xmlrpc
}}}