GENI Reference Control Framework
================================


Description
===========

The GCF package implements a sample GENI Aggregate Manager. It also
includes a sample GENI Clearinghouse and command line test client. This
software is intended to demonstrate the GENI Aggregate Manager
API. The Omni command line tool is also included with the GCF package:
see README-omni.txt.


Installation & Getting Started
==============================

See INSTALL.txt for instructions on installing this package, and
the 4 step test run using the test client.
Omni users should follow those instructions to ensure software 
dependencies are met.

Software Dependencies
=====================

The GCF package is intended to be run on a modern Linux distribution
(circa 2010 or 2009). Python 2.6 is required. This software is not
Python 3 compatible.

This software requires a number of readily available software
packages. Most modern Linux distributions should have these packages
available via their native package management suite (eg. yum or apt).

For details, see INSTALL.txt.


Included Software
=================

This package includes software from PlanetLab. All of the PlanetLab
software is in the src/sfa directory. More information, including the
license, can be found in src/sfa/README.txt.


Usage Instructions
============

Basic install & running instructions are in INSTALL.txt.

Full details on options for each step are described below.

0. Edit gcf_config (typically in the current directory; find a
   template in gcf_config.sample) to configure your clearinghouse and
   aggregate manager.  The default values should be fine for most
   settings, but you may change the base_name (URN) to be specific
   to you.  The keys and certificates will be generated in
   src/gen-certs.py in Step 1 to the paths you enter in
   gcf_config.
 
1. Generate keys and certificates for your users, clearinghouse, and 
   aggregate manager.

   $ python src/gen-certs.py

   This creates keys and certificates for a clearinghouse (ch), an
   aggregate manager (am), and a researcher (alice).  Cert URNs and
   some privileges are modifiable via constants.  Note you can
   generate multiple AM credentials and multiple user credentials
   using this script.

   Note that you should customize the certificates generated at your
   site using the constants in gcf_config, if you will use these
   certificates to interact with any other GENI site. In particular,
   URNs must be globally unique.

   By default the gcf_config file is found in the local directory.
   Override the default locations by specifying the -f argument.

   A directory for trusted_roots is used or created, and your CH
   certificate is copied there. This directory is used in Federation (see
   below).

2. Start the clearinghouse server:

   $ python src/gcf-ch.py   
 
   To override the settings in gcf_config, you can use these command
   line options:

   $ python src/gcf-ch.py -r <ch-cert.pem or trusted_roots_dir/> \
                          -g ch-cert.pem -k ch-key.pem \
                          -c <path-to-gcf_config-file>

   The optional -r argument could be a file with the GCF CH
   certificate.  If you want to allow users from other Clearinghouses
   to make calls on this clearinghouse, install their root
   certificates too.  To support this, it should be a directory with
   all trusted / federated certificates (PEM format).  Note that the
   CH certificate is used in generating slice credentials.

   The gcf_config file am_* properties lists the Aggregate Managers that have
   federated with this Clearinghouse. For some other examples see
   src/geni/ch.py.  This is how a single gcf-ch can contact multiple
   AM API compliant agggregate managers from whatever control
   framework.  Aggregate URNs here are for human consumption and need
   not be accurate.

   By default the gcf_config file is found in the local
   directory. Override that by specifying the -f argument.

   Other optional arguments include -H to specify a full hostname, -p
   to listen on a port other than 8000, and --debug for debugging
   output.  Note that listening on localhost/127.0.0.1 (the default)
   is not the same as listening on a real hostname / IP address. Be
   sure to listen on the desired interface and address the Aggregate
   Manager / Clearinghouse consistently.

   Supply the --debug argument for more detailed logging.

   See the gcf_config clearinghouse section for relevant constants.  Note
   that slice URNs are globally unique, and constrained to be proper
   children of their Clearinghouse (Slice Authority).  Another
   constant you may want to change is the lifetime of Slice
   credentials. By default they last 7200 seconds. That is likely too
   short to actually use any allocated resources.
 
3. Start the aggregate manager server:

   $ python src/gcf-am.py
 
   To override the settings in gcf_config, you can use these command
   line options:

 $ python src/gcf-am.py -r <ch-cert.pem or trusted_chs_and_cas_dir/> \
                        -g am-cert.pem -k am-key.pem \
                        -c <path-to-gcf_config-file>

   By default the gcf_config file is found in the local
   directory. Override that by specifying the -f argument. See the
   aggregate_manager section.  Note in particular that you name your
   aggregate manager, and could generate multiple aggregate manager
   certificates by editing gcf_config and re-running gen-certs.

   NOTE: The -r ch-cert.pem option specifies the name of the file with
   the CH cert, or better still, a directory with all trusted root
   certs.
   These certs will be used to verify slices and resource requests
   from the control frameworks that you have federated with.

   Optional arguments include -H to specify a full hostname, -p to
   listen on a port other than 8001, and --debug for debugging output.
   Note that listening on localhost/127.0.0.1 (the default) is not the
   same as listening on a real hostname / IP address. Be sure to
   listen on the desired interface and address the Aggregate Manager /
   Clearinghouse consistently.

   You can also optionally specify the API version that this aggregate should
   implement, using the -V option. The default is API version 2, and
   valid values include 1, 2 and 3. If using gcf-test, be sure to
   supply a matching -V option to that script.
   Supply the --debug argument for more detailed logging.

