GLEXEC

NAME
SYNOPSIS
DESCRIPTION
OPTIONS
ENVIRONMENT -- for gLExec
ENVIRONMENT -- for executable
RETURN VALUES
INSTALLATION
FILES
BUGS
LIBRARY PATH NOTES
SEE ALSO
AUTHORS
COPYRIGHT

NAME

gLExec - execute a command as another user based on ones grid credentials

SYNOPSIS

glexec <command> [arguments]

glexec <-h|-v|-V>

(deprecated) glexec <target uid> <target gid> <cmd> [args]

DESCRIPTION

gLExec takes as input an X.509 proxy and passes this information on to both LCAS and LCMAPS for authentication and authorization. These two components determine the validity of the credentials and based on their configurations decide the mapping to a local Unix account. Once the mapping has been determined, gLExec will execute the command with given arguments as specified. Typically this will be done with the credentials of the local Unix user to which has been mapped.

gLExec can be installed in either user-switching or logging-only mode. In logging only mode, no actual user-switch is performed, and hence the target executable will be run with the same credentials and permissions as the calling user, but the mapping as it would have been done, will be logged. Furthermore gLExec will still fail in this mode if either LCAS or LCMAPS denies or fails.

gLExec clears all environment variables except those starting with GLEXEC_ and those explicitly whitelisted in the glexec.conf(5). Variables starting with MALLOC_ cannot be whitelisted and will always be lost. Furthermore, note that the variable LD_LIBRARY_PATH is ignored for setuid applications. To overcome these limitations, one can use the glexec_wrapenv.pl and glexec_unwrapenv.pl scripts.
A number of variables will be set by gLExec for the target environment. See further under ENVIRONMENT for individual details.

OPTIONS

-h

Displays usage information.

-v

Displays the version of gLExec.

-V

Displays the compile-time defaults. Only available for root.

ENVIRONMENT -- for gLExec

GLEXEC_CLIENT_CERT

should point to a file containing a valid proxy on which the user switch will be based. This is typically a proxy of the payload user. The file should be readable/writable only by the calling user.

X509_USER_PROXY

should point to a file containing a valid proxy used to authenticate at, for example, a SCAS or PEPd. This is a proxy of the pilot job user. NOTE: gLExec will reset this variable to a suitable proxy for the payload user.

GLEXEC_SOURCE_PROXY

when set, the file it points to will be copied for use as proxy by the payload user. The file should be readable/writable only by the calling user. When unset it will default to the file pointed to by GLEXEC_CLIENT_CERT.

GLEXEC_TARGET_PROXY

when set, the contents of GLEXEC_SOURCE_PROXY or its default value will be copied to this location, with the credentials of the target user. When unset, its default depends on the gLExec running mode, in user switching mode its default is a unique filename /tmp/x509up_u<uid>.glexec.XXXXXX where <uid> will be the target uid and XXXXXX will be 6 random letters. In logging only mode its default value will be equal to GLEXEC_SOURCE_PROXY or its default, but no file will be copied.

GLEXEC_MODE (deprecated)

Set gLExec in either of two modes:

lcmaps_get_account -- Default. Normally, one operates gLExec in this mode and this makes sure that LCMAPS acquires all resources necessary to get an account. The arguments for gLExec in this mode are the command and its arguments.

(deprecated) lcmaps_verify_account -- The same as above, except necessary resources are not allocated and LCMAPS will only return the uid and gui for the mapping. The arguments for gLExec in this mode are first the target uid and target gid, followed by the command and its arguments.
NOTE
: Setting lcmaps_verify_account will trigger a user error. If you really need this functionality, please contact us (the developers) to find another solution or to restore the support for this functionality.

SSL_CLIENT_CERT (deprecated)

Old style of passing a certificate. This variable contains the whole certificate and not a path to a certificate.
NOTE
: the use of this variable is no longer supported. It is error prone and now also removed from gLExec completely. Use GLEXEC_CLIENT_CERT instead.

ENVIRONMENT -- for executable

The following environment variables are set up during the execution of gLExec and are meant to have sensible meaning in the execution environment of the requested command:

PATH

/usr/local/bin:/usr/bin:/bin

HOME

in switching mode, set to the mapped user’s home directory, e.g. /home/pool0001, in logging only mode it is set to the calling user’s home directory.

USER
LOGNAME

