= Configuring fedd = This section is a reference on the `fedd` configuration files. 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 [FeddGettingStarted adminstrator's guide] or the [wiki:FeddSkelPlugin 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 [FeddPluginArchitecture plug-in] that is being used. Though the richness of configuration may seem daunting at first, the [FeddGettingStarted adminstrator's guide] 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 [http://www.python.org/doc/current/library/configparser.html 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. The format allows attributes to be substituted into other values, so it is a bset practice to define an attribute for commonly used values like so: {{{ [DEFAULT] # Configuration directory base: /usr/local/etc/fedd/fedd #logging directory var: /var/db/fedd/fedd # Machine running fedd hostname=users.isi.deterlab.net }}} These can be substituted at other places in the same file, like so: {{{ repodir: %(var)s/repo repo_url: https://%(hostname)s:23235 }}} Note that the "s" after the second parenthesis is literal and required. === 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 [FeddConfig#MakingaFedidCertificate 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 [http://www.python.org/doc/current/library/socket.html 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 ABAC DB that maps three-level names to local project and users (for creation and services). This is the map file generated by [wiki:FeddCommands#access_to_abac.py access_to_abac.py]. Usually something like `%(base)s/deter_abac_map`. '''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 common value `%(var)s/access.state`. '''auth_type''':: '''Deprecated'''. Access control system used only '''abac''' works. '''auth_dir''':: The diretory that holds the ABAC authorization directory, created by [wiki:FeddCommands#access_to_abac.py access_to_abac.py]. '''cert_file''':: Certificate used to assert identity of the access controller. It uses this certificate when proxying requests. 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. `%(base)s/certs` or `%(var)s/certs` are common. '''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 [http://www.python.org/doc/current/library/logging.html 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. '''type''':: The underlying plug-in module to use for access. Currently '''emulab''', '''dragon''', '''deter_internal''', '''protogeni''', '''desktop''', and '''starbed''' are understood. We will be adding more choices as well as dynamic choices in the near future. The default is '''emulab''', for backward compatibility. 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. '''boss''':: The DNS name of the Emulab boss node. The controller contacts this node to create and manipulated local experiments. '''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_vlans''':: 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 [FeddAbout#TheFederationKit 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 [FeddDownload section] that can be installed in `/usr`. '''local_seer_software''':: '''local_seer_image''':: '''local_seer_start''':: The software, disk image, and startup commands necessary to start a local [http://seer.isi.deterlab.net SEER] controller. '''nat_portal''':: If the controller is behind a [http://en.wikipedia.org/wiki/Network_address_translation NAT] or set of NATs, this holds the external addresses that will forward packets into the experiments. This value is used to establish routes between sub-experiments. A comma separated list of DNS names, IP addresses or both is required. '''node_startcommand''':: Startcommand to run for a generic node. The version given in the [FeddConfigExamples examples] is right for our fedkit. '''ops''':: The DNS name of the Emulab ops node. Local users' files and other local data is manipulated here. '''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 [FeddConfigExamples examples] is right for our fedkit. '''portal_type''':: Required portal hardware type, if any '''seer_master_start''':: The startup command to start a master [http://seer.deterlb.net SEER] controller. A master SEER controller coordinates the local SEER servers. '''shared_nat''':: True if the controller uses the DETER extensions for a shared NAT for external access. '''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 [FeddDownload#Whatmachinesshouldrunfedd 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. '''xmlrpc_cert ==== Dragon Access Controllers ==== DRAGON access controllers allocate resources using the [https://wiki.internet2.edu/confluence/display/DCNSS/Java+Client+API 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 [http://ws.apache.org/axis2 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 [http://www.protogeni.net/trac/protogeni/wiki/ComponentManagerAPIV2 ProtoGENI v2 CM] and '''geniapi''' for the [http://groups.geni.net/geni/wiki/GeniApi 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 [FeddAbout#TheFederationKit 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 [FeddDownload 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 [http://seer.isi.deterlab.net SEER] controller. '''node_startcommand''':: Startcommand to run for a generic node. The version given in the [FeddConfigExamples 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 [FeddConfigExamples 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 [FeddDownload#Whatmachinesshouldrunfedd 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''':: '''Deprecated'''. 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 [FeddDatabases databases page]. This is unused and unnecessary when '''auth_type''' is '''abac'''. It is converted to ABAC format using [wiki:FeddABAC#fedd_to_abac.py fedd_to_abac.py]. '''auth_type''':: '''Deprecated'''. Access control system used. Must be '''abac'''. '''auth_dir''':: The directory that holds the ABAC authorization directory, created by [wiki:FeddCommands#fedd_to_abac.py fedd_to_abac.py]. '''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. '''create_debug''':: If true, do not create experiments. '''default_testbed''':: The testbed to which to assign nodes without a testbed attribute. '''direct_transit''':: List of testbeds that can only interconnect other testbeds. '''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)s/fedd` is often used. '''fedkit''':: The [FeddDownload#TheFederationKitfedkit fedkit] to use for connections. '''gatewaykit''':: If a specialized [FeddDownload#TheFederationKitfedkit fedkit] is needed for gateways, this specifies it. Uneeded with the default fedkit. '''info_cache''':: Number of seconds to cache status information about sub-experiments. See [FeddCommands#fedd_ftopo.py fedd_ftopo.py] and [FeddCommands#fedd_info.py fedd_info.py] descriptions for the data this covers. '''log_level''':: The level of logging to produce from this component. One of `debug`, `info`, `warning`, `critical`, and `error`. See the [http://www.python.org/doc/current/library/logging.html 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.deterlab.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. '''routing''':: '''Experimental'''. Local program to supply static routes to the federated experiment. '''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''':: '''Deprecated.''' 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''':: [FeddDatabases#GlobalAccessDB Database] indicating which requesters can use the service. Unused if '''auth_type''' is '''abac'''. '''auth_type''':: Access control system used. Must be '''abac''' or '''legacy''', and obviously '''abac''' is preferred. '''auth_dir''':: When '''abac''' is specified for '''auth_type''' this is the diretory that holds the ABAC authorization directory, probably created by [wiki:FeddABAC#access_to_abac.py access_to_abac.py]. '''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 [http://www.python.org/doc/current/library/logging.html 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 [FeddAbout#GlobalIdentifiers:Fedids 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 }}} == Converting User Credentials to fedids == 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.