Configuring fedd

As noted in installation, many of these parameters define the layout of the fedd instantiation on your machine, so read the reference below and look at the examples to make sure you understand how fedd is working on your testbed.

If you are configuring an access controller that allows you to share loaclly administered resources with other federants, you should primarily configure the ![access] sections below. Choose the sub-sections that correspond to the plug-in you intend to configure. First time fedd users should try walking through the configuration and testing of a skeleton plug-in to acquaint themselves with the basic operation of configuring an access controller. That section walks a user through the configuration of an access controller step by step.

Fedd configuration files are broken down into sections that configure the various subcomponents. For experiment controllers, only the experiment_control section is required. Access controllers require more or fewer sections based on the features provided by the plug-in that is being used. Though the richness of configuration may seem daunting at first, the examples section should lead you to simple setups.

Access controllers and experiment controllers each have an access database that defines the services they grant to a given fedid. We describe the global configuration file first, and then the access databases.

Main Configuration File (fedd.conf)

The main configuration file is in /usr/local/etc/fedd.conf by default, though the --config option can redirect it. It of the basic format parsed by a python ​SafeConfigParser. Basically this format is sections headed by []'s with attribute/value pairs in for each section following. One can use any of the substitution tricks in the python documentation as well. There are 5 sections, one for each component and one for global options.

Global Options

Global options are in the section following the [globals] header. Experiment controllers and access controllers both use it. The following attributes are used:

cert_file

the file containing the certificate and private key for this server, in pem format.

cert_pwd

if the private key in cert_file has a password, it is given here.

services

This configures the addresses and ports on which fedd will provide services and what transport it will use on those ports. It is a comma-separated list of 1 to 3 colon-delimited fields. The semantics are:

• A single integer: the integer is considered the port on which to provide SOAP services for all default addresses of this host.
• An integer separated from a transport: services will be provided on the integer port using the given transport for all addresses of the machine. Transport may be SOAP or XMLRPC and is case insensitive.
• A hostname separated from a port separated from a transport: provide service on the port on the address given by the hostname using the transport. The address can be any hostname that the ​python socket understands; a DNS name is usually used.

trusted_certs

a file containing the trusted CAs used for SSL validation. If this is not present, no certificate path checking is done.

Each of these can be affected by other sections. For example, if the [access] section specifies a cert_file and cert_pwd, those will be used rather than those in [globals]. Similarly, [allocation] and [splitter] sections can include their own attribute databases. Note that the presence of another database does not invalidate the global access database, but adds to it.

Access Options

Access control sections follow the [access] header. These sections configure access controllers. Some options are universal and some are specific to the type of controller in use.

These attributes concern the how fedd grants access to remote experimenters through their fedd. Some of the parameters are directly related to whether access is granted and some are parameters returned to the requester so it can manipulate the resources once granted.

The following are valid attributes:

All Controllers

All controllers understand and respect the following:

accessdb

The mapping of three level names to local project and users (for creation and services). See below for the format of this DB.

access_state

Name of the file where current access state is saved. This state includes the access granted to each federated experiment request and is used to decide what to release and when. Must be specified for access decisions to survive fedd failures or node reboots. A file in /var/db/fedd is often used.

access_type

The underlying plug-in module to use for access. Currently emulab, dragon, deter_internal, and protogeni are understood. We will be adding more choices as well as dynamic choices in the near future. The default is emulab, for backward compatibility.

cert_file

Certificate used to assert identity of the access controller. It uses this certificate when proxying requests. Note that the certificates used in the [allocate] section are used to contact a remote allocation fedd. If this field is not present and a cert_file is present in the [globals] section, the [globals] certificate will be used.

certdir

Local certificates for granting access to sub-experiments. This directory should be writable by fedd and unreadable to all others.

cert_pwd

Password for the private key in cert_file. If the [globals] certificate is used, so is the [globals] cert_pwd, if any.

domain

The trailing (common) parts of the domain name for various hosts. Returned to the requester to allow manipulation of resources.

log_level

