\documentclass[]{article}
\usepackage[dutch,english]{babel}
\usepackage{url}

%\usepackage[pdftex,colorlinks]{hyperref}
%\usepackage{html}
%\usepackage{graphicx}
%\usepackage{moreverb}
%\usepackage{alltt}
%\include{lcmaps_include}

%
% Start document
%
\begin{document}

%
% titlepage and table of contents
%
\begin{titlepage}
\begin{center}
\textsc{\LARGE LCMAPS}\\[1.5cm]
\textsc{\Large version 1.5.0}\\[1.5cm]
\hrule \vspace{0.4cm}
{\huge \bfseries Local Credential Mapping Service } \\[0.4cm]
\hrule \vspace{1.5cm}
\emph{Author:}\\
Oscar \textsc{Koeroo}

\vfill

{\large \today}

\end{center}
\end{titlepage}



%
% All the chapters
%

\section{Introduction}
The LCMAPS framework is designed to take various credentials as input, e.g. a
certificate and/or VOMS\footnote{Virtual Organization Management System by INFN
CNAF} credentials, and map them to Unix credentials as output. Unix credentials
are the basic POSIX credentials, i.e. User ID, Group ID and Secondary Group
IDs. LCMAPS is a framework that can load and run one or more 'credential
mapping' plugins.  The framework will load and run plugins to perform the
identity mapping. Site and organizations can create their own new functionality
by creating new plugins. The LCMAPS framework exposes various APIs to push
credentials into the framework and to get the account mapping results in
return. The \emph{lcmaps.db} configuration file configures the LCMAPS plugins
and configures the order in which the plugins are launch. Some practical
examples are shown below.

LCMAPS is used by \emph{gLExec}, the \emph{lcas-lcmaps-gt4-interface} to
interface with a Globus GT4 and GT5 Gatekeeper, GridFTP daemon and
GSI-OpenSSHd, in StoRM and somewhere in Xrootd.