4. Run the GCF installation testing client:

   $ python src/gcf-test.py
 
   To override the settings in gcf_config, you can use these command
   line options:

   $ python src/gcf-test.py -g alice-cert.pem -k alice-key.pem \
                            --ch https://localhost:8000/ \
                            --am https://localhost:8001/ \
                            -c <path-to-gcf_config-file>

   The output should show some basic API testing, and possibly some
   debug output. Errors will be marked by exception traces or
   'failed'.

   By default the gcf_config file is found in the local
   directory. Override that by specifying the -f argument.

   Optional arguments --debug and --debug-rpc enable more debug
   output.
   Optional argument -V allows specifying the AM API version to run
   against the specified aggregate: the default is 2, and valid values
   are 1, 2 or 3. Be sure it matches the -V value you supplied to gcf-am.

   Note that you can use user credentials from any federated control
   framework, as long as the appropriate CH certificates were supplied
   to the -r arguments to gcf-ch and gcf-am above.

5. See README-omni.txt for instructions on running the OMNI GENI
   Client. Omni is a command line tool for doing arbitrary
   commands against multiple Aggregate Managers.

6. Federating: Interacting with multiple Control Frameworks.
 
   With federation, a user from one control framework (or
   clearinghouse and slice authority) can use their
   certificate and slice credentials to allocate resources from
   aggregates affiliated with other control frameworks.  In a
   federated network, each clearinghouse lists to its users all of the
   known aggregate managers that its users can allocate from.  Second,
   each aggregate manager has a list of trusted root certificates for
   each federated control framework.

6.1 Sharing keys -- Do this for each Aggregate Manager

   For each Aggregate Manager that should accept credentials from your
   Clearinghouse:

   To add your GCF certificate to an SFA based aggregate manager, copy
   the CH certificate file (ch-cert.pem) to /etc/sfa/trusted_roots/ on
   the AM's server.
 
   After adding your certificates, restart sfa (sudo /etc/init.d/sfa
   restart).

   To add an SFA certificate to a GCF based aggregate manager, copy
   your SFA key from /etc/sfa/trusted_roots/<should be a .gid file> to
   your GCF trusted roots directory created in steps 2 and 3
   above. This is not particularly necessary for the Clearinghouse
   (gcf-ch), but is necessary for the Aggregate Manager (gcf-am).

   There is a similar for ProtoGENI (InstaGENI), FOAM, and Orca
   (ExoGENI) aggregates.

6.2 Listing Aggregates -- Do this on all peered clearinghouses

   To list your GCF AM to SFA users, add your GCF address to 
    	 /etc/sfa/geni_aggregates.xml.

   The form is 
       <aggregate addr="hostname" hrn="hrn" port="port" url="hostname:port"/>

   URL and addr/port are redundant, but fill in both.  The hrn can be
   anything, but its intent is to be a shorthand dotted notation of
   your URN, such as 'plc.princeton' or 'geni.gpo.bbn'. Be sure it is
   unique.

   To list your SFA aggregate manager in your GCF clearinghouse, edit
   the 'gcf_config' file in your root gcf/ directory and add an
   entry for the SFA AM. The form is documented in the sample file.
   Enter a new am_# property with a value like "URN,URL" (without quotes) with
   one such entry per line. An example is:

     'am_5 = urn:publicid:IDN+plc:gpo1+authority+sa, \
             http://sfa.gpolab.bbn.com:12348'

   The AM URN should be unique. While it need not be fully accurate, that
   is useful. You can find the AM URN using the openssl commandline:

     openssl x509 -in [cert of AM] -text | grep "urn:publicid:IDN"

   There is a similar for ProtoGENI (InstaGENI), FOAM, and Orca
   (ExoGENI) aggregates.


Further Reading
===============

The GENI API pages on the GENI wiki have full details on GENI identifiers,
credentials and certificates, and the GENI AM API.

See http://groups.geni.net/geni/wiki/GeniApi

Known issues, Omni tutorials and further documentation are on the GCF Wiki:
http://trac.gpolab.bbn.com/gcf