The level of logging to produce from this component. One of debug, info, warning, critical, and error. See the ​standard python logging system for details.

project_priority

When considering two possible resolutions of wildcarded access control db entries, give priority to a project match over a user match. Default is to give priority to the user match.

trusted_certs

a file containing the trusted CAs used for SSL validation. If this is not present, no certificate path checking is done. If this field is not present and a trusted_certs field is present in the [globals] section, the [globals] certificates will be used.

In addition they understand the following debugging settings:

create_debug

A boolean. If true this access controller will not actually allocate resources, but always report success. The default is false - carry out real allocations.

leave_tmpfiles

A boolean. If true the controller will not remove temporary files allocated when carrying out operations, notably sub-experiment creation. The default is false- clean up.

Emulab Controllers

Emulab controllers understand and respect the following options, as well as the [allocation] section described below.

deter_internal

True if the Emulab supports interval VLANs controlled by a deter_internal controller.

dragon

True if the testbed is connected to the DRAGON transit

dragon_vlags

If the testbed is connected to a set of static DRAGON VLAN termination numbers, this is the list of VLAN IDs. The lists of the form 1-10,11,14 are permitted.

federation_software

Location of the tar file containing the federation kit to establish the on all nodes. This is a list of installation directory, software pairs. /usr/local /usr/local/etc/fedd/fedkit.tgz will install the tarball in fedkit.tgz in /usr/local. The destination directory can be rpm if the software is in an rpm file. There is a version available from the downloading section that can be installed in /usr.

local_seer_software

local_seer_image

local_seer_startup

The software, disk image, and startup commands necessary to start a local ​SEER controller.

node_startcommand

Startcommand to run for a generic node. The version given in the examples is right for our fedkit.

portal_command

Ns2 command to embed in an experiment description for a portal node, if any

portal_image

Required image for a portal node, if any

portal_software

Location of the tar file containing additional software required on the in experiments to support extra services. It has the same format as federation_software.

portal_startcommand

Startcommand to run for a portal node. The version given in the examples is right for our fedkit.

portal_type

Required portal hardware type, if any

ssh_port

Port used by portal nodes for remote access. This rarely needs to be overridden.

ssh_privkey_file

The public key that this fedd will use to access remote Emulab services, if it is a remote access controller. Protect it appropriately. Earlier versions always defined this option in as an experiment control option. That is no longer supported.

tunnel_config

True if the testbed supports DETER extensions to tmcd for external access

type

Emulab access controllers can either run on the local testbed infrastructure (users and boss as described in the downloading and installation documentation) or on another node as a proxy. Choices are remote_emulab and local_emulab. Remote access controllers access the testbed using ssh for file transfer and other reasons using the key given in ssh_privkey_file.

userconfdir

Directory used to stage information about user accounts that are exported to other testbeds. It needs to be writeable by fedd.

userconfcmd

External command used to export user information. It should return the user accounts to create in a format similar to the Emulab tmcd USERS command. Specifically group entries should be formatted as

ADDGROUP NAME=name GID=digits

and user information as

ADDUSER LOGIN=name PSWD=hash WPSWD=passwd UID=digits GID=digits ROOT=1/0 NAME="user name" HOMEDIR=path GLIST="gname gname" EMAIL="a@b" SHELL=shell

This is required if the controller is to export user accounts.

userconfurl

URL from which to acquire the exported user information. It should almost always be the access controller's URL.

Allocation Options

The [allocation] section controls how Emulab access controllers allocate projects locally. If the uri option is set in the [access] section, the [allocation] section defined the parameters used to communicate with the remote fedd. If not, project allocation will occur on this machine and the parameters apply to the manipulation of the local Emulab state to grant access.

We do not discuss the somewhat unusual case of a remote_emulab access controller that creates and destroys projects on the remote emulab by talking to a local_emulab access controller running on the remote Emulab. Such a thing works, though.

The following options are valid:

accessdb

This file controls which callers (i.e., which fedids) can access the project allocation services. The format and execution mechanisms are on the databases page. All the information contained in a database specified here can be specified in the global accessdb.

