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