lcmaps

LCMAPS(3)                  Library Functions Manual                  LCMAPS(3)



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)