= 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 [FeddConfigExamples examples] to make sure you understand how fedd is working on your testbed. Fedd is broken into 4 components: experiment control, access control, project allocation, and experiment description parsing (most installations will not need this component). There is a global configuration file with subsections devoted to each of these components. Each component also has an access database that defines the services they grant to a given fedid. We described 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. === Global Options === Global options are in the section following the [globals] header. The following attributes are used: '''accessdb''':: global fedid -> access attribute mapping database. See the [FeddDatabases databases section] for information on the format and generation methods. '''cert_file''':: the file containing the X509 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 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: '''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. '''allow_proxy''':: Allow this fedd to act as a proxy for others in making access requests. This functionality is in development and ''not'' intended for use yet. '''boss''':: Hostname to report as boss to remote testbeds granted access. A requesting `fedd` uses this to configure internals of the federated experiment. This is just the first component of the name, the '''domain''' option provides the rest. '''cert_file''':: Certificate used to assert identity of the access component. 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. '''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. '''eventserver''':: Hostname of the machine that forwards events in this testbed. Returned to the requester to allow manipulation of resources. '''fileserver''':: Hostname of the machine that serves user files in this testbed. 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. '''testbed''':: A comma separated list of URLs that this fedd answers requests on. Requests for testbeds other that these will be denied, or proxied if '''allow_proxy''' is true (which it ''shouldn't'' be). '''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. === Allocation Options === The [allocation] section controls how Emulab project allocation is carried out on the host where `fedd` is running. 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. 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 [FeddDatabases 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 [FeddDownload 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 [FeddDownload 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 [FeddDownload 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 [http://www.python.org/doc/current/library/logging.html 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`. === 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 [FeddDatabases 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. '''create_debug''':: If this boolean is true, this component will not create the experiment, though it will make access control requests to remote testbeds. '''fedkit''':: Location of the tar file containing the federation software to establish the expriment. There is a version available here. '''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 [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. '''ssh_pubkey_file''':: The public key that this `fedd` will use to access remote Emulab services. Required. '''ssh_privkey_file''':: The private key corresponding to the key in '''ssh_pubkey_file'''. This should be accessibel without a password, and properly protected, for example in a local filesystem with appropriate permissions, or with `fedd` running under an ssh agent. '''ssh_keytype''':: Type of key generated for internal accesses in the experiment. It can be either dsa or rsa, but probably does not need to be changed. '''splitter_uri''':: Contact point for using a remote experiment splitter. Generally this should be set to !http://users.isi.dertelab.net:23235 . '''tcl_splitter''':: Path to the tcl-based splitter program to be used if splitting is done locally. If '''splitter_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. === Splitter Options === The splitter component divides a federated experiment description into sub-experiments and that include infrastructure nodes that will connect the experiments. 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. '''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 splitting. Default is `/usr/testbed/lib/ns2ir/parse.tcl`. Most Emulabs will not include a `parse.tcl` capable of doing the split.