.\" Copyright (c) Members of the EGEE Collaboration. 2006-2010. .\" See http://www.eu-egee.org/partners/ for details on the copyright .\" holders. .\" .\" Licensed under the Apache License, Version 2.0 (the "License"); .\" you may not use this file except in compliance with the License. .\" You may obtain a copy of the License at .\" .\" http://www.apache.org/licenses/LICENSE-2.0 .\" .\" Unless required by applicable law or agreed to in writing, software .\" distributed under the License is distributed on an "AS IS" BASIS, .\" WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. .\" See the License for the specific language governing permissions and .\" limitations under the License. .\" .\" Authors: .\" 2009- .\" Oscar Koeroo .\" Mischa Sall\'e .\" NIKHEF Amsterdam, the Netherlands .\" .\" 2006-2009 .\" Gerben Venekamp .\" NIKHEF Amsterdam, the Netherlands .\" .TH LCMAPS 3 "December 22, 2011" .SH NAME lcmaps \- The Local Credential MAPping Service .SH SYNOPSIS .nh .ad l .B lcmaps .hy .ad b .SH 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 \fBlcmaps.db\fR 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 \fBgLExec\fR, the \fBlcas-lcmaps-gt(4)-interface\fR to interface with a Globus GT4 and GT5 Gatekeeper, GridFTP daemon and GSI-OpenSSHd, in StoRM and somewhere in XRootD. .SH INVOCATION When an application initializes LCMAPS the plugins will be loaded based on the \fBlcmaps.db\fR 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 \fBlcmaps.db\fR 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. .SH ENVIRONMENT .TP .BI GATEKEEPER_JM_ID Extra Gatekeeper log message to be able to more easily track a Job Manager ID. .TP .BI GLOBUSID See $GATEKEEPER\_JM\_ID. .TP .BI JOB_REPOSITORY_ID See $GATEKEEPER_JM_ID, but explicitly for the purpose of the LCMAPS Job Repository plugin. .TP .BI LCMAPS_DB_FILE Override the build-in default filename for the \fBlcmaps.db\fR configuration file with the value of this environment variable. .TP .BI 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. .RS .TP .B 0 Silent logging, \fBno messages\fR will be written to file or Syslog. .TP .B 1 All messages with a priority of \fBLOG_ERR\fR 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. .TP .B 2 All messages with a priority of \fBLOG_WARNING\fR or more severe, i.e. LOG_ERR, are written to file and/or Syslog. .TP .B 3 All messages with a priority of \fBLOG_NOTICE\fR 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 \fBlcas-lcmaps-gt-interface\fR and \fBglexec\fR. 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. .TP .B 4 All messages with a priority of \fBLOG_INFO\fR 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 \fBbuild-in default\fR. 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. .TP .B 5 All messages with a priority of \fBLOG_DEBUG\fR 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. .RE .TP .BI LCMAPS_DIR The base directory of the $LCMAPS_DB_FILE parameter. This variable is concatenated with the $LCMAPS_DB_FILE .TP .BI LCMAPS_ETC_DIR See $LCMAPS_DIR .TP .BI LCMAPS_LOG_FILE Overrides the build-in default file path to log the output to. When set, the logging will not go to Syslog. .TP .BI LCMAPS_LOG_STRING Prepend all log output messages with value of this environment variable .TP .BI LCMAPS_MODULES_DIR Directory to search for the LCMAPS plugins (or modules). Same as the \fBpath\fR option in the \fBlcmaps.db\fR file.. .TP .BI 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 \fBlcmaps.db\fR file (from top to bottom). .TP .BI LCMAPS_VERIFY_TYPE Deprecated .TP .BI LCMAPS_VOMS_EXTRACT Deprecated .TP .BI LCMAPS_X509_CERT_DIR Specific setting equal to the $X509_CERT_DIR environment variable .TP .BI LCMAPS_X509_VOMS_DIR Specific setting equal to the $X509_VOMS_DIR environment variable .TP .BI 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/. .TP .BI 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/. .SH "RETURN VALUES" .TP .B LCMAPS_SUCCESS Success. .TP .B LCMAPS_FAIL Failure. .SH NOTES For an API specification, please use \fBmake doc\fR to make the apidoc. .SH 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 . .SH "SEE ALSO" .BR lcmaps.db (5), .BR lcas_lcmaps_gt4_interface (8), .BR lcas_lcmaps_gt_interface (8), .BR lcmaps_dummy_bad.mod (8), .BR lcmaps_dummy_good.mod (8), .BR lcmaps_ldap_enf.mod (8), .BR lcmaps_localaccount.mod (8), .BR lcmaps-plugins-c-pep (8), .BR lcmaps_plugins_scas_client (8), .BR lcmaps_poolaccount.mod (8), .BR lcmaps_posix_enf.mod (8), .BR lcmaps_tracking_groupid.mod (8), .BR lcmaps_verify_proxy.mod (8), .BR scas (8), .BR scas.conf (5), .BR glexec (1), .BR glexec.conf (5), .BR ees (1), .BR ees.conf (5) .SH AUTHORS LCMAPS and the LCMAPS plug-ins were written by the Grid Middleware Security Team .