Context Navigation

Changes between Version 26 and Version 27 of FeddConfig

Timestamp:: Jun 11, 2014 3:54:58 PM (10 years ago)
Author:: faber
Comment:: --

Legend:

: Unmodified
: Added
: Removed
: Modified

FeddConfig

-                      v26
+                      v27
 = 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.
+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 [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 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.
+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`) ==
 …
 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 ===
 …
  '''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:FeddABAC#access_to_abac.py access_to_abac.py]. Usually something like `%(base)s/deter_abac_map`.
+  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 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.
+  fedd failures or node reboots.  A common value `%(var)s/access.state`.
  '''auth_type'''::
    Access control system used.  Must be '''abac''' or '''legacy''', and obviously '''abac''' is preferred.
+   '''Deprecated'''. Access control system used only '''abac''' works.
  '''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].
+   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. 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.
+  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.
+  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.
 …
   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:
 …
 ==== Emulab Controllers ====
+Emulab controllers understand and respect the following options, as well as the [allocation] section described below.
+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_vlags'''::
+ '''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'''::
 …
  '''local_seer_software'''::
  '''local_seer_image'''::
  '''local_seer_startup'''::
+ '''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_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.
 …
   '''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 [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`.
+  '''xmlrpc_cert
 ==== Dragon Access Controllers ====
 …
  '''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].  This is unused and unnecessary when '''auth_type''' is '''abac'''.  It can be converted to ABAC format using [wiki:FeddABAC#fedd_to_abac.py fedd_to_abac.py].
+  '''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'''::
    Access control system used.  Must be '''abac''' or '''legacy''', and obviously '''abac''' is preferred.
+   '''Deprecated'''. Access control system used.  Must be '''abac'''.
  '''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].
+   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/db/fedd` is often used.
+ 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.
 …
   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 .
+  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.
 …
   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.
+   '''Deprecated.''' A comma separated list of fedids that can access any experiment.  Each fedid must include the '''fedid:''' prefix.
 === Splitter Options ===