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)