= Fedd Databases = There are several small databases that control how `fedd` operates. They are the various access databases that control which [FeddAuthorizationArchitecture#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. All of the formats allow comments that begin with # and ignore blank lines. == AccessDBs == The primary role of the various `fedd` accessDBs is to assign attributes to the [FeddAuthorizationArchitecture#GlobalIdentifiers:Fedids fedid]s or [FeddAuthorizationArchitecture#GlobalIdentifiers:Three-levelNames three-level name]s that a requester may assert. Those attributes control the access to services. A requester with the proper attribute may access the service, one without is denied. The access component and experiment control component accessDBs assign the attributes necessary for their services implicitly in conjunction with specifying mapping information inherent to the function. The other components' accessDBs are simple attribute assignments. Once these databases are constructed in text format, the [FeddCommands#access_to_abac.py access_to_abac.py] command needs to be run to convert them into a map pointed to by the '''access_db''' parameter in the configuration and the ABAC permissions, pointed to by the '''auth_dir''' parameter. === Access Component AccessDB === This is the most complex of the accessDBs. Its purpose is to configure how an access control component maps a [FeddAuthorizationArchitecture#GlobalIdentifiers:Three-levelNames three level name] to a authorization attribute and local access control information. Usually the authorization attribute information is 'access' implying the ability to create new experiments. Other plug-ins are free to create and interpret other attributes. In addition to that, a mapping can have local values, interpreted by the plug-in. By convention the attribute is unadorned and the optional plug-in dependent information is separated by a comma and enclosed in parentheses. The general format looks like: {{{ (testbed, project, user) -> attribute }}} With testbed dependent information: {{{ (testbed, project, user) -> attribute, (some, testbed, stuff) }}} Relevant attributes include: '''access''':: The right to access resources on this testbed. Without an mapping to local resources in the access component's accessDB, this attribute is useless. It is specified implicitly by inclusion in that DB. '''allocate''':: The right to allocate local resources through the internal remote interface. A `fedd` running on boss to allocate resources based on the decisions of a `fedd` running on users would grant the users `fedd` this attribute. '''create''':: The right to create an experiment on this `fedd`. Assigning this without an entry in the experiment control component's accessDB is not useful. Having the right without specifying a mapping to three-level name fill cause the creation to fail. '''split''':: The right to run the experiment splitter program on this `fedd`. Because the service at !http://users.isi.deterlab.net:23235 is open to anyone, this attribute is rarely allocated. ==== Emulab Mappings ==== 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) -> attribute, (local_project, local_creation_user, local_service_user) }}} The triple on the left is the three-level name. One of those fields must be a [FeddAuthorizationArchitecture#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 [FeddAuthorizationArchitecture#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) -> access, (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 `` which matches any value and `` which explicitly indicates the field is absent. Here are examples with those rules: {{{ (fedid:ce90957dd5b7d20f9c3890c4599313b7f1cf31ea, , bill) -> access, (fed, foo, bar) (fedid:ce90957dd5b7d20f9c3890c4599313b7f1cf31ea, , faber) -> access, (fed, baz, quux) (fedid:ce90957dd5b7d20f9c3890c4599313b7f1cf31ea, , ) -> access, (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). Any three-level name that does not match a rule in this DB is denied access. That is, any three-level name matching a rule in this database is granted the '''access''' attribute. On the local entity side, the special fields are `` which indicates that the corresponding value in the three-level name should be used as the local name and `` which indicates that a new project or user should be allocated for this access. For example: {{{ (fedid:ce90957dd5b7d20f9c3890c4599313b7f1cf31ea, Deter, ) -> access, (fed, foo, ) (fedid:ce90957dd5b7d20f9c3890c4599313b7f1cf31ea, , faber) -> access, (, , ) }}} 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 `` 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 `` all three must be, a restriction that will be relaxed in the future. If a rule with no `` fields matches, that rule is preferred to others with `` fields. If multiple `` fields match, the match with the fewest `` matches has precedence. An `` field cannot anchor a three-level matching rule (that it is, `` 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, ) -> access, (foo, , ) (fedid:ce90957dd5b7d20f9c3890c4599313b7f1cf31ea, , faber) -> access, (bar, , ) }}} 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`. ==== DRAGON Mappings ==== A dragon controller maps the [FeddAuthorizationArchitecture#GlobalIdentifiers:Three-levelNames three level name] to a directory holding the X.509 certificates to use for the allocation. In OSCARS command-line terms, it maps the requester to the '''repo''' parameter. This line; {{{ (fedid:ce90957dd5b7d20f9c3890c4599313b7f1cf31ea,emulab-ops, faber) -> access, (/usr/local/OSCARS/local_repo) }}} Maps the given three-level name to the keys stored in /usr/local/OSCARS/local_repo. That directory should be protected appropriately. ==== ProtoGENI Mappings ==== A dragon controller maps the [FeddAuthorizationArchitecture#GlobalIdentifiers:Three-levelNames three level name] to an X.509 certificate used to make GENI calls, an optional password for that certificate, and a username and ssh_key with rights to move files around on ProtoGENI for configuration of nodes. ProtoGENI supports less autometed installation than Emulab.This line; {{{ (fedid:ce90957dd5b7d20f9c3890c4599313b7f1cf31ea,emulab-ops, faber) -> access, (/usr/local/etc/fedd-config/protoGENI/ProtoGENI.pem, tied_user, /usr/local/etc/fedd-config/protoGENI/fedd_rsa, jhktsta) }}} Maps the given three-level name to a protogeni certificate called {{{/usr/local/etc/fedd-config/protoGENI/ProtoGENI.pem}}}. The user {{{tied_user}}} and the ssh key in {{{fedd_rsa}}} in the given directory will be used for configuration. The password for the certificate is the last entry. Because it contains passwords, this file should be readable only by the fedd user. === Experiment Control Component AccessDB === Like the access component accessDB, the experiment control component accessDB performs double duty - it both determines what [FeddAuthorizationArchitecture#GlobalIdentifiers:Fedids fedids] can be used to create experiments, and it determines what [FeddAuthorizationArchitecture#GlobalIdentifiers:Three-levelNames three-level name]s a `fedd` will assert on behalf of that user when acquiring access to other testbeds. Once this databases is constructed in text format, the [FeddCommands#fedd_to_abac.py fedd_to_abac.py] command needs to be run to convert them into the ABAC permissions, pointed to by the '''auth_dir''' parameter in the configuration file. Lines in the accessDB have the following format: {{{ fedid:xxx -> user fedid:xxx -> (project, user) }}} The top line says that the given fedid should be mapped to (`this_testbed`, , `user`), and the second line says that the given fedid should be mapped to (`this_testbed`, `project`, `user`), where `this_testbed` is the fedid of this `fedd`. If the same fedid appears on more than one line, any of the three-level name may be used on behalf of that requester. Currently `fedd` tries them all in an arbitrary order until one is granted access at each testbed. During an embedding a requester may be granted access to different testbeds under different three-level names. Any fedid not appearing in this databses is denied access to the experiment control facility; that is, a fedid in this DB is granted the '''create''' attribute. When an experiment is created, access to it is controlled independently of this database, so a fedid in this database does not automatically possess the right to terminate or interrogate an experiment they did not create. These rights are controlled by non-string attributes that are not specified in the databases. To simplify creating this database, the fedd package supplies a utility script, [FeddCommands#exp_access_db.py exp_access_db.py]. == Experiment Name Mapping DB == This DB controls how `fedd` maps the user annotations of the experiment nodes to the URI of the `fedd` controlling the testbed. It is a simple colon-separated text file where the annotation is on the left and the URI on the right. For example: {{{ deter:https://users.isi.deterlab.net:23235 ucb:https://users.ucb.deterlab.net:23235 }}}