in switching mode, both are set to the username of the mapped user. In logging only mode both are set to that of the calling user.

X509_USER_PROXY

set to (the default of) GLEXEC_TARGET_PROXY. When in logging only mode GLEXEC_TARGET_PROXY is unset, no file will be copied and this variable will point to the same location as (the default of) GLEXEC_SOURCE_PROXY.

IMPORTANT although for the payload users, in value GLEXEC_TARGET_PROXY is equal to this variable, payload users should only use the X509_USER_PROXY variable.

GLEXEC_TARGET_PROXY (deprecated)

Do not use in the target environment. For the target user this variable has the same value as X509_USER_PROXY. We only set it for backwards compatibility and it is foreseen to be no longer set in a future version.

RETURN VALUES

Upon successful execution of a program, the return value from gLExec will simply be the return value of the program that was executed. Otherwise, gLExec quits with the following limited range of return values:

201 - Client error:

This error code is triggered when the user (caller of gLExec) has to change something in order for gLExec to be able to succeed. Some example situations: the input files (like proxy certificates) might have the wrong permissions or do not exist; the executable to be executed doesn’t exist or has unacceptable file permissions.

202 - Internal gLExec error:

This error code has to be handled by the system administrator of the machine. This might be due to wrong permission bits on the configuration file, initialization errors of LCAS and/or LCMAPS or other system specific errors that can only be addressed by somebody with sufficient rights on the machine.

203 - Authorization error:

Everything went ok, but the user is not authorized. This could be triggered because the calling process was not in the white list and therefore not privileged to use gLExec. The other reason is that LCAS and/or LCMAPS failed to authorize the (real) user and gain an account mapping.

204 - Child return value overlap:

This error code is triggered when gLExec is in linger mode (activated by default) and when the called child process returns an exit code that overlaps with one of the error code numbers 201, 202, 203 and 204.

126 - Shell returns that the executable can’t be executed:

This error code is triggered when the execve() call failed to execute the command, because of permission, execution or system problems found during the call for the executable that was tried to be set up. The shell code is not caught, but forwarded as an error code from the actual child process.

INSTALLATION

NOTE: this section is exclusively valid from gLExec version 0.7 and higher.
The preferred ownership for the glexec executable is root.root or root.glexec. For the config file, the preferred ownership is glexec.root.

For switching mode, the preferred set of permissions for the executable is 4711 and for the config file 0400:
-rws--x--x 1 root root 12345 2010-02-29 12:34 glexec
-r-------- 1 glexec root 123 2010-02-29 12:34 glexec.conf

For logging only mode, the preferred set of permissions for the executable is 0711 and for the config file 0444:
-rwx--x--x 1 root root 12345 2010-02-29 12:34 glexec
-r--r--r-- 1 glexec root 123 2010-02-29 12:34 glexec.conf

These setups also work when either or both are installed on NFS mounts with root-squash enabled.

FILES

/opt/glite/etc/glexec.conf

BUGS

Reading and writing of proxy files will generally be done with either flock(2) or fcntl(2) locks. However be aware that these mechanisms do not always reliably work on NFS file systems. See flock(2) for more details.

LIBRARY PATH NOTES

The effective library path of the system and shell must be able to locate the required runtime libraries for gLExec itself, LCAS, LCMAPS and their dynamically loaded plug-ins. In an ideal world this would mean to have all the required libraries be installed in system native locations on the file system. In practice you are required to add the paths /opt/globus/lib/ and /opt/glite/lib/ to the run-time library search paths. Since gLExec is a setuid application, LD_LIBRARY_PATH is ignored, see ld.so(8), so this leaves adding the path to the /etc/ld.so.conf{.d/glite} file or directory or hoping for a correctly applied set of RPATH values in the libraries. When using a version built by ETICS, only the ld.so.conf option is available since ETICS strips the RPATH values in the libraries. If you build all the components from source without ETICS, these RPATHs take precedence.

SEE ALSO

glexec.conf(5), execve(2), flock(2), fcntl(2), ld.so(8), glexec_wrapenv.pl(1), glexec_unwrapenv.pl(1)

http://www.nikhef.nl/pub/projects/grid/gridwiki/index.php/GLExec

AUTHORS

Written by Oscar Koeroo & Mischa Sallé (from Jan 2009)
Written by Gerben Venekamp (until Jan 2009)

COPYRIGHT

Copyright © 2009-2010 EGEE