\section{History}
The Gridification subtask of WP4 of the European Datagrid
project\footnote{European DataGrid: http://www.eu-datagrid.org} interfaces the
local fabric to other middleware components by a number of services, among
which the Local Centre Authorization Service (LCAS) handles authorization
requests to the local computing fabric and the Local Credential Mapping Service
(LCMAPS) provides all local credentials needed for jobs allowed into the
fabric.  This document describes a prototype version of LCMAPS, which is the
second component released by the Gridification subtask, the first being LCAS.


\section{The frameworks inner working and plugins}
When an application intializes LCMAPS the plugins will be loaded based on the
\emph{lcmaps.db} configuration file.  The application can use one of the APIs
to provide credentials as input. The loaded plugins will be executed in the
sequence described in the same \emph{lcmaps.db} configuration file. 

During a plugin's execution it has access to the credential data in the
LCMAPS core memory. The plugin is also capable of writing credential mapping
results in LCMAPS. The plugins can each resolve a part of the mapping and they
can also perform actions based on these (intermediate) results, e.g. run
setuid, setgid and setgroup calls or interact with an LDAP service.

The plugins are executed in a state machine. When a plugin finishes succesfully
it can execute a different next plugin then when it failed. This allows LCMAPS
to pass different plugins to resolve a credential mapping.


\section{Installation}
The easiest way of installing LCMAPS is to use the \emph{EPEL}, \emph{Debian},
\emph{Etics} or Nikhef software repositories\footnote{Nikhef software
repository: http://software.nikhef.nl/}. The installation experience is similar
when manually build from a tarbal with the command: \verb!./configure && make && sudo make install!.
When you've downloaded the software from our Subversion
repository the \verb!./bootstrap!  command is mandatory.

The software will be installed in the following system default locations. The locations can be altered at ./configure time or the system might have different default location specified then Debian and/or Fedora systems:
\begin{list}{}{}
    \item [/usr/lib\{64\}/] The core library files will be located here. This includes the front-end API implementing libraries.
    \item [/usr/lib\{64\}/lcmaps/] This is the default path for all the LCMAPS plugins. The same directory is used to hold the LCMAPS plugins.
    \item [/etc/lcmaps/] The configuration file \emph{lcmaps.db} will be placed in this directory by default.
    \item [/usr/share/doc/lcmaps-\$\{version\}] The documentation and example files will be located here.
\end{list}

\subsection{Dependencies}
The dependencies of LCMAPS are:
\begin{list}{}{}
    \item vomsapi 1.6 or higher
    \item Globus 2.x through Globus 5.x. Older version of Globus are known to work.
    \item OpenSSL 0.9.7 through 1.0
\end{list}


\subsection{Custom configure options}
The LCMAPS \emph{configure} script is trying a few methods on finding the depending libraries on the system, including pkg-config. To be able to work with non-system distribution provided installation or personal compiles explicitly we provide several \emph{configure} options to work with:
\begin{list}{}{}
    \item [--enable-headers] This switch will only build and install or distribute the header files to LCMAPS. The header files will contain the required type definitions for both the front-end/application interface as also the plugin interface. 
    \item [--enable-gsi-mode] This option is \emph{on} by default and will build LCMAPS against the GSI interface libraries and OpenSSL. Switch this option to \emph{no} to create the \emph{lcmaps-without-gsi} flavor of LCMAPS.
    \item [--enable-osg] This option is \emph{off} by default. This option is used in the Open Science Grid build-flavor and will explicitly switch off the VOMS Attribute Certificate verification in the VOMS-api. This is to overload a default failure condition when the VOMS api could not verify the VOMS credentials. Note: Only enable this option if your infrastructure's security does not depend on the VOMS AC verification at all service nodes.
    \item [--with-globus-prefix=PFX] Allows you to select an alternative location to find the Globus headers and libraries needed to build LCMAPS.
    \item [--with-globus-libdir=DIR] Allows you to select an alternative directory for the Globus libraries. The default behaviour is to use the \$PFX setting of the previous option and add /lib, e.g. \$PFX/lib or \$PFX/lib64
    \item [--with-globus-thr-flavor=FLAVOR] Sets the threaded flavor of Globus. This is not needed in Globus 5 (and up) installation.
    \item [--with-globus-nothr-flavor=FLAVOR] Sets the non-threaded flavor of Globus. This is not needed in Globus 5 (and up) installation.
    \item [--with-voms-prefix=PFX] Sets the directory where LCMAPS should look for the VOMS api libraries. The default is in /usr
    \item [--with-voms-includes=DIR] Override to the default \$VOMS\_PFX/include directory to look for the required VOMS header files. 
    \item [--with-voms-libdir=DIR] Override to the default \$VOMS\_PFX/lib or \$VOMS\_PFX/lib64 directories to look for the required VOMS libraries.
\end{list}


\section{Common used paths}
Here is a small list of commonly used files and paths used in the context of LCMAPS and its plugins. It's important to know that these paths are not created by LCMAPS.

\begin{list}{}{}
    \item [/etc/grid-security/grid-mapfile] DN-based or VOMS FQAN-based auhtorization and mapping file used by various plugins. It maps DNs and/or FQANs to user accounts.
    \item [/etc/grid-security/vomapfile] Meant to be exclusively used as VOMS FQAN-based auhtorization and mapping file used by VOMS-specific various plugins. It maps FQANs to user accounts.
    \item [/etc/grid-security/groupmapfile] VOMS FQAN-based auhtorization and mapping file used by various VOMS plugins. It maps (secondary) Unix groups.
    \item [/etc/grid-security/vomsdir/] The VOMS directory will hold the VOMS .lsc files and/or PEM files to authenticate the VOMS Attributes Certificates. Subdirectories are named by the VO name and scope the .lsc and PEM files in their authentication to one particular VO.
    \item [/etc/grid-security/certificates/] The Certificate Authority (CA) directory filled with the supported CAs. It also contains the Certificate Revocation List (CRL) files and (Subject DN) signing namespace files of the CAs.
    \item [/etc/grid-security/gridmapdir/] The directory where all the user account mappings are held made by LCMAPS plugins that support the mapping of pool accounts. It will make a hardlink between a file entry representing the (Unix) account and the (encoded representation of the) certificate subject DN. The link is persistent and should be seen as a database that exposes the link between the Grid identity and the Unix identity.
    \item [/etc/grid-security/groupmapdir/] A similarly purposed directory, explicitly used by a VOMS-aware plugin that maps FQANs to a pool of (Unix) groups.
\end{list}


\section{Control through environment variables}
The library can be steered using environment variables used in the running process. It's important to understand that plugins can use an additional set of environment variables for plugins specific purposes. Feature overloading the following set of environment variables is not adviced.

\begin{list}{}{}
    \item [GATEKEEPER\_JM\_ID] Extra Gatekeeper log message to be able to more easily track a Job Manager ID.
    \item [GLOBUSID] See \$GATEKEEPER\_JM\_ID.
    \item [JOB\_REPOSITORY\_ID] See \$GATEKEEPER\_JM\_ID, but explicitly for the purpose of the LCMAPS Job Repository plugin.
    \item [LCMAPS\_DB\_FILE] Override the build-in default filename for the \emph{lcmaps.db} configuration file with the value of this environment variable.
    \item [LCMAPS\_DEBUG\_LEVEL] Tune the logging output cut off level. The numbers reasemble the numbers as used in previous released in the range 1-5. However, since LCMAPS version 1.5.0 these numbers resemble a numberically shifted Syslog number.
    \begin{list}{}{}
        \item [0] Silent logging, no messages will be written to file or Syslog.
        \item [1] All messages with a priority of BLOG\_ERR are written to file or Syslog. More severe error messages are squashed down to the LOG\_ERR priorirty. This is to prevent Syslog from blocking on default configurations and to prevent Syslog from broadcasting LCMAPS related messages on the connected TTYs when old plug-ins are used.
        \item [2] All messages with a priority of LOG\_WARNING or more severe, i.e. LOG\_ERR, are written to file and/or Syslog.
        \item [3] All messages with a priority of LOG\_NOTICE or more severe, i.e. LOG\_ERR or LOG\_WARNING, are written to file and/or Syslog. This is the default advertised setting for the lcas-lcmaps-gt-interface and glexec. The "FINAL CRED" messages are written on LOG\_NOTICE and indicate the resulting LCMAPS mapping from an X.509 and/or VOMS credential to a Unix/POSIX credential.
        \item [4] All messages with a priority of LOG\_INFO or more severe, i.e. all messages between (and including) LOG\_ERR and LOG\_INFO, are written to file and/or Syslog. This value is the build-in default. The success or failures of plug-ins are written on LOG\_INFO. To see the flow of plug-ins this log level is the advised log level to set.
        \item [5] All messages with a priority of LOG\_DEBUG or more severe, i.e. all messages between (and including) LOG\_ERR and LOG\_DEBUG, are written to file and/or Syslog. This is the most verbose mode and should be used carefully as the amount of information flowing from here might hinder normal operation performance if the syslogd isn't able to keep up.
    \end{list}
    \item [LCMAPS\_DIR] The base directory of the \$LCMAPS\_DB\_FILE parameter. This variable is concatinated with the \$LCMAPS\_DB\_FILE
    \item [LCMAPS\_ETC\_DIR] See \$LCMAPS\_DIR
    \item [LCMAPS\_LOG\_FILE] Overrides the build-in default file path to log the output to. When set, the logging will not go to Syslog.
    \item [LCMAPS\_LOG\_STRING] Prepend all log output messages with value of this environment variable
    \item [LCMAPS\_MODULES\_DIR] Directory to search for the LCMAPS plugins (or modules). Same as the \emph{path} option in the \emph{lcmaps.db} file..
    \item [LCMAPS\_POLICY\_NAME] A colon separated list of LCMAPS plugin execution policies. When this environment variable is present, only the listed execution policies will be executed. They will be executed in the order as writen in the \emph{lcmaps.db} file (from top to bottom).
    \item [LCMAPS\_VERIFY\_TYPE] Depricated
    \item [LCMAPS\_VOMS\_EXTRACT] Depricated
    \item [LCMAPS\_X509\_CERT\_DIR] Specific setting equal to the \$X509\_CERT\_DIR environment variable
    \item [LCMAPS\_X509\_VOMS\_DIR] Specific setting equal to the \$X509\_VOMS\_DIR environment variable
    \item [X509\_CERT\_DIR] The directory where all the CA files, e.g. CA certificate and CRL files, are located. The default location is: /etc/grid-security/certificates/.
    \item [X509\_VOMS\_DIR] This VOMS directory will hold the VOMS .lsc files and/or PEM files to authenticate the VOMS Attributes Certificates. Subdirectories are named by the VO name and scope the .lsc and PEM files in their authentication to one particular VO. The default location is: /etc/grid-security/vomsdir/.
\end{list}


\section{Configuration}
The default configuration file for LCMAPS is \emph{lcmaps.db}. This file defines the plug-in configurations and policy definitions as used by tools like gLExec and a Globus GridFTPd\footnote{The GridFTP daemon will need to be extended with the lcas-lcmaps-gt4-interface library}. As it is impossible to provide a default configuration that a) makes sense and b) doesn't require at least one plug-in that is not strictly required in every case. A few commonly used configration will be explained. The system administrator should pick and choose which parts are needed. The selected plug-ins are provided in separate packages.

