Changes between Initial Version and Version 1 of FeddDatabases

Timestamp:

Dec 10, 2008 6:34:52 PM (15 years ago)

Author:

faber

Comment:

--

FeddDatabases

@@ +1 @@
+= Fedd Databases =
+
+There are several small databases that control how `fedd` operates.  They are the various access databases that control which [FeddAbout#GlobalIdentifiers:Fedids fedids] can access services and how they will be mapped into three-level names or local testbed parameters, and the database that maps local testbed names into service URIs.
+
+== Access Component accessdb ==
+
+This is the most complex of the accessdbs.  Its purpose is to configure how an access control component maps a [FeddAbout#GlobalIdentifiers:Three-levelNames three level name] to a local testbed user and project, as well as the rights the project must possess (the node types it can access).  It also includes information about which kinds of nodes are restricted and allows a testbed owner to supply additional attributes used in accessing the testbed.
+
+The file is a text file.  Each line containing a -> represents a rule for mapping from one or more three-level names to local testbed entities.  The format for a three-level name to project info mapping has the format:
+
+{{{
+(testbed, project, user) -> (local_project[:node_type[,node_type]], local_creation_user, local_service_user)
+}}}
+
+The triple on the left is the three-level name.  One of those fields must be a [FeddAbout#GlobalIdentifiers:Fedids fedid], given as fedid:xxxxx .  The x's are the text of the hexadecimal representation of the fedid.  After the fedid, the fields can either be strings or more fedids.  Recall that a valid [FeddAbout#GlobalIdentifiers:Three-levelNames three-level name] must be anchored in a fedid.
+
+The `local_project` is a project on the testbed, and `local_creation_user` and `local_service_user` are testbed users that are members of that project.  The `local_experiment_user` will run commands on behalf of `fedd` that create the sub-experiment on this testbed and needs appropriate authority.  The `local_service-user` may be accessed by the experimenter once the experiment is in progress, and need not have the authority to create or delete experiments.  The optional list of node types after the `local_project` (separated by a colon) are the node types that the project can access.
+
+An example of the simplest sort of access accessdb line is:
+
+{{{
+(fedid:ce90957dd5b7d20f9c3890c4599313b7f1cf31ea, Deter, faber) -> (fed, foo, bar)
+}}}
+
+That line grants access to a user `faber` in project `Deter` from the testbed with the given fedid.  That user will be mapped into local testbed project `fed` as local testbed user `foo` for experiment creation and `bar` for service access.  Notice that the strings to the left of the arrow refer to global three-level names and those on the right to local testbed entities.
+
+Special fields can appear in either the three-level name or the local entity clauses.  In the three level name, they determine how the rule matches.  Two special fields are `<any>` which matches any value and `<none>` which explicitly indicates the field is absent.  Here are examples with those rules:
+
+{{{
+(fedid:ce90957dd5b7d20f9c3890c4599313b7f1cf31ea, <any>, bill) -> (fed, foo, bar)
+(fedid:ce90957dd5b7d20f9c3890c4599313b7f1cf31ea, <none>, faber) -> (fed, baz, quux)
+(fedid:ce90957dd5b7d20f9c3890c4599313b7f1cf31ea, <any>, <none>) -> (fed, foo, fred)
+}}}
+
+The first rule will match the `bill` user from the given testbed regardless of the project that the testbed asserts (including no project).  The second line matches the `faber` user from the given testbed only if no project is asserted by that testbed.  The third line matches any three-level name that originates from the given testbed and includes only a project (and any project will match).
+
+On the local entity side, the special fields are `<same>` which indicates that the corresponding value in the three-level name should be used as the local name and `<dynamic>` which indicates that a new project or user should be allocated for this access.  For example:
+
+{{{
+(fedid:ce90957dd5b7d20f9c3890c4599313b7f1cf31ea, Deter, <any>) -> (fed, foo, <same>)
+(fedid:ce90957dd5b7d20f9c3890c4599313b7f1cf31ea, <none>, faber) -> (<dynamic>, <dynamic>, <dynamic>)
+}}}
+
+The top line indicates that any user in the `Deter` project of the given testbed will be mapped to the local `fed` project using user `foo` to create the experiment and an account with the same user name as the user in the three-level name for service access.  (NB `<same>` means "use the same string as in the three-level name" not "use the same string as for the other local user.")  The administrator should guarantee that the mebers of the `foo` group on his or her testbed are a superset of the users for which the given testbed will assert `Deter` as a project in the three-level name.  That may be done out of band.  The next line indicates that user `faber` without a project from the given testbed should be allocated a dynamic project.  Currently if one field is `<dynamic>` all three must be, a restriction that will be relaxed in the future.
+
+If a rule with no `<any>` fields matches, that rule is preferred to others with `<any>` fields.  If multiple `<any>` fields match, the match with the fewest `<any>` matches has precedence.  An `<any>` field cannot anchor a three-level matching rule (that it is, `<any>` cannot match an initial fedid).  That leaves one ambiguity - if (fedid:ce90957dd5b7d20f9c3890c4599313b7f1cf31ea, Deter, faber) requests access from a testbed with only the rules:
+
+{{{
+(fedid:ce90957dd5b7d20f9c3890c4599313b7f1cf31ea, Deter, <any>) -> (foo, <same>, <same>)
+(fedid:ce90957dd5b7d20f9c3890c4599313b7f1cf31ea, <any>, faber) -> (bar, <same>, <same>)
+}}}
+
+the outcome is determined by the setting of the '''project_priority''' option in the [FeddConfig#AccessOptions access section] of the global configuration file.  If it is true, the user will map to local project `foo`, otherwise to `bar`.
+
+Other than the access rules, two types of line can appear in the acesss accessdb.  A line of the form:
+
+{{{
+restricted: node_type
+}}}
+
+indicates that the use of `node_type` is not open to all users.  If a requester asks for access to a restricted node type and is mapped to a project that does not include access to that type, the `fedd` will deny the request.  To specify multiple such types, include multiple such lines.
+
+For exmaple if `node_type` is restricted and `(fedid:ce90957dd5b7d20f9c3890c4599313b7f1cf31ea,emulab-ops, faber)` makes an access request, that user will succeed if he or she matches:
+
+{{{
+(fedid:ce90957dd5b7d20f9c3890c4599313b7f1cf31ea,emulab-ops, faber) -> (emulab-ops:node_type, <same>, <same>)
+}}}
+
+but fail if the matching line is:
+
+{{{
+(fedid:ce90957dd5b7d20f9c3890c4599313b7f1cf31ea,emulab-ops, faber) -> (emulab-ops:pc3000, <same>, <same>)
+}}}
+
+A line of the form:
+
+{{{
+attribute: connectorImage value: FBSD7-TVF
+}}}
+
+specifies an attribute to be passed back to the requester.  In this case the attribute specifies that nodes used to connect this testbed to another federant should use local Emulab image FBSD7-TVF.  Attribute values start with the first non-whitespace character after '''value:''' and continue until the end of the line.
+
+Currently `fedd`'s experiment control system understands the following attributes:
+
+ '''!ConnectorImage'''::
+  The local image to load on federation connectors
+ '''!ConnectorType'''::
+  The Emulab node type to request for federation connectors.  For example, this type may have access to the wide area Internet when others do not.
+ '''!MasterConnectorStartCmd'''::
+  When this testbed is a master, run the given command on starting a federation connector node.
+ '''!MasterNodeStartCmd'''::
+  When this testbed is a master, run the given command on starting an experimental node.
+ '''!SlaveConnectorStartCmd'''::
+  When this testbed is a slave, run the given command on starting a federation connector node.
+ '''!SlaveNodeStartCmd'''::
+  When this testbed is a slave, run the given command on starting an experimental node.
+
+Generally the '''!StartCmd''' attributes do not need to be modified.