.\" In .TH, FOO should be all caps, SECTION should be 1-8, maybe w/ subsection
.\" other parms are allowed: see man(7), man(1)
.\"
.TH lcas_lcmaps_gt_interface 8 "February 11, 2015" "@PACKAGE@ @VERSION@" "Site Access Control"
.SH NAME
lcas_lcmaps_gt_interface \- A Globus GSI-AuthZ plug-in to run LCAS and LCMAPS
.SH SYNOPSIS
.nh
.ad l
.B lcas_lcmaps_gt_interface@SHREXT@

.B lcas_lcmaps_gt4_interface@SHREXT@

.hy
.ad b
.SH DESCRIPTION
This is a plug-in to be loaded from a GSI-AuthZ capable Globus service. The
feature was introduced in Globus GT4 and is available for GT5 and GT6. The
purpose of this call-out is to authorize a user by optionally running the LCAS
framework and subsequently running the LCMAPS framework to map the user
credentials to a Unix account. Both LCAS and LCMAPS are plug-in frameworks,
where the plug-ins to do the real work.

Some of these plug-ins are capable of imposing a certain policy on the user
credentials, others are capable of off-loading the decision to a centralized
service to make the decision or even provide an account mapping in the process.

This plug-in is dynamically loaded during each interaction that requires an
account mapping in the GSI-AuthZ interface of a Globus service. It has no
configuration file for itself, it is configured via environment variables and
the LCAS and LCMAPS configuration files. It can be enabled for use in the
GSI-AuthZ interface using the \fIgsi-authz.conf\fR file, by configuring it to
call the function \fIlcmaps_callout()\fR, which can be done using
\fBgt4-interface-install\fR(8).

.SH ENVIRONMENT VARIABLES

.TP
.BI "LLGT_LOG_FILE"
When this variable is set and it can be opened as file, log output will go to
the given file instead of to syslog. When either $LCAS_LOG_FILE or
$LCMAPS_LOG_FILE is unset, it will also be set to this same file.
.TP
.BI "LLGT_LOG_FACILITY"
Change the default logging facility with the $LLGT_LOG_FACILITY environment
variable. Use the name of (standard syslog) facility names. Example:
LOG_DAEMON, LOG_LOCAL1, etc.
.TP
.BI "LLGT_LOG_IDENT"
The $LLGT_LOG_IDENT can (optionally) be set as the syslog ident value. This
will be the identifying string in syslog for the current process. Not using
this option will let syslog (or one of the GT services) to set these options.
By default the syslog ident will be set to the executable name.
.TP
.BI "LLGT_RUN_LCAS"
Set the environment variable $LLGT_RUN_LCAS to "no", "disabled" or "disable" to
avoid LCAS to run prior to the LCMAPS.

There is a matching ./configure option "\-\-enable\-lcas" which can be used to
change the default behaviour to run LCAS or not. The $LLGT_RUN_LCAS environment
variable can still influence the LCAS run.
.TP
.BI "LLGT_LIFT_PRIVILEGED_PROTECTION"
Normally the callout, after LCMAPS has finished, checks whether it is (still)
running with root privileges (uid, euid, gid or egid) and fails if that is the
case. This is to prevent erroneous configurations to silently result in a
root-account mapping in services that do not have their own checks for this.

When the environment variable $LLGT_LIFT_PRIVILEGED_PROTECTION is set, this
check is disabled\fR. This is NEEDED for services that:

1.) don't user switch, and run as root.

