NAME

       lcmaps - The Local Credential MAPping Service

SYNOPSIS

       lcmaps

DESCRIPTION

       The  LCMAPS framework is designed to take various credentials as input, e.g. a certificate
       and/or VOMS 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 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 gLExec, the lcas-lcmaps-gt(4)-interface to interface with a Globus GT4
       and GT5 Gatekeeper, GridFTP daemon and GSI-OpenSSHd, in StoRM and somewhere in XRootD.

INVOCATION

       When an application initializes LCMAPS the plugins will be loaded based on  the  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 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 successfully it can
       execute a different next plugin then when it failed. This allows LCMAPS to pass  different
       plugins to resolve a credential mapping.

ENVIRONMENT

       GATEKEEPER_JM_ID
              Extra Gatekeeper log message to be able to more easily track a Job Manager ID.

       GLOBUSID
              See $GATEKEEPER_JM_ID.

       JOB_REPOSITORY_ID
              See  $GATEKEEPER_JM_ID, but explicitly for the purpose of the LCMAPS Job Repository
              plugin.

       LCMAPS_DB_FILE
              Override the build-in default filename for the lcmaps.db  configuration  file  with
              the value of this environment variable.

       LCMAPS_DEBUG_LEVEL
              Tune  the logging output cut off level. The numbers resemble the numbers as used in
              previous released in the range [1-5]. However, since  LCMAPS  version  1.5.0  these
              numbers resemble a numerically shifted Syslog number.

              0      Silent logging, no messages will be written to file or Syslog.

              1      All messages with a priority of LOG_ERR are written to file or Syslog.  More
                     severe error messages are squashed down to the LOG_ERR priority. 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.

              2      All  messages  with  a priority of LOG_WARNING or more severe, i.e. LOG_ERR,
                     are written to file and/or Syslog.

              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.

              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.

              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.

       LCMAPS_DIR
              The base directory of the $LCMAPS_DB_FILE parameter. This variable is  concatenated
              with the $LCMAPS_DB_FILE

       LCMAPS_ETC_DIR
              See $LCMAPS_DIR

       LCMAPS_LOG_FILE
              Overrides  the  build-in  default  file  path  to  log the output to. When set, the
              logging will not go to Syslog.

       LCMAPS_LOG_STRING
              Prepend all log output messages with value of this environment variable

       LCMAPS_MODULES_DIR
              Directory to search for the LCMAPS plugins (or modules). Same as the path option in
              the lcmaps.db file..

       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 written in the lcmaps.db file (from top to bottom).

       LCMAPS_VERIFY_TYPE
              Deprecated

       LCMAPS_VOMS_EXTRACT
              Deprecated

       LCMAPS_X509_CERT_DIR
              Specific setting equal to the $X509_CERT_DIR environment variable

       LCMAPS_X509_VOMS_DIR
              Specific setting equal to the $X509_VOMS_DIR environment variable

       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/.

       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/.

RETURN VALUES

       LCMAPS_SUCCESS
              Success.

       LCMAPS_FAIL
              Failure.

NOTES

       For an API specification, please use make doc to make the apidoc.

BUGS

       The  apidoc  is  not  complete.  It  has  most  interfaces,  but  needs  to be checked for
       completeness.

       Please report any errors to the Nikhef Grid Middleware  Security  Team  <grid-mw-security-
       support@nikhef.nl>.

SEE ALSO

       lcmaps.db(5),          lcas_lcmaps_gt4_interface(8),          lcas_lcmaps_gt_interface(8),
       lcmaps_dummy_bad.mod(8),         lcmaps_dummy_good.mod(8),         lcmaps_ldap_enf.mod(8),
       lcmaps_localaccount.mod(8),     lcmaps-plugins-c-pep(8),    lcmaps_plugins_scas_client(8),
       lcmaps_poolaccount.mod(8),    lcmaps_posix_enf.mod(8),     lcmaps_tracking_groupid.mod(8),
       lcmaps_verify_proxy.mod(8),  scas(8),  scas.conf(5),  glexec(1),  glexec.conf(5),  ees(1),
       ees.conf(5)

AUTHORS

       LCMAPS and the LCMAPS plug-ins were written by the Grid Middleware Security Team <grid-mw-
       security@nikhef.nl>.

                                        December 22, 2011                               LCMAPS(3)