Changes between Version 30 and Version 31 of FeddCommands

Timestamp:

Jun 11, 2014 11:53:28 AM (10 years ago)

Author:

faber

Comment:

--

FeddCommands

@@ -87 +87 @@
 The `user_to_project.py` command exists to provide command line functionality that Emulab keeps in a web page.  It attaches a user to a project.  It is called by a `fedd` running on `boss` when a project is dynamically created.  Its default installation destination and the default value for the [experiment_control] parameter '''user_to_project''' both default to `/usr/local/bin/user_to_project.py`.  It is unlikely a user will ever need to run this command.
 
-=== ABAC Conversion Utilities ===
-
-There are several [wiki:FeddABAC#ConversionUtilities conversion utilities] for converting existing configurations to ABAC.
+=== ABAC Utilities ===
+
+There are several utilities for converting text-based configurations to ABAC and manipulating ABAC logic statements directly.
+
+=== fedd_to_abac.py ===
+
+{{{fedd_to_abac.py}}} converts an fedd experiment controller configuration into an ABAC configuration.  A certificate and key are required as well as an output directory for the ABAC authorizer (target of the '''auth_dir''' parameter in the configuration file.
+
+It takes the following arguments:
+  {{{--cert=}}}''file''::
+    A file containing an X.509 certificate in pem format.  This is the identity that will assert the attributes and should probably be the same as the experiment controller's identity.  It may be a combination certificate and key file.
+  {{{--key=}}}''file''::
+    The key for signing attributes.  It should be a pem file with an RSA key in it.  This can be omitted if {{{--cert}}} specifies a combination file.
+  {{{--dir=}}}''dir''::
+    The output directory for the authorizer.   (This must be an absolute pathname).
+
+  {{{--make_dir}}}::
+    If given, make the output directory.
+  {{{--debug}}}::
+    Just output the creddy commands that would be issued to create the certificates.
+  {{{--policy_only}}}::
+    Only output the ABAC certificates, not the full ABAC authorizer.  This is primarily for debugging.
+  {{{--update}}}::
+    Update the output directory rather than creating it.  This allows the authorizer to remember credentials it has learned or issued while updating the policy.
+
+After the named arguments are given, the [FeddDatabases#ExperimentControlComponentAccessDB aceess DB file] is a required argument.
+
+=== access_to_abac.py ===
+
+{{{access_to_abac.py}}} converts access controller policies into ABAC and generates a DB for mapping the derived attributes into an appropriate credential mapping database, the target of the '''accessdb''' configuration directive.  Keys and certificates are required parameters as well as a directory for the ABAC authorizer and a file for the access DB.
+
+It takes the following arguments:
+
+  {{{--cert=}}}''file''::
+    A file containing an X.509 certificate in pem format.  This is the identity that will assert the attributes and should probably be the same as the experiment controller's identity.  It may be a combination certificate and key file.
+  {{{--key=}}}''file''::
+    The key for signing attributes.  It should be a pem file with an RSA key in it.  This can be omitted if {{{--cert}}} specifies a combination file.
+  {{{--dir=}}}''dir''::
+    The output directory for the authorizer.   (This must be an absolute pathname).
+  {{{--type=}}}''type''::
+    The type of access controller used by the [FeddConfig#AccessOptions access_type] configuration directive.  Used to parse the various formats of the old accessDB.
+  {{{--quiet}}}::
+    Do not produce extra output
+  {{{--no_create_creds}}}::
+    Do not create the authorizer (debugging only)
+  {{{--file=}}}''old_accessdb''::
+    The accessDB to convert.  May also be specified as a bare parameter after the named parameters have been given.
+  {{{--mapfile=}}}''new_accessdb''::
+    The new accessDB to create.  It must be a different file name than the file being converted.
+  {{{--no_delegate}}}::
+    By default the ABAC created attributes include a layer of delegation for a standalone fedd running with a different principal.  Specifying this parameter eliminates a layer of delegation.  Even for single-user experiment controllers, this option is rarely necessary.
+  {{{--no_auth}}}::
+    Do not create an authorizer.  For debugging only.
+  {{{--debug}}}::
+    Just produce debugging output.
+
+If {{{--file}}} is not given, the [FeddDatabases#AccessComponentAccessDB accessDB] to convert must follow.
+
+=== dump_abac_authorizer.py ===
+
+The {{{dump_abac_authorizer.py}}} program prints the contenst of an abac authorizer.  It takes one parameter, the directory containing the authorizer, and prints the contents of the authorizer.  The first line is the keyid of the fedd that uses the authorizer.  Each line after that is an ABAC credential in RT0 logic (the logic described [http://groups.geni.net/geni/wiki/TIEDABACModel here]).
+
+For example:
+{{{
+$ dump_abac_authorizer.py abac/
+b9325180cc55b2af23bbfed6435d365449ab4afa
+b9325180cc55b2af23bbfed6435d365449ab4afa.new <- d18901f621eaa03507867212cd48c2b8d686d742
+b9325180cc55b2af23bbfed6435d365449ab4afa.create <- d18901f621eaa03507867212cd48c2b8d686d742
+b9325180cc55b2af23bbfed6435d365449ab4afa.faber <- d18901f621eaa03507867212cd48c2b8d686d742
+b9325180cc55b2af23bbfed6435d365449ab4afa.feduser <- d18901f621eaa03507867212cd48c2b8d686d742
+}}}
+
+=== import_abac_creds.py ===
+
+The import_abac_creds.py program adds ABAC credential held in X.509 certificates directly to an ABAC authorizer used by fedd.  This authorizer is created by either fedd_to_abac.py or access_to_abac.py.  The command takes an argument of the form:
+
+  {{{--dir=}}}''dir''::
+    The output directory for the authorizer.  (This must be an absolute pathname).
+
+The remaining parameters are a list of files containing the certificates to add.  These can be identity or attribute certificates.  To add an attribute certificate signed by issuer.pem and contained in attr.der to an authroizer in {{{/usr/local/etc/fedd/abac}}} the command is:
+
+{{{
+$ import_abac_creds.py --dir /usr/local/etc/fedd/abac issuer.pem attr.der
+}}}
+
+You can confirm the addition of the certificates using dump_abac_authorizer.py.
+
+=== cert_to_fedid.py ===
+
+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.
+
 
 == Command Line ==