2.) services that expect only a username to be returned and perform the user
switch themselves, e.g. the Globus GSI-OpenSSHd.
.TP
.BI "LLGT_CACHE_CALLOUT"
Set the environment variable $LLGT_CACHE_CALLOUT to "no", "disabled" or
"disable" to disable reusing the result of the `localname' callout for the
`userok' callout. This results in calling the LCAS/LCMAPS authorization twice
for e.g. gsisshd.
.TP
.BI "LLGT_DLCLOSE_LCMAPS"
Set the environment variable $LLGT_DLCLOSE_LCMAPS to "no", "disabled" or
"disable" to prevent calling \fIdlclose()\fR on the LCMAPS library. This might
be needed as a workaround on RH5-based systems in an installation for gsisshd,
when the use of PAM is enabled ("UsePAM Yes" in the
\fI/etc/gsissh/sshd_config\fR).
The underlying bug is a combination between the OpenSSL, VOMS and PAM libraries,
which can trigger a segfault when VOMS is initialized twice. 
.TP
.BI "LLGT_DLCLOSE_LCAS"
Set the environment variable $LLGT_DLCLOSE_LCAS to "no", "disabled" or "disable"
to prevent calling \fIdlclose()\fR on the LCAS library. This might be needed as
a workaround on RH5-based systems. The underlying bug is a combination between
the OpenSSL, VOMS and Globus libraries, which can trigger a segfault when VOMS
is initialized twice, which can happen when LCAS is using a VOMS based plugin.
Normally should not be needed as LCAS is now dlclosed and terminated after
LCMAPS.
.TP
.BI LLGT_NO_CHANGE_USER " (deprecated)
Deprecated $LLGT_NO_CHANGE_USER in favour of $LLGT_LIFT_PRIVILEGED_PROTECTION.
(Deprecation does not mean non-functional anymore)
.TP
.BI LLGT4_NO_CHANGE_USER " (deprecated)
Deprecated $LLGT4_NO_CHANGE_USER in favour of $LLGT_LIFT_PRIVILEGED_PROTECTION.
(Depreciation does not mean non-functional anymore)
.TP
.BI LLGT_VOMS_DISABLE_CREDENTIAL_CHECK
The VOMS credentials are verified by the LCMAPS framework before further
processing is done in the plug-ins. The LCMAPS framework has an API to enable or
disable the verification of the VOMS credentials and this option will
\fBdisable\fR the verification of the VOMS credentials. A vanilla LCMAPS build
will verify the VOMS credentials by default.
.TP
.BI LLGT_VOMS_ENABLE_CREDENTIAL_CHECK
Similar to the $LLGT_VOMS_DISABLE_CREDENTIAL_CHECK environment variable, this
setting will \fBenable\fR the verification of the VOMS credentials, overriding
the LCMAPS default setting to have the verification of VOMS credentials to be
disabled. A vanilla LCMAPS build will verify the VOMS credentials by default,
the OSG build has is disabled by default.
.TP
.BI LLGT_LCAS_LIBDIR
Support for an alternative LCAS_LIBDIR as a run-time setting by exporting such
as $LLGT_LCAS_LIBDIR="@libdir@/liblcas@SHREXT@"
.TP
.BI LLGT_LCAS_MODULEDIR_SFX
When set, used as suffix instead of the default @LCAS_MODULEDIR_SFX@ when
setting the $LCAS_MODULES_DIR variable based on the $LLGT_LCAS_LIBDIR
variable. Default @LCAS_MODULEDIR_SFX@. \fBNOTE\fR: current versions of LCAS
do not yet use the $LCAS_MODULES_DIR variable.
.TP
.BI LLGT_LCMAPS_LIBDIR
Support for an alternative LCMAPS_LIBDIR as a run-time setting by exporting such
as $LLGT_LCMAPS_LIBDIR="@libdir@/liblcmaps@SHREXT@". Must be an absolute path.
Setting this variable will also set the LCMAPS variable $LCMAPS_MODULES_DIR to
the given libdir followed by either the default @LCMAPS_MODULEDIR_SFX@ or the
value of $LLGT_LCMAPS_MODULEDIR_SFX.
.TP
.BI LLGT_LCMAPS_MODULEDIR_SFX
When set, used as suffix instead of the default @LCMAPS_MODULEDIR_SFX@ when
setting the $LCMAPS_MODULES_DIR variable based on the $LLGT_LCMAPS_LIBDIR
variable. Default @LCMAPS_MODULEDIR_SFX@.
.TP
.BI LLGT_ENABLE_DEBUG
If the $LLGT_ENABLE_DEBUG environment variable is set, then the debugging
message logged at level LOG_DEBUG are passed to the log. The scope of this
setting is only within the LCAS-LCMAPS-GT-interface