allocation_level

This option defines what fedd will try to do to grant access. The following are valid choices:

• dynamic_projects - Add new projects and users to the local Emulab in response to requests. What users and projects and who may successfully request them is a function of the access DB below. The access component decides what projects and users to add and the allocation component does the work.
• dynamic_keys - No projects or users are added to the local Emulab, but addtional keys may be granted access to user accounts and projects may have their access rights expanded. Again the access component decides which users and projects to expand and the allocation system does so.
• confirm_keys - The local Emulab is never changed, but the allocating fedd confirms that the users specified may be accessed by the given keys. In effect, it confirms that the if the changes were requested, they would succeed.
• none - The local Emulab is never changed, and no parameters are checked. This makes allocation a no-op.

allocation_state

Name of the file where current allocation state is saved. This state includes the project and user changes made to support each federated experiment request. That state is used to decide what to release and when. Must be specified for allocation decisions to survive fedd failures or node reboots. A file in /var/db/fedd is often used.

addpubkey

Path to the addpubkey Emulab command. Only useful for local allocation. The default of /usr/testbed/sbin/addpubkey is usually insufficient. See the instructions in installing for information on how to construct and install the taddpubkey version, and set this option to point at it. Note that if you are not dynamically allocating resources, you need not create the new script nor set this option.

cert_file

Certificate used to assert identity of the allocation component. If uri is set in this section, this certificate is presented to the remote allocation fedd, if not this certificate is presented to the allocator making a request. If this field is not present and a cert_file is present in the [globals] section, the [globals] certificate will be used.

cert_pwd

Password for the private key in cert_file. If the [globals] certificate is used, so is the [globals] cert_pwd, if any.

confirmkey

Path to the Emulab command used to confirm a user's public SSH key. Only useful for local allocation. The default of /usr/testbed/sbin/addpubkey is usually insufficient. If you are interested in dynamic allocation, the same modifications that make taddpubkey sufficient as for use in adding and removing public SSH keys are sufficent for this use as well. Follow the instructions in installing for information on how to construct and install the taddpubkey version, and set this option to point at it. If you are not allocating resources dynamically, you can use the confirm_sshkey.py script packaged with fedd for this purpose. By default it is installed as `/usr/local/bin/confirm_sshkey.py'.

debug

If this boolean is true, a local allocating fedd will not execute the allocation commands, just log them (at debug priority). It has no effect on a fedd that is calling out to make allocations.

grantnodetype

Path to the grantnodetype Emulab command. Only useful for local allocation. The default of /usr/testbed/sbin/grantnodetype is usually insufficient. See the instructions in installing for information on how to construct and install the tgrantnodetype version, and set this option to point at it. Note that if you are not dynamically allocating resources, you need not create the new script nor set this option.

log_level

The level of logging to produce from this component. One of debug, info, warning, critical, and error. See the ​standard python logging system for details.

mkproj

Path to the mkproj Emulab command. Only useful for local allocation. The default of /usr/testbed/sbin/mkproj is usually correct.

newproj

Path to the newproj Emulab command. Only useful for local allocation. The default of /usr/testbed/sbin/newproj is usually correct.

newuser

Path to the newuser Emulab command. Only useful for local allocation. The default of /usr/testbed/sbin/newuser is usually correct.

rmproj

Path to the rmproj Emulab command. Only useful for local allocation. The default of /usr/testbed/sbin/rmproj is usually correct.

rmuser

Path to the rmuser Emulab command. Only useful for local allocation. The default of /usr/testbed/sbin/rmuser is usually correct.

trusted_certs

a file containing the trusted CAs used for SSL validation. If this is not present, no certificate path checking is done. If this field is not present and a trusted_certs field is present in the [globals] section, the [globals] certificates will be used.

uri

If present this gives the uri of the fedd that will perform the manipulation of the local project database to grant and revoke access to the testbed. In installations where fedd runs on both users and boss, this will tell the users fedd where to reach the boss fedd. The certificates and trusted certificates specified in the [allocate] section establish the identity of this fedd when communicating with the remote fedd.

