CredentialCompiler README
#########################

The CredentialCompiler software allows a grid resource administrator to
generate the gridmap-file (Globus) or the UUDB (UNICORE). The
credentials are read from an LDAP database and converted to local
mappings using rules which are defined in the local rule file.
Therefore, an administrator has the full control over the mapping of
grid users to local accounts.

Starting with version 0.2, a rails-based portal is also available. Users
can specify their credentials and other contact information and request
access to the grid. A VO-User manager can then review the requests and
approve or decline - if the request is approved, the credential
information is propagated to the LDAP server. It is also possible to
delete the request later on. During all stages, the user will receive
emails on the current status of his request.

THEORY OF OPERATION
###################

The CredentialCompiler will walk over an LDAP tree in order to discover
the distinguished names a user will use to connect to grid resources.
Each user can have more than one DN associated - we use an LDAP schema
extension to store the DNs as strings with a "inetOrgPerson" object (see
contrib directory for the schema files).

The set of DNs is then checked against a locally defined ruleset to
determine how to map the grid accounts on local accounts. An
administrator can define mappings using regular expressions on the DNs
of the users - for example, it is possible to map all users from the
Fraunhofer ITWM on the itwmuser account with a rule

    /ou=ITWM,o=Fraunhofer/  itwmuser

Note that all regular expression operations are case insensitive. If no
mapping is present for a grid user, the site administrator will be
notified by email. A site administrator can build the rule database
incrementally, adding only those entries that are needed.

Finally, the DN-local user mappings are written to the middleware's
mapping files, either Globus or UNICORE. Those files can then be
distributed to the local resources (using scp or whatever tool you
prefer). The CredentialCompiler should be called frequently as a
cronjob.

INSTALLATION
############

The CredentialCompiler depends on the ruby language - your Linux
distribution should provide packages for you.

You need the following libraries:
- RubyGems
- log4r gem
- ruby/ldap from http://ruby-ldap.sourceforge.net/

I suggest the following installation procedure:
(1) Install Ruby (if you don't have it already installed)
    => http://www.ruby-lang.org/en/downloads/
(2) Install RubyGems
    => http://rubygems.org/read/chapter/3
(3) Use RubyGems to install the libraries:
    # gems install ruby-net-ldap log4r
(4) Install the CredentialCompiler, either via tar.gz or via the gem
file (which will check whether the libraries are installed correctly). 
You can get the files from the sf.net download page:

http://sourceforge.net/project/showfiles.php?group_id=183786

After unpacking, check the etc/ directory for configuration files. The
credentialcompiler.yml holds the configuration, and the rules.txt
contains the mapping database. Run the CredentialCompiler with 

    # bin/credentialcompiler.rb

You may also want to add the -h switch to see available options.

LICENSE
#######

The CredentialCompiler is open source software released under the GPL,
(c) 2006-2007 Mathias Dalheimer (md@gonium.net)


Version 0.1.0, 12/18/2006
#########################

- Initial release with minimal functionality.
- Unicore support is not integrated at the moment.
- Globus gridmapfile generation is supported.