.SH INTERNAL ENVIRONMENT VARIABLES
.TP
.BI "GATEKEEPER_JM_ID"
An environment variable that is internally set to uniquely identify this
gatekeeper and the job manager.
.TP
.BI "JOB_REPOSITORY_ID"
Similar to the $GATEKEEPER_JM_ID value, but its purpose is for the LCMAPS job
repository plug-in.

.SH LCAS ENVIRONMENT VARIABLES
The following list of LCAS environment variables are handled specially by the
interface.
.TP
.BI "LCAS_MODULES_DIR"
Default directory for LCAS to look for in plug-ins (not yet supported by LCAS).
Will be set based on the values of $LLGT_LCAS_LIBDIR and
$LLGT_LCAS_MODULEDIR_SFX or their defaults.
.TP
.BI "LCAS_LOG_FILE"
When set, LCAS will log there instead of syslog. When unset, it will get the
value of $LLGT_LOG_FILE when that one is set. When compiled with
LCAS_LCMAPS_FORCE_LOG_TO_FILE defined, it will get set to
/var/log/gt_lcas_lcmaps.log.
.TP
.BI "LCAS_DEBUG_LEVEL"
LCAS log level. Default: 3.
.TP
.BI "LCAS_DB_FILE"
Location of the LCAS configuration file. Default for the interface:
@sysconfdir@/lcas/lcas.db

.SH LCMAPS ENVIRONMENT VARIABLES
The following list of LCMAPS environment variables are handled specially by the
interface.
.TP
.BI "LCMAPS_MODULES_DIR"
Default directory for LCMAPS to look for in plug-ins. Will be set based on the
values of $LLGT_LCMAPS_LIBDIR and $LLGT_LCMAPS_MODULEDIR_SFX or their defaults.
.TP
.BI "LCMAPS_LOG_FILE"
When set, LCMAPS will log there instead of syslog. When unset, it will get the
value of $LLGT_LOG_FILE when that one is set. When compiled with
LCAS_LCMAPS_FORCE_LOG_TO_FILE defined, it will get set to
/var/log/gt_lcas_lcmaps.log.
.TP
.BI "LCMAPS_DEBUG_LEVEL"
For LCMAPS 1.5.0 (and newer) the value "5" corresponds to syslog LOG_DEBUG, "4"
corresponds to LOG_INFO, "3" to LOG_NOTICE and so on. The LCMAPS default is to
log up to LOG_INFO.
.TP
.BI "LCMAPS_DB_FILE"
Location of the LCMAPS configuration file. Default for the interface:
@sysconfdir@/lcmaps/lcmaps.db


.SH "RETURN VALUES"
.TP
.B True
The user is authorized and a local Unix account was procured.
.TP
.B False
No mapping was possible.
.SH NOTES
From version 0.3.1 onwards, the interface supports the 'sharing' service: it
then expects an additional argument, (a PEM string) containing the credential on
which the mapping should be based.

From version 0.3.0 onwards, the interface tries to forward the requested
username to LCMAPS (for version 1.6.0 and up). The mapping plugins can use this
to support multiple username entries in the grid-mapfile, or enforcing
pool account mappings to a specific pool account.
.SH BUGS
Please report any errors to the Nikhef Grid Middleware Security Team
<grid-mw-security-support@nikhef.nl>.
.SH "SEE ALSO"
.BR gt4-interface-install (8),
.BR lcas.db (5), 
.BR lcas (3),
.BR lcmaps.db (5), 
.BR lcmaps (3).
.SH AUTHORS
LCMAPS and the LCMAPS plug-ins were written by the Grid Middleware Security Team 
<grid-mw-security@nikhef.nl>.