user_to_project

Script to attach a new local (Emulab) user to a local (Emulab) project. The user_to_project.py script shipped with fedd is used for this purpose by default. Specifically, the default value of this option is /usr/local/bin/user_to_project.py.

Dragon Access Controllers

DRAGON access controllers allocate resources using the ​OSCARS client software so much of its configuration is concerned with connecting the plug-in to that software.

DRAGON controllers understand and respect the following settings.

axis2_home

OSCARS depends on the ​axis web services client classes. Setting this variable to the location of these classes is required.

cli_dir

The location of the OSCARS command line installation.

idc

The uri of the inderdomain controller to reserve circuits through.

ProtoGENI

ProtoGENI controllers understand the following settings:

api

The underlying component manager API to use. Choices are protogeni for the ​ProtoGENI v2 CM and geniapi for the ​GENIAPI v 0.9 AM.

ch_url

The URL of the ProtoGENI clearinghouse

cm_url

The URL of the ProtoGENI component manager

deter_internal

True if the Emulab supports interval VLANs controlled by a deter_internal controller.

dragon

True if the testbed is connected to the DRAGON transit

dragon_vlags

If the testbed is connected to a set of static DRAGON VLAN termination numbers, this is the list of VLAN IDs. The lists of the form 1-10,11,14 are permitted.

federation_software

Location of the tar file containing the federation kit to establish the on all nodes. This is a list of installation directory, software pairs. /usr/local /usr/local/etc/fedd/fedkit.tgz will install the tarball in fedkit.tgz in /usr/local. The destination directory can be rpm if the software is in an rpm file. There is a version available from the downloading section that can be installed in /usr.

local_seer_software

local_seer_image

local_seer_startup

The software, disk image, and startup commands necessary to start a local ​SEER controller.

node_startcommand

Startcommand to run for a generic node. The version given in the examples is right for our fedkit.

portal_command

Ns2 command to embed in an experiment description for a portal node, if any

portal_image

Required image for a portal node, if any

portal_software

Location of the tar file containing additional software required on the in experiments to support extra services. It has the same format as federation_software.

portal_startcommand

Startcommand to run for a portal node. The version given in the examples is right for our fedkit.

portal_type

Required portal hardware type, if any

renewal

Renewal interval for ProtoGENI slices, in minutes.

sa_url

The URL of the ProtoGENI slice authority.

sshd

Pathname of an alternative ssh daemon to run on ProtoGENI nodes.

sshd_config::

Pathname of an alternative ssh daemon configuration file to use on ProtoGENI nodes.

ssh_port

Port used by portal nodes for remote access. This rarely needs to be overridden.

ssh_privkey_file

The public key that this fedd will use to access remote Emulab services, if it is a remote access controller. Protect it appropriately. Earlier versions always defined this option in as an experiment control option. That is no longer supported.

staging_dir

Directory on the staging_host where software is staged for loaging onto protoGENI nodes. The fedd must be able to write to it.

staging_host

The host on which to stage software bound for ProtoGENI nodes. If it is not the same machine on which the daemon runs, it must be accessible through the ssh parameters configured for this fedd.

tunnel_config

True if the testbed supports DETER extensions to tmcd for external access

type

Emulab access controllers can either run on the local testbed infrastructure (users and boss as described in the downloading and installation documentation) or on another node as a proxy. Choices are remote_emulab and local_emulab. Remote access controllers access the testbed using ssh for file transfer and other reasons using the key given in ssh_privkey_file.

userconfdir

Directory used to stage information about user accounts that are exported to other testbeds. It needs to be writeable by fedd.

userconfcmd

External command used to export user information. It should return the user accounts to create in a format similar to the Emulab tmcd USERS command. Specifically group entries should be formatted as

ADDGROUP NAME=name GID=digits

and user information as

ADDUSER LOGIN=name PSWD=hash WPSWD=passwd UID=digits GID=digits ROOT=1/0 NAME="user name" HOMEDIR=path GLIST="gname gname" EMAIL="a@b" SHELL=shell

This is required if the controller is to export user accounts.

userconfurl

URL from which to acquire the exported user information. It should almost always be the access controller's URL.

Experiment Control Options

These options control how fedd embeds an experiment into the requested testbeds, including acquiring access and starting the experiment.

accessdb

Database that indicates who can request services from this fedd and what three-level names the fedd will attest on their behalf. The specification is on the databases page.

cert_file

Certificate used to assert identity of the experiment control component. If this field is not present and a cert_file is present in the [globals] section, the [globals] certificate will be used.

cert_pwd

Password for the private key in cert_file. If the [globals] certificate is used, so is the [globals] cert_pwd, if any.

experiment_state

Name of the file where current experiment state state is saved. This state includes the allocations made to support each federated experiment request as well as the information necessary to release those resources. Must be specified for experiment to survive fedd failures or node reboots. A file in /var/db/fedd is often used.

log_level

The level of logging to produce from this component. One of debug, info, warning, critical, and error. See the ​standard python logging system for details.

mapdb

Database that controlls the default mapping from testbed name to contact URI.

ns2topdl_uri

Contact point for using a remote experiment translator. Generally this should be set to http://users.isi.dertelab.net:23235 .

repodir

Directory where fedd can stage software for experiments. Should be on an adequately sized file system with permissions that the fedd can access. IN deciding size, consider the size of required software like fedkits and the software users might include in experiments.

repo_url

The URL on which access controllers can collect staged software. Should almost always be the URL of the experiment controller.

store_url

The URL on which access controllers can collect synchronization information. Should almost always be the URL of the experiment controller.

synch_store

file in which synchronization information is stored between runs. This should be a filename in an accessible directory. Fedd will create it if it does not exist.

tcl_splitter

Path to the tcl-based topdl translator program to be used if translation is done locally. If ns2topdl_url is set, this has no effect.

trusted_certs

a file containing the trusted CAs used for SSL validation. If this is not present, no certificate path checking is done. If this field is not present and a trusted_certs field is present in the [globals] section, the [globals] certificates will be used.

overrides

A comma separated list of fedids that can access any experiment. Each fedid must include the fedid: prefix.

Splitter Options

The splitter component is a misnomer; it controls the ns2 to topdl translation service. Most fedd installations will use the fedd at https://users.isi.deterlab.net:23235 to provide this service by setting splitter_url in the [experiment_control] section. Should you need to configure a splitter, the parameters are:

accessdb

Database indicating which requesters can use the service.

allow_any

If this boolean is true, any requester may use the service. The service at https://users.isi.deterlab.net:23235 has this parameter set.

debug

Produce debugging output and do not call the splitting program

log_level

The level of logging to produce from this component. One of debug, info, warning, critical, and error. See the ​standard python logging system for details.

muxmax

Maximum number of inter-testbed connections to attempt on a single connector. Default is 3.

tclsh

Interpreter to call to run the splitter script. Default is /usr/local/bin/otclsh

tcl_splitter

Script to do the translation. Default is /usr/testbed/lib/ns2ir/parse.tcl. Most Emulabs will not include a parse.tcl capable of doing the split.

Making a Fedid Certificate

Each fedd and client encodes an fedid as an X.509 certificate. The openssl command installed on most Unices can create such a certificate. The simplest things to do is the following:

$ /usr/bin/openssl req -text -newkey rsa:1024 -keyout key.pem -nodes -subj /CN=users.isi.deterlab.net -x509 -days 3650 -out cert.pem
$ cat key.pem cert.pem > fedd.pem

The resulting fedd.pem file contains an unencrypted private key and certificate. To use a password, the sequence is:

$ /usr/bin/openssl req -text -newkey rsa:1024 -keyout key.pem -nodes -subj /CN=users.isi.deterlab.net -x509 -days 3650 -out cert.pem
$ openssl rsa -in key.pem -des3 -out keyout.pem
# Prompts for a password
$ cat keyout.pem cert.pem > fedd.pem
$ rm key.pem