For more information, see lcmaps.db(5) and the documentation for each individual plugin, or go to \url{http://www.nikhef.nl/pub/projects/grid/gridwiki/index.php/Site_Access_Control}


\subsection{gLExec example}
\small
\begin{verbatim}
## Documentation example for gLExec
##
## The default path where modules are looked for. Do not change this.

path = /usr/lib64/lcmaps

## ======================================================================
## Section: PLUG-INS
## ======================================================================

## Tracking group plug-in
##
## The Tracking Group ID plug-in can reattach secondary Group IDs from
## the calling user to the mapped user account. This is to ensure that
## special tracking group IDs, attached by the batch system to a running
## job, also remain when e.g. gLExec is switching the Unix/POSIX process
## ownership.
## The tracking group plug-in can either preserve a fixed range of Unix
## Group IDs or can auto-discover tracking GIDs. The auto-discover works
## by assuming tracking GIDs are 'nameless', but should be used with
## care.

# tracking_groupid = "lcmaps_tracking_groupid.mod"
#                        "--tracking-groupid-min MINGID"
#                        "--tracking-groupid-max MAXGID"

## verify-proxy
##
## The lcmaps_verify_proxy plugin verifies the validity of a proxy chain
## and (optionally) a valid delegation, including restrictions on the
## life time of any proxies in the chain. 
## For more informaation about this plugin: 
##    http://www.nikhef.nl/pub/projects/grid/gridwiki/index.php/Verify-proxy

## verify_proxy    = "lcmaps_verify_proxy.mod" 
##                       " -certdir /etc/grid-security/certificates/"
##                       " --allow-limited-proxy"

## Posix enforcement plug-in
## 
## The posix_enf plug-in takes the mapping as returned by earlier
## plug-ins and changes the user's identity according to the mapping,
## including any mapped secondary group ids. This is usually the last
## step in the chain.

# posix_enf        = "lcmaps_posix_enf.mod"
#                        "-maxuid 1"
#                        "-maxpgid 1"
#                        "-maxsgid 32"

## 
## VOMS local group mapping
## 
## The voms_localgroup plugin will map the VOMS FQANs (Fully Qualified
## Attribute Names) to one or more locally known groups by matching each
## FQAN to a line in the groupmapfile.

# vomslocalgroup   = "lcmaps_voms_localgroup.mod"
#                        "-groupmapfile /etc/grid-security/groupmapfile"
#                        "-mapmin 0"

## VOMS pool account mapping
## 
## The voms_poolaccount plug-in maps FQANs to pool users, just like
## the plain poolaccount plug-in maps DNs.

# vomspoolaccount  = "lcmaps_voms_poolaccount.mod"
#                        "-gridmapfile /etc/grid-security/grid-mapfile"
#                        "-gridmapdir /etc/grid-security/gridmapdir"


## ======================================================================
## Section: POLICIES
## ======================================================================
##
## The policies are labeled, and gLExec will use the policy named in
## glexec.conf(5); if no policy is declared the first one will be used.

## One of the simplest policies is to verify the validity of the user
## proxy, and mapping the DN to a local account in
## /etc/grid-security/grid-mapfile.  This is the easiest setup to
## handle just a few users.  The verify_proxy and localaccount
## plug-ins in the plug-in section should be uncommented, and the
## lcmaps-plugins-basic package must be installed.

vomsawarelocalmapping:
verify_proxy -> vomslocalgroup
vomslocalgroup -> vomspoolaccount
vomspoolaccount -> tracking_groupid
tracking_groupid -> posix_enf | posix_enf

\end{verbatim}
\normalsize


\subsection{GridFTPd example}


\small
\begin{verbatim}
## Documentation example for gLExec
##
## The default path where modules are looked for. Do not change this.

path = /usr/lib64/lcmaps

## ======================================================================
## Section: PLUG-INS
## ======================================================================

## Posix enforcement plug-in
## 
## The posix_enf plug-in takes the mapping as returned by earlier
## plug-ins and changes the user's identity according to the mapping,
## including any mapped secondary group ids. This is usually the last
## step in the chain.

# posix_enf        = "lcmaps_posix_enf.mod"
#                        "-maxuid 1"
#                        "-maxpgid 1"
#                        "-maxsgid 32"

## 
## VOMS local group mapping
## 
## The voms_localgroup plugin will map the VOMS FQANs (Fully Qualified
## Attribute Names) to one or more locally known groups by matching each
## FQAN to a line in the groupmapfile.

# vomslocalgroup   = "lcmaps_voms_localgroup.mod"
#                        "-groupmapfile /etc/grid-security/groupmapfile"
#                        "-mapmin 0"

## VOMS pool account mapping
## 
## The voms_poolaccount plug-in maps FQANs to pool users, just like
## the plain poolaccount plug-in maps DNs.

# vomspoolaccount  = "lcmaps_voms_poolaccount.mod"
#                        "-gridmapfile /etc/grid-security/grid-mapfile"
#                        "-gridmapdir /etc/grid-security/gridmapdir"


## ======================================================================
## Section: POLICIES
## ======================================================================
##
## The policies are labeled, and vomsawarelocalmapping is the first and 
## only label

vomsawarelocalmapping:
vomslocalgroup -> vomspoolaccount
vomspoolaccount -> posix_enf

\end{verbatim}
\normalsize


\section{Debugging LCMAPS}
LCMAPS will typically be logging in the same location as the service or tool that is initiating the LCMAPS library and its plugins. The plugin log records are embedded in the LCMAPS main framework logrecords.

To start debugging a problem in LCMAPS, we recommend to look at the log file and increase the logging verbosity ultimately to level "5" by using the \emph{LCMAPS\_LOG\_LEVEL}. You can now see the plugins loading succesfully:
\small
\begin{verbatim}
lcmaps_log_open(): setting debugging level to 5 
lcmaps.mod-lcmaps_startPluginManager(): doing lcmaps_startEvaluationManager(/etc/lcmaps/lcmaps-glexec.db) 
Checking policy 'localonly' for recursions. 
No recursions were found. 
[...]
lcmaps.mod-lcmaps_startPluginManager(): initializing plugin /usr/lib64/lcmaps/lcmaps_verify_proxy.mod (db entry 0) 
lcmaps.mod-PluginInit(): found "plugin_initialize()" 
lcmaps.mod-PluginInit(): found "plugin_run()" 
lcmaps.mod-PluginInit(): found "plugin_terminate()" 
lcmaps.mod-PluginInit(): found "plugin_introspect()" 
lcmaps.mod-PluginInit(): found "plugin_verify()" 
lcmaps.mod-PluginInit(): creating first pluginlist entry 
[...]
\end{verbatim}
\normalsize

The start of an mapping request initiated using the LCMAPS PEM and return account API. When available the LCMAPS framework will also pre-load its memory with VOMS credentials, of which a summary is given here. Note: This feature depricates the LCMAPS VOMS extract plugin:
\small
\begin{verbatim}
Using "lcmaps_run_with_pem_and_return_account" interface of LCMAPS 
Got individual certificate with subject: /O=dutchgrid/O=users/O=nikhef/CN=Oscar Koeroo/CN=proxy 
 lcmaps_x509_to_voms_fqans(): voms data structure initialized 
 lcmaps_x509_to_voms_fqans(): setting voms data for VO == dteam 
 lcmaps_x509_to_voms_fqans(): setting voms data for VO server == /C=GR/O=HellasGrid/OU=hellasgrid.gr/CN=voms.hellasgrid.gr 
 lcmaps_x509_to_voms_fqans(): TYP_STD 
lcmaps_get_attributes: found 0 generic attributes.  
 lcmaps_x509_to_voms_fqans(): extracted '0' generic voms attributes  
 lcmaps_x509_to_voms_fqans(): Success, VOMS destroy 
 print_lcmaps_vomsdata(): lcmaps_vomsdata->voms[ 1 / 1 ] 
 print_lcmaps_vomsdata(): lcmaps_vomsdata->voms[1].user_dn           : /O=dutchgrid/O=users/O=nikhef/CN=Oscar Koeroo 
 print_lcmaps_vomsdata(): lcmaps_vomsdata->voms[1].user_ca           : /C=NL/O=NIKHEF/CN=NIKHEF medium-security certification auth 
 print_lcmaps_vomsdata(): lcmaps_vomsdata->voms[1].voms_issuer_dn    : /C=GR/O=HellasGrid/OU=hellasgrid.gr/CN=voms.hellasgrid.gr 
 print_lcmaps_vomsdata(): lcmaps_vomsdata->voms[1].voms_issuer_ca    : /C=GR/O=HellasGrid/OU=Certification Authorities/CN=HellasGrid CA 2006 
 print_lcmaps_vomsdata(): lcmaps_vomsdata->voms[1].uri               : voms.hellasgrid.gr:15004 
 print_lcmaps_vomsdata(): lcmaps_vomsdata->voms[1].date1             : 20110421100431Z 
 print_lcmaps_vomsdata(): lcmaps_vomsdata->voms[1].date2             : 20110422100431Z 
 print_lcmaps_vomsdata(): lcmaps_vomsdata->voms[1].voname            : dteam 
 print_lcmaps_vomsdata(): lcmaps_vomsdata->voms[1].fqan_unix[ 1 / 1 ] 
 print_lcmaps_vomsdata(): lcmaps_vomsdata->voms[1].fqan_unix[1].fqan : /dteam/Role=NULL/Capability=NULL 
 print_lcmaps_vomsdata(): lcmaps_vomsdata->voms[1].fqan_unix[1].uid  : -1 
 print_lcmaps_vomsdata(): lcmaps_vomsdata->voms[1].fqan_unix[1].gid  : -1 
lcmaps.mod-lcmaps_credential_store_x509(): Found LCMAPS vomsdata structure, adding it to the lcmaps_credentials. 
[...]
\end{verbatim}
\normalsize

Each of the plugins will be loaded in the sequence described in the configuration section. Here is an example of the LCMAPS Verify Proxy plugin.
\small
\begin{verbatim}
lcmaps.mod-lcmaps_runPluginManager(): Do lcmaps_runEvaluationManager() 
evaluationmanager: found plugin: /usr/lib64/lcmaps/lcmaps_verify_proxy.mod 
evaluationmanager: Resetting credential data. 
lcmaps.mod-lcmaps_resetCredentialData(): Called 
lcmaps.mod-lcmaps_runPlugin(): looking for plugin /usr/lib64/lcmaps/lcmaps_verify_proxy.mod 
lcmaps.mod-lcmaps_runPlugin(): found plugin /usr/lib64/lcmaps/lcmaps_verify_proxy.mod 
lcmaps.mod-lcmaps_runPlugin(): running plugin /usr/lib64/lcmaps/lcmaps_verify_proxy.mod 
 lcmaps_plugin_verify_proxy-plugin_run(): 
 lcmaps_plugin_verify_proxy-plugin_run(): found X.509 chain. 
 lcmaps_plugin_verify_proxy-plugin_run(): found PEM string 
 lcmaps_plugin_verify_proxy-plugin_run(): found lcmaps voms_data_list placeholder. 
 lcmaps_plugin_verify_proxy-plugin_run(): vomsdata->nvoms = 1 
 lcmaps_plugin_verify_proxy-plugin_run(): vomsdata->voms = 19f9f500 
 lcmaps_plugin_verify_proxy-plugin_run(): vomsdata->voms[0] = 0 
 lcmaps_plugin_verify_proxy-plugin_run(): vomsdata->voms[0].userdn = /O=dutchgrid/O=users/O=nikhef/CN=Oscar Koeroo 
Debug:   --- Reading the Private Key From PEM --- 
Info:    Reading PEM string 
Debug:   Reading Private key 
Debug:   --- Welcome to the grid_verifyCert function --- 
Info:    Using CA Directory: /etc/grid-security/certificates/ 
[...]
\end{verbatim}
\normalsize

At the end of each plugin execution the LCMAPS framework will log if the module ended succesfully or not. This is important to understand the execution/control flow of the plugins by LCMAPS.
\small
\begin{verbatim}
[...]
lcmaps_runEvaluationManager: running plugin: /usr/lib64/lcmaps/lcmaps_verify_proxy.mod. 
                    : result true. 
\end{verbatim}
\normalsize

At the end of the exeuction of the LCMAPS framework a summary will be printed. The following example didn't map the user based on the VOMS FQANs but only on the DN to a \emph{uid} (Unix User ID) and \emph{pgid} (Unix primary Group ID):
\small
\begin{verbatim}
LCMAPS CRED FINAL: DN:"/O=dutchgrid/O=users/O=nikhef/CN=Oscar Koeroo"->mapped uid:'539',pgid:'100' 
lcmaps.mod-lcmaps_run_with_pem_and_return_account(): LCMAPS found no secondary groups 
\end{verbatim}
\normalsize

%
% Finish
%
\end{document}


O
OOO
The local credentials that are gathered (UNIX uids, gids, VO information, AFS/Kerberos (?) tokens),
are stored internally, but a new WP4 component, the job repository, is foreseen in which these
credentials may be stored as well and which is accessible by other applications and services.
The following LCMAPS plugins are currently available:
\bi
\item plugins providing the functionality that is equivalent to the functionality of the original
gatekeeper:
	\bi
	\item \texttt{lcmaps\_localaccount.mod} (\textbf{A}):
	    this plugin collects the local account name from a \emph{gridmap} file.
	    \htmladdnormallink{More info ...}{apidoc/html/lcmaps_localaccount.mod.html}
	\item \texttt{lcmaps\_poolaccount} (\textbf{A}):
	    this plugins collects a pool account name from a \emph{gridmap} file (leases in \$GRIDMAPDIR).
	    \htmladdnormallink{More info ...}{apidoc/html/lcmaps_poolaccount.mod.html}
	\item \texttt{lcmaps\_posix\_enf.mod} (\textbf{E}):
	    this plugin enforces the local credentials in the running process
	    by posix system calls (setuid(), setgid() etc.).
	    \htmladdnormallink{More info ...}{apidoc/html/lcmaps_posix_enf.mod.html}
	\item \texttt{lcmaps\_ldap\_enf.mod} (\textbf{E}):
	    this plugin enforces the local credentials by setting the primary and 
	    secondary gids in the LDAP database that is used by the site
	    as the source of account information for PAM or NSS.
	    \htmladdnormallink{More info ...}{apidoc/html/lcmaps_ldap_enf.mod.html}
	\ei
\item plugins that use the VOMS (VO Membership Service)
attribute assertions in the user certificate for the credential mapping.
	\bi
	\item \texttt{lcmaps\_voms.mod} (\textbf{A}):
	    this plugin extracts the VOMS information from the user X509 proxy
	    certificate.
	    \htmladdnormallink{More info ...}{apidoc/html/lcmaps_voms.mod.html}
	\item \texttt{lcmaps\_voms\_localgroup.mod} (\textbf{A}):
	    this plugin tries to find a local group Id (gid) based on the VO information
	    and a \emph{groupmapfile}.
	    \htmladdnormallink{More info ...}{apidoc/html/lcmaps_voms_localgroup.mod.html}
	\item \texttt{lcmaps\_voms\_poolgroup.mod} (\textbf{A}):
	    this plugin tries to find a pool group Id (gid) based on the VO information
	    and a \emph{groupmapfile} (leases in \$GROUPMAPDIR)
	    \htmladdnormallink{More info ...}{apidoc/html/lcmaps_voms_poolgroup.mod.html}
	\item \texttt{lcmaps\_voms\_poolaccount.mod} (\textbf{A}):
	    this plugin tries to find  a pool account based on the VO information and a
	    \emph{gridmapfile} (leases in \$GRIDMAPDIR)
	    \htmladdnormallink{More info ...}{apidoc/html/lcmaps_voms_poolaccount.mod.html}
	\ei
\item plugins that give the user AFS (later also Kerberos5) access.
	\bi
	\item \texttt{lcmaps\_afs.mod} (\textbf{A/E}):
            this plugin has to run after the \texttt{lcmaps\_posix\_enf.mod} plugin has been run
            successfully.
            \htmladdnormallink{More info ...}{apidoc/html/lcmaps_afs.mod.html}
        \ei
\item plugins that access (i.e. store lcmaps info in) the Job Repository:
	\bi
	\item \texttt{lcmaps\_jobrep.mod}:
            \htmladdnormallink{More info ...}{apidoc/html/lcmaps_jobrep.mod.html}
        \ei
\item dummy plugins always answering yes or no (handy for testing the lcmaps policy:
	\bi
	\item \texttt{lcmaps\_dummy\_good.mod}:
            \htmladdnormallink{More info ...}{apidoc/html/lcmaps_dummy\_good.mod.html}
	\item \texttt{lcmaps\_dummy\_bad.mod}:
            \htmladdnormallink{More info ...}{apidoc/html/lcmaps_dummy\_bad.mod.html}
        \ei
\ei

More information on LCMAPS and other components of the Gridification subsystem can be found in:
\bi
\item the WP4 architecture document D4.2:
\item plugins that use the VOMS (VO Membership Service)
attribute assertions in the user certificate for the credential mapping.
	\htmladdnormallinkfoot{pdf version}
	{http://hep-proj-grid-fabric.web.cern.ch/hep-proj-grid-fabric/architecture/eu/WP4-architecture-2\_1.pdf}
	or
	\htmladdnormallinkfoot{doc version}
	{http://hep-proj-grid-fabric.web.cern.ch/hep-proj-grid-fabric/architecture/eu/WP4-architecture-2\_1.doc}.
\item LCAS:
	\htmladdnormallinkfoot{http://www.dutchgrid.nl/DataGrid/wp4/lcas/edg-lcas-1.1/}
	{http://www.dutchgrid.nl/DataGrid/wp4/lcas/edg-lcas-1.1/}
\item the description of the LCMAPS API:
	\htmladdnormallinkfoot{here}{apidoc/html/index.html}
	,
	\htmladdnormallinkfoot{PostScript file}{apidoc/latex/refman.ps}
	and
	\htmladdnormallinkfoot{PDF file}{apidoc/latex/refman.pdf}.
\item the LCMAPS policy description language (pdl):
        \htmladdnormallinkfoot{here}
        {pdl\_requirements/index.html}
        , or as
        \htmladdnormallinkfoot{PostScript file}{pdl\_requirements.ps}
        or
        \htmladdnormallinkfoot{PDF file}{pdl\_requirements.pdf}.
\item \htmladdnormallinkfoot{Job Repository}
        {../jr/index.html}
\item the
	\htmladdnormallinkfoot{README}{README},
	\htmladdnormallinkfoot{INSTALL}{INSTALL},
	and
	\htmladdnormallinkfoot{LICENSE}{LICENSE}
	files.
\item In 
	\htmladdnormallinkfoot{README.AFS}{README.AFS}
      it is described what prerequisites are needed for the LCMAPS AFS module
      (most notably the gssklog package has to be setup).
\item the file containing instructions how to avoid LDAP as a source of user accounting information
	\htmladdnormallinkfoot{README.NO\_LDAP}{README.NO\_LDAP},
\ei
A few \emph{example} scripts are added, which can be used to setup poolaccounts, poolgroups in LDAP:
\bi
\item \htmladdnormallinkfoot{lcmaps\_gen\_poolacc\_ldif}{lcmaps\_gen\_poolacc\_ldif}
\item \htmladdnormallinkfoot{lcmaps\_gen\_poolgroup\_ldif}{lcmaps\_gen\_poolgroup\_ldif}
\item \htmladdnormallinkfoot{lcmaps\_make\_poolacc\_dir}{lcmaps\_make\_poolacc\_dir}
\item \htmladdnormallinkfoot{lcmaps\_setup\_pool}{lcmaps\_setup\_pool}
\ei

\section{Installation}

LCMAPS uses the globus security libraries (gss, gsi, openssl), which are provided by e.g.
\htmladdnormallink{VDT}{http://www.lsc-group.phys.uwm.edu/vdt/edg_lcg.html}
(Virtual Data Toolkit) and the VOMS API.
These libraries in addition to the libraries listed
\hyperref{here}{in table}{}{tab:rpms}
, have to be installed on the CE.
\btab
\caption{RPMs to be installed.
         \label{tab:rpms} }
\begin{center}

\begin{htmlonly}
\begin{tabular}{||l|l|l|l||}
\hline
RPM & min. version & description & URL \\
%\hline
%\multicolumn{4}{ || c ||}{LCMAPS plugins} \\
\texttt{edg-lcmaps} & 0.0.16
    & the LCMAPS library ( = pluginframework + utilities) and an example LCMAPS plugin
    & \htmladdnormallink{http://datagrid.in2p3.fr/distribution/autobuild/i386-rh7.3/wp4/gridification/RPMS/}
      {http://datagrid.in2p3.fr/distribution/autobuild/i386-rh7.3/wp4/gridification/RPMS/} \\
\texttt{edg-lcmaps-basic\_plugins} & 0.0.16
    & the LCMAPS plugins providing the basic globus-gatekeeper functionality
    & \htmladdnormallink{http://datagrid.in2p3.fr/distribution/autobuild/i386-rh7.3/wp4/gridification/RPMS/}
      {http://datagrid.in2p3.fr/distribution/autobuild/i386-rh7.3/wp4/gridification/RPMS/} \\
\texttt{edg-lcmaps-voms\_plugins} & 0.0.16
    & the LCMAPS plugins that base the credential mapping on the VO information inside the user certificate
    & \htmladdnormallink{http://datagrid.in2p3.fr/distribution/autobuild/i386-rh7.3/wp4/gridification/RPMS/}
      {http://datagrid.in2p3.fr/distribution/autobuild/i386-rh7.3/wp4/gridification/RPMS/} \\
\texttt{edg-lcmaps-afs\_plugins} & 0.0.19
    & the LCMAPS plugin that acquires an AFS token for the user (uses gssklog)
    & \htmladdnormallink{http://datagrid.in2p3.fr/distribution/autobuild/i386-rh7.3/wp4/gridification/RPMS/}
      {http://datagrid.in2p3.fr/distribution/autobuild/i386-rh7.3/wp4/gridification/RPMS/} \\
\texttt{edg-lcmaps-jobrep\_plugins} & 0.0.23
    & the LCMAPS plugin that stores user and job info in the Job Repository
    & \htmladdnormallink{http://datagrid.in2p3.fr/distribution/autobuild/i386-rh7.3/wp4/gridification/RPMS/}
      {http://datagrid.in2p3.fr/distribution/autobuild/i386-rh7.3/wp4/gridification/RPMS/} \\
\texttt{edg-lcmaps-interface} & 0.0.1
    & LCMAPS interface/API, only needed for software development (new plugins)
    & \htmladdnormallink{http://datagrid.in2p3.fr/distribution/autobuild/i386-rh7.3/wp4/gridification/RPMS/}
      {http://datagrid.in2p3.fr/distribution/autobuild/i386-rh7.3/wp4/gridification/RPMS/} \\
\texttt{edg-lcfg-lcmaps} & 1.0
    & the LCFG object that configures the LCMAPS configuration files
    & \htmladdnormallink{http://datagrid.in2p3.fr/distribution/autobuild/i386-rh7.3/wp4/edg-lcfg/RPMS/}
      {http://datagrid.in2p3.fr/distribution/autobuild/i386-rh7.3/wp4/edg-lcfg/RPMS/} \\
\texttt{voms-api} & 1.1.16
    & the VOMS API, used by \texttt{edg-lcmaps-voms\_plugins}
    & \htmladdnormallink{http://datagrid.in2p3.fr/distribution/autobuild/i386-rh7.3/wp6/RPMS/}
      {http://datagrid.in2p3.fr/distribution/autobuild/i386-rh7.3/wp6/RPMS/} \\
\texttt{edg\_gatekeeper-gcc32dbg\_pgm} & 2.2.8
    & the modified globus gatekeeper
    & \htmladdnormallink{http://datagrid.in2p3.fr/distribution/autobuild/i386-rh7.3/wp4/gridification/RPMS/}
      {http://datagrid.in2p3.fr/distribution/autobuild/i386-rh7.3/wp4/gridification/RPMS/} \\
\texttt{globus-config} & 0.20-1
    & globus configuration scripts, including the init.d gatekeeper script
    & \htmladdnormallink{http://datagrid.in2p3.fr/distribution/globus/config/RPMS/}
      {http://datagrid.in2p3.fr/distribution/globus/config/RPMS/} \\
\texttt{edg-lcfg-globuscfg} & 1.3.12
    & the LCFG component to manage the Globus configuration
    & \htmladdnormallink{http://datagrid.in2p3.fr/distribution/autobuild/i386-rh7.3/wp4/edg-lcfg/RPMS/}
      {http://datagrid.in2p3.fr/distribution/autobuild/i386-rh7.3/wp4/edg-lcfg/RPMS/} \\
\texttt{vdt\_globus\_essentials} & VDTALT1.1.8
    & VDT globus rpm that contains a.o. the security libraries
    & \htmladdnormallink{http://www.lsc-group.phys.uwm.edu/vdt/vdt\_rpms/edg/vdt-1.1.8/globus\_coarse\_rpm/}
      {http://www.lsc-group.phys.uwm.edu/vdt/vdt\_rpms/edg/vdt-1.1.8/globus\_coarse\_rpm/} \\
\hline
\end{tabular}
\end{htmlonly}

\begin{latexonly}
\tiny
\begin{tabular}{||l|l|l||}
\hline
RPM & min. version & description + URL \\
\hline
\texttt{edg-lcmaps} & 0.0.16
    & the LCMAPS library ( = pluginframework + utilities) and an example LCMAPS \\
    && plugin \\
\cline{3-3}
    && \htmladdnormallink{http://datagrid.in2p3.fr/distribution/autobuild/i386-rh7.3/wp4/gridification/RPMS/}
      {http://datagrid.in2p3.fr/distribution/autobuild/i386-rh7.3/wp4/gridification/RPMS/} \\
\hline
\texttt{edg-lcmaps-basic\_plugins} & 0.0.16
    & the LCMAPS plugins providing the basic globus-gatekeeper functionality \\
\cline{3-3}
    && \htmladdnormallink{http://datagrid.in2p3.fr/distribution/autobuild/i386-rh7.3/wp4/gridification/RPMS/}
      {http://datagrid.in2p3.fr/distribution/autobuild/i386-rh7.3/wp4/gridification/RPMS/} \\
\hline
\texttt{edg-lcmaps-voms\_plugins} & 0.0.16
    & the LCMAPS plugins that base the credential mapping on the VO information \\
    && inside the user certificate \\
\cline{3-3}
    && \htmladdnormallink{http://datagrid.in2p3.fr/distribution/autobuild/i386-rh7.3/wp4/gridification/RPMS/}
      {http://datagrid.in2p3.fr/distribution/autobuild/i386-rh7.3/wp4/gridification/RPMS/} \\
\hline
\texttt{edg-lcmaps-afs\_plugins} & 0.0.19
    & the LCMAPS plugin that acquires an AFS token for the user (uses gssklog) \\
    && \htmladdnormallink{http://datagrid.in2p3.fr/distribution/autobuild/i386-rh7.3/wp4/gridification/RPMS/}
      {http://datagrid.in2p3.fr/distribution/autobuild/i386-rh7.3/wp4/gridification/RPMS/} \\
\hline
\texttt{edg-lcmaps-jobrep\_plugins} & 0.0.23
    & the LCMAPS plugin that stores user and job info in the Job Repository \\
    && \htmladdnormallink{http://datagrid.in2p3.fr/distribution/autobuild/i386-rh7.3/wp4/gridification/RPMS/}
      {http://datagrid.in2p3.fr/distribution/autobuild/i386-rh7.3/wp4/gridification/RPMS/} \\
\hline
\texttt{edg-lcmaps-interface} & 0.0.1
    & LCMAPS interface/API, only needed for software development (new plugins) \\
\cline{3-3}
    && \htmladdnormallink{http://datagrid.in2p3.fr/distribution/autobuild/i386-rh7.3/wp4/gridification/RPMS/}
      {http://datagrid.in2p3.fr/distribution/autobuild/i386-rh7.3/wp4/gridification/RPMS/} \\
\hline
\texttt{edg-lcfg-lcmaps} & 1.0
    & the LCFG object that configures the LCMAPS configuration files \\
\cline{3-3}
    && \htmladdnormallink{http://datagrid.in2p3.fr/distribution/autobuild/i386-rh7.3/wp4/edg-lcfg/RPMS/}
      {http://datagrid.in2p3.fr/distribution/autobuild/i386-rh7.3/wp4/edg-lcfg/RPMS/} \\
\hline
\texttt{voms-api} & 1.1.16
    & the VOMS API, used by \texttt{edg-lcmaps-voms\_plugins} \\
\cline{3-3}
    && \htmladdnormallink{http://datagrid.in2p3.fr/distribution/autobuild/i386-rh7.3/wp6/RPMS/}
      {http://datagrid.in2p3.fr/distribution/autobuild/i386-rh7.3/wp6/RPMS/} \\
\hline
\texttt{edg\_gatekeeper-gcc32dbg\_pgm} & 2.2.8
    & the modified globus gatekeeper \\
\cline{3-3}
    && \htmladdnormallink{http://datagrid.in2p3.fr/distribution/autobuild/i386-rh7.3/wp4/gridification/RPMS/}
      {http://datagrid.in2p3.fr/distribution/autobuild/i386-rh7.3/wp4/gridification/RPMS/} \\
\hline
\texttt{globus-config} & 0.20-1
    & globus configuration scripts, including the init.d gatekeeper script \\
\cline{3-3}
    && \htmladdnormallink{http://datagrid.in2p3.fr/distribution/globus/config/RPMS/}
      {http://datagrid.in2p3.fr/distribution/globus/config/RPMS/} \\
\hline
\texttt{edg-lcfg-globuscfg} & 1.3.12
    & the LCFG component to manage the Globus configuration \\
\cline{3-3}
    && \htmladdnormallink{http://datagrid.in2p3.fr/distribution/autobuild/i386-rh7.3/wp4/edg-lcfg/RPMS/}
      {http://datagrid.in2p3.fr/distribution/autobuild/i386-rh7.3/wp4/edg-lcfg/RPMS/} \\
\hline
\texttt{vdt\_globus\_essentials} & VDTALT1.1.8
    & VDT globus rpm that contains a.o. the security libraries \\
\cline{3-3}
    && \htmladdnormallink{http://www.lsc-group.phys.uwm.edu/vdt/vdt\_rpms/edg/vdt-1.1.8/globus\_coarse\_rpm/}
      {http://www.lsc-group.phys.uwm.edu/vdt/vdt\_rpms/edg/vdt-1.1.8/globus\_coarse\_rpm/} \\
\hline
\end{tabular}
\end{latexonly}

\end{center}
\etab

The LCMAPS library will be installed in \texttt{/opt/edg/lib/lcmaps/} and the example configuration
files in \texttt{/opt/edg/etc/lcmaps/}. The LCMAPS plugins are all installed in
the \texttt{lcmaps} subdirectory of the directory where LCMAPS is
installed.


\textbf{From CVS:}\\
The LCMAPS library and plugins can also be built directly from the
	\htmladdnormallinkfoot{cvs repository}
	{http://datagrid.in2p3.fr/cgi-bin/cvsweb.cgi/fabric\_mgt/gridification/lcmaps/} by the following
steps:
\bi
\item \texttt{cvs export -r <version\_tag> \ fabric\_mgt/gridification/lcmaps} -- export the source from CVS
using a tagged version (e.g. v0\_0\_1)
\item \texttt{cd fabric\_mgt/gridification/lcmaps; ./autogen.sh} -- run the bootstrap script to run
autotools
\item \texttt{./configure --prefix=<path>} \texttt{--libdir=<path>/lib/lcmaps} \\
\texttt{--includedir=<path>/include/lcmaps} \texttt{--sysconfdir=<path>/etc/lcmaps} -- run the configure script
\item \texttt{make rpm} -- if you want to make the rpm
\item \texttt{make; make install} -- build and install the LCMAPS Library and the LCMAPS plugins
\item \texttt{make apidoc} -- if you want to create the API documentation. This is for example
useful for developers of new LCMAPS plugins.
\item \texttt{make userdoc} -- Generate this documentation.
\ei

\section{Configuration}

The configuration involves both LCMAPS itself and the edg-gatekeeper.

\subsection{Configuration of the edg-gatekeeper}
The edg-gatekeeper is configurable with a few more command line options in addition to the normal
globus-gatekeeper options:
\begin{htmlonly}
\bi
\item \texttt{-lcmaps\_debug\_level <debug level>}: set the debug level for LCMAPS (0--5, default: 0 (= no debugging))
\item \texttt{-lcmaps\_db\_file <file>}: specifies the filename of the LCMAPS policy file
                                         (default: \texttt{lcmaps.db}).
\item \texttt{-lcmaps\_etc\_dir <path>}: specifies the directory where the LCMAPS configuration files
                                         are located (default: \texttt{/opt/edg/etc/lcmaps/}).
\item \texttt{-lcmapsmod\_dir <path>}:   specifies the directory where the LCMAPS library is located
                                         (default: \texttt{/opt/edg/lib/lcmaps/}).
\item \texttt{-lcas\_debug\_level <debug level>}: set the debug level for LCAS (0--5, default: 0 (= no debugging))
\item \texttt{-lcas\_db\_file <file>}:   specifies the filename of the LCAS policy file
                                         (default: \texttt{lcas.db}).
\item \texttt{-lcas\_etc\_dir <path>}:   specifies the directory where the LCAS authorization
                                         configuration files are located
                                         (default \texttt{/opt/edg/etc/lcas/}).
\item \texttt{-lcas\_dir <path>}:        same as \textrm{-lcas\_etc\_dir <path>}, deprecated.
\item \texttt{-lcasmod\_dir <path>}:     specifies the directory where the LCAS library is located
                                         (default \texttt{/opt/edg/lib/lcas/}).
\item \texttt{-plainoldglobus}:          provides the old globus-gatekeeper functionality,
                                         LCAS and LCMAPS are not used.
\item \texttt{-no\_lcas}:                do not use LCAS.
\item \texttt{-no\_lcmaps}:              do not use LCMAPS (use standard gridmap functionality of
                                         gatekeeper).
\ei
\end{htmlonly}
\begin{latexonly}
\begin{tabbing}
aaaaaaaaaaaaaaaaaaaaa: \= text \kill
-lcmaps\_debug\_level $<$debug level$>$: \> set the debug level for LCMAPS (default: 0 (= no debugging))\\
-lcmaps\_db\_file $<$file$>$: \> specifies the filename of the LCMAPS policy file\\
                              \> (default: \texttt{lcmaps.db}).\\
-lcmaps\_etc\_dir $<$path$>$: \> specifies the directory where the LCMAPS configuration files\\
                              \> are located (default: \texttt{/opt/edg/etc/lcmaps/}).\\
-lcmapsmod\_dir $<$path$>$:   \> specifies the directory where the LCMAPS library is located\\
                              \> (default: \texttt{/opt/edg/lib/lcmaps/}).\\
-lcas\_debug\_level $<$debug level$>$: \> set the debug level for LCAS (0--5, default: 0 (= no debugging))\\
-lcas\_db\_file $<$file$>$:   \> specifies the filename of the LCAS policy file\\
                                 (default: \texttt{lcas.db}).\\
-lcas\_etc\_dir $<$path$>$:   \> specifies the directory where the LCAS authorization\\
                              \> configuration files are located (default \texttt{/opt/edg/etc/lcas/}).\\
-lcas\_dir $<$path$>$:        \> same as \textrm{-lcas\_etc\_dir <path>}, deprecated.\\
-lcasmod\_dir $<$path$>$:     \> specifies the directory where the LCAS library is located\\
                              \> (default \texttt{/opt/edg/lib/lcas/}).\\
-plainoldglobus:              \> provides the old globus-gatekeeper functionality,\\
                              \> LCAS and LCMAPS are not used.\\
-no\_lcas:                    \> do not use LCAS.\\
-no\_lcmaps:                  \> do not use LCMAPS (use standard gridmap functionality of\\
                              \> gatekeeper).\\
\end{tabbing}
\end{latexonly}
The directories where the poolaccount and poolgroup leases are registered, the so called gridmapdir
and groupmapdir, can be passed to the gatekeeper by setting the environment variables
\texttt{\$GRIDMAPDIR} and \texttt{\$GROUPMAPDIR} to the respective directories.

The \texttt{globus.conf} file (usually residing in the \texttt{/etc} directory) contains the
configuration parameters for the globus software. The gatekeeper init.d script uses this file to
to configure the edg-gatekeeper. The following lines were added/modified in \texttt{/etc/globus.conf}:
\bi
\item[] \texttt{[gatekeeper]}
\item[] \texttt{[...]}
\item[] \texttt{globus\_gatekeeper=/opt/edg/sbin/edg-gatekeeper}
\item[] \texttt{extra\_options="-lcas\_etc\_dir /opt/edg/etc/lcas/ -lcasmod\_dir /opt/edg/lib/lcas/ -lcas\_db\_file lcas.db -lcmaps\_etc\_dir /opt/edg/etc/lcmaps/ -lcmapsmod\_dir /opt/edg/lib/lcmaps -lcmaps\_db\_file lcmaps.db"}
\ei
The \texttt{globus\_gatekeeper=} line gives the path of the gatekeeper to be used and the \texttt{extra\_options=}
line the gatekeeper options to be added.
The \texttt{gridmapdir} and \texttt{groupmapdir} entries give the default locations for the
poolaccount and poolgroup lease administration directories.

\textbf{LCFG configuration:}\\
The \texttt{globus.conf} file can be created using the globus LCFG object contained in package
\texttt{edg-lcfg-globuscfg}. The extra lines for the configuration files have to be specified in
an LCFGng resource file in the way that is shown in
the Computing Element resource file
\htmladdnormallinkfoot{ComputingElement-cfg.h}
{http://datagrid.in2p3.fr/cgi-bin/cvsweb.cgi/edg-release/ng\_source/ComputingElement-cfg.h}.

\subsection{Configuration of LCMAPS}
The LCMAPS reads its configuration, in particular the plugins that it should load and the local
site policy from the file \texttt{lcmaps.db}. An example file is shown
\begin{htmlonly}
	\htmladdnormallink{here}{lcmaps.db.ex}.
\end{htmlonly}
\begin{latexonly}
here:
\verbatiminput{lcmaps.db.ex}
\end{latexonly}
The default path to the LCMAPS plugins is specified on the line starting with \texttt{path =}.
On the following
lines aliases are defined for the complete plugin names and their options. For a description of the
plugins and the options please refer to the man pages installed with the rpms, which can also be found
in \htmladdnormallink{apidoc}{apidoc/html/pages.html}.
In the current release the number of aliases attached to a plugin is limited to one. If one wants to
use two aliases of for example the "localaccount" plugin, each alias corresponding to different
options, this is not possible, unless a physical copy is mode of the plugin. This will be corrected in
the next release.

In the lines following the plugin definitions the local site policies are described. The policies
follow the word ended by a colon. The policies are evaluated in order of appearance, until
a policy evaluation returns a true result.
In the example two policies are described:
\begin{enumerate}
\item default: This policy does pretty much the same as what the old gatekeeper did: check the
gridmapfile with the user's DN for a local account or a poolaccount.
\item voms: This policy uses the VOMS information in the user's proxy X509 certificate. First it
checks if the VO info is actually there. If so, it tries to find local groups for this VO info or
if it cannot find local groups it tries to find pool groups. If local groups \emph{were} found, in
addition it will try to find pool groups. Then it will try to find a VOMS poolaccount (based on the VO
information). The next step is to try to add the gids found to the LDAP directory (\texttt{ldap\_enf})
and enforce them in (\texttt{posix\_enf}) the calling process (become the user).
\end{enumerate}

A more elaborate description of the policy description language can be found
\htmladdnormallinkfoot{here}
{pdl\_requirements/index.html}
, or as
\htmladdnormallinkfoot{PostScript file}{pdl\_requirements.ps}
or
\htmladdnormallinkfoot{PDF file}{pdl\_requirements.pdf}.

The configuration files needed by the plugins consist of the (ordinary) \texttt{grid-mapfile} (used by
the plugins \texttt{localaccount}, \texttt{poolaccount} and \texttt{vomspoolaccount}) and a new file: the
\texttt{groupmapfile} (used by the plugins vomslocalgroup and vomspoolgroup). This file contains
line entries for "VO-GROUP-ROLE" combinations and a corresponding local/pool account.
The "VO-GROUP-ROLE" combinations in the user's proxy will be compared to the entries in the
\texttt{groupmapfile} and if a match is found, a gid is added to the list of local credentials for the
user.
An example \texttt{groupmapfile} is shown
\begin{htmlonly}
	\htmladdnormallink{here}{groupmapfile.ex}.
\end{htmlonly}
\begin{latexonly}
here:
\verbatiminput{groupmapfile.ex}
\end{latexonly}
Note that one can use \texttt{'*'} as a wild character.
The \texttt{vomspoolaccount} finds a pool account based on the VO information and on the user
DN. Therefore, it looks in the \texttt{grid-mapfile} for "VO-GROUP-ROLE" combinations as is shown
\begin{htmlonly}
in
	\htmladdnormallink{this}{gridmapfile.ex}
example.
\end{htmlonly}
\begin{latexonly}
here:
\verbatiminput{gridmapfile.ex}
\end{latexonly}
The leases that are maintained in the gridmapdir are, however, based on the user
DN and the gids found prior to the \texttt{vomspoolaccount} call.

The gridmapdir and groupmapdir directories that are needed by the various plugins can be set
in the \texttt{lcmaps.db} file or by setting the environment variables
\texttt{\$GRIDMAPDIR} and \texttt{\$GROUPMAPDIR} to the respective directories.

\textbf{LCFG configuration:}\\
The LCMAPS policy file can also be created using the LCMAPS LCFG object contained in package
\texttt{edg-lcfg-lcmaps}. The lines for the configuration files have to be specified in
an LCFG resource file in the way that is shown in
the Computing Element resource file
\htmladdnormallinkfoot{ComputingElement-cfg.h}
{http://datagrid.in2p3.fr/cgi-bin/cvsweb.cgi/edg-release/ng\_source/ComputingElement-cfg.h}.
One should be careful when specifying asterixes and double quotes.
The \texttt{groupmapfile} will be installed by the filecopy LCFG package \texttt{edg-lcfg-filecopy}.

\section{Adding LCMAPS plugins}

To be done.
%In addition to the three standard authorization plugins, new plugins may be written.
%The plugins have to be provided as shared objects.
%When the LCAS receives an authorization request, it uses \texttt{dlopen} to open the plugin shared object.
%The interface of the plugins to the LCAS consists of the following three functions, which are called
%in order with a \texttt{dlsym} call by the LCAS:
%\bi
%\item \textbf{int plugin\_initialize(int argc, char **argv)}: \\
%Everything that is needed to initialize the plugin should be put inside this function.
%Arguments as read from the LCAS database (\textbf{argc}, \textbf{argv}) are passed to the plugin.
%
%\item \textbf{int plugin\_confirm\_authorization(lcas\_request\_t request, lcas\_cred\_id\_t lcas\_cred)}: \\
%By this call, the LCAS asks the plugin for authorization by passing the request in RSL (later JDL)
%and the user credential (\textbf{lcas\_cred}).
%The user credential will contain information on the role the user wants to play.
%In the RSL (JDL) the user might specify the resources he wants to use.
%The authorization decision has to be made using this information.
%The LCAS provides no library for parsing the RSL (JDL).
%\item \textbf{int plugin\_terminate()}: \\
%Whatever is needed to terminate the plugin module goes in here.
%\ei
%If these symbols cannot be found by LCAS at runtime, an error occurs, resulting in an authorization failure.
%More information on the plugin interface can be found in the \textbf{apidoc} documentation for the
%	\htmladdnormallink{plugin interface}{apidoc/html/group__PluginInterface.html}.
%The LCAS Library also contains utilities for logging, file checking and (extremely simple) LCAS credential
%handling. The API to be used by the LCAS plugins can be found in the \textbf{apidoc} documentation for the
%	\htmladdnormallink{API for the plugins}{apidoc/html/group__APIforPlugins.html}.
%In order to use these utilities a line like
%\begin{verbatim}
%#include "lcas_modules.h"
%\end{verbatim}
%has to appear in the plugin source.
%A line similar to
%\begin{verbatim}
%-I $GLOBUS_LOCATION/include/gcc32dbg -I /opt/edg/include/lcas
%\end{verbatim}
%has to be added to the compilation command line in order to include the LCAS and GLOBUS include directories.
%
%To make life easier for the plugin developer an example plugin has been written in C,
%which is available in the LCAS
%	\htmladdnormallinkfoot{cvs repository}
%	{http://datagrid.in2p3.fr/cgi-bin/cvsweb.cgi/fabric\_mgt/gridification/lcas/plugin\_example}.
%The example plugin is built using autotools (automake, autoconf, libtool), for which the files
%	\htmladdnormallinkfoot{configure.in}
%	{http://datagrid.in2p3.fr/cgi-bin/cvsweb.cgi/fabric\_mgt/gridification/lcas/configure.in}
%and
%	\htmladdnormallinkfoot{Makefile.am}
%	{http://datagrid.in2p3.fr/cgi-bin/cvsweb.cgi/fabric\_mgt/gridification/lcas/plugin\_example/Makefile.am}
%have to be present.
%\begin{htmlonly}
%The source code can be found
%	\htmladdnormallink{here}{apidoc/html/lcas__plugin__example_8c-source.html}.
%\end{htmlonly}
%\begin{latexonly}
%The source code is shown here:
%\tiny
%\verbatiminput{lcas_plugin_example.c}
%\end{latexonly}
%
%The new plugin can be tested without having a functioning edg-gatekeeper by running the program
%\texttt{lcas-test} in the \texttt{src} directory of the LCAS cvs repository,
%which is basically a copy of the part of the edg-gatekeeper that contacts the LCAS.

\section{User guide}

Empty.


%
% Finish
%
\end{document}