= Plug-in Interfaces =

Access controllers respond to a series of standard calls from the experiment controller to create local allocations. These are described in conceptual detail [FeddPluginArchitecture elsewhere on this site] and in a [http://groups.geni.net/geni/attachment/wiki/TIEDProtoGENIPlugin/TIED_CF_plugin_design_spec_v1.0.pdf document about the design of the ProtoGENI plug-in].  This section discussed the calls and their encoding for developers interested in reading and extending existing plug-in code.

The interfaces are all described in xsd and SOAP, and these are easy enough to convert into python data structures [SoapToPython once you know how].  Below we describe the semantics of each call, and the tools available to plug-in writers to assist in implementation.  These tools are available when plug-ins derive from [source:fedd/trunk/federation/access.py federation.access], as [source:fedd/trunk/federation/skeleton_access.py federation.skeleton_access] is.

Each python method in the plug-in that corresponds to a plug-in interface is called with the same parameters:

 * the request: a python dict representing the parameters to the call as encoded in SOAP
 * the calling fid: a [source:fedd/trunk/federation/fedid.py fedid object] holding the caller's identity

Each method should return the python dict encoding the response or raise a [source:fedd/trunk/federation/service_error.py service_error] containing information about the error.  The service_error class contains error codes (in either the [source:wsdl/trunk/fedd_types.xsd XSD] or [source:fedd/trunk/federation/service_error.py python] definitions.

== Initialization ==

This is not an interface from the experiment controller, but we discuss it to mention the tools available for implementors.  These include routines to save state and interpret the standard parts of the [FeddDatabases#AccessComponentAccessDB access database], including specializing for testbed dependent data.  The method {{{read_access(file, local_info_parser)}}} takes the file to read and a function that takes the string following the access attribute and returns the local testbed attributes, stored into the self.access dict, keyed by the [FeddAbout#GlobalIdentifiers:Three-levelNames three-name] being authorized.  The {{{___init___()}}} routine of source:fedd/trunk/federation/skeleton_access.py federation.skeleton_access] includes an example of this.

In addition, the initializer of the [source:fedd/trunk/federation/access.py federation.access] base class parses standard parameters from {{{[access]}}} section from the configuration file.  The fields and corresponding class instance attributes are:

 '''cert_file'''::
  The certificate file that contains the [FeddAbout#GlobalIdentifiers:Fedids fedid] that identifies this access controller.  It is stored in {{{self.cert_file}}}.
 '''cert_pw'''::
  Password for the certificate file, if any.  Stored in {{{self.cert_pw}}}.
 '''trusted_certs'''::
  Certificates used to validate the signatures of other fedd principals.  Generally unused.  Stored in {{{self.trusted_certs}}}.

Those first three attributes are initialized by the {{{[access]}}} section, if given, or {{{[globals]}}}, if not.
 '''access_state'''::
  The file storing persistent state.  Stored in {{{self.state_file}}}.
 '''certdir'''::
  Directory to store local certificates for allocations in.  Stored in {{{self.certdir}}}.
 '''project_priority'''::
  Affects the standard access lookup routines by preferring matches on project if true.  Stored in {{{self.project_priority}}}, though most implementations will not need to access it.
 '''create_debug'''::
  Intended to keep the plug-in from making any persistent changes to the facility.  Plug-in writers are expected to honor it.  It is stored in {{{self.create_debug}}}.
 '''leave_tmpfiles'''::
  Intended to tell the plug-in not to delete temporary files.  Plug-in writers are expected to honor it.  Stored in {{{self.cleanup}}}, negated; that is if '''leave_tempfiles''' is false in the configuration {{{self.cleanup}}} is true.  {{{self.cleanup}}} defaults to true.
 '''type'''::
  Distinguishes between sub-types of the plug-in.  Stored in {{{self.access_type}}}; semantics are up to the plug-in writer.
 '''log_level'''::
  The level of log entries to pass to the logger.  Any of the values in [http://docs.python.org/library/logging.html the standard python logging choices] are acceptable.  It is only stored as internal state of {{{self.log}}}, a logger allocated by the initializer.

Finally, the default initializer allocates a Lock to be acquired when accessing persistent state and reads that state from {{{self.state_file}}}.

The plug-in initializer is largely plug-in depenent, but must also set the methods to be called for each interface call in the {{{self.soap_services}}} and {{{self.xmlrpcservices}}} dicts.  

== !RequestAccess ==

The !RequestAccess command asks the testbed to map the [FeddAbout#GlobalIdentifiers:Three-levelNames three-level name] on the call into local permissions and to do any bookkeeping associated with later attachment of resources to that allocation.  Specifically, a [http://fedd.isi.deterlab.net/trac/wiki/FeddAbout#GlobalIdentifiers:Fedids fedid] must be created.  Requests from this allocation back to the central experiment controller will be made under that principal/fedid.  Such requests gather configuration information or parameters passed between sub-experiments during creation.  The per-allocation fedid allows fine-grained control of access to thie information at the experiment controller, as well as the ability to name (and therefore request operation on) the various allocations made on this plug-in.

A !RequestAccess message has the following format:

{{{
request = {
    # list of strings of the form user:name project:name (these will be replaced by ABAC credentials in fedd 3.1)
    'credential': [ 'user:u', 'project:p' ]
    # Requested services
    'service': [
        # Each of these has an identifier, service name, server (optional), and a list of attributes as service parameters
        { 'id': '0001', 'name': 'project_export', 'visibility': 'export', 'fedAttr: [ { 'attribute': 'att_name', 'value': 'val1'} ] }
    ],
}
}}}

The credentials are opaquely and correctly handled by the [source:fedd/trunk/federation/access.py access controller base class].  Service requests encode the various [FeddAbout#ExperimentServices services] that the facility will be asked for in this allocation.

There are also some scheduling fields that are for future expansion.  The DETER experiment controller never includes them.

The response message has the form:

{{{
response = {
    'allocID': { 'fedid': fedidobj },
    'service': [
        # The meta service 'export_project' in the request has become 2 actual service descriptions with the same ID as the request 
        { 'id': '0001', 'name': 'SMB', 'visibility': 'export', 'fedAttr: [ { 'attribute': 'att_name', 'value': 'val1'} ] } ] },
        { 'id': '0001', 'name': 'userconf', 'visibility': 'export', 'fedAttr: [ { 'attribute': 'att_name', 'value': 'val1'} ] },
     ]
}
}}}

The response includes the fedid of the allocation and the actual services exported.  Note that in the example the single '''export_project''' request has become 2 specific service exports.  See the [sources:fedd/trunk/federation/emulab_access.py emulab plug-in] for an example of how services are decoded and managed.