LCMAPS_VOMS_POOLGROUP.MOD(8)

NAME
lcmaps_voms_poolgroup.mod - LCMAPS plugin to switch user identity based on VOMS credentials by pool groups

SYNOPSIS
lcmaps_voms_poolgroup.mod [-groupmapfile group-mapfile] [-groupmapdir groupmapdir] [--map-to-secondary-groups] [-override_inconsistency] [-mapall] [-mapmin number of minimal mappings] [-strict_poolprefix_match {yes|no}]

DESCRIPTION
The VOMS poolgroup acquisition plugin is a 'VOMS-aware' plugin similar to the lcmaps_voms_poolaccount.mod.8 plugin, but for groups instead of accounts. The plugin tries to find local groups (more specifically GroupIDs) based on the VOMS information that is available from LCMAPS, in particular the Fully Qualified Attribute Names (FQANs). The actual groups are acquired from a group pool. The resulting list of groups will be looked up in the /etc/groups and/or LDAP directories to determine which Group IDs should be added as a mapping result.

It will first try to find an FQAN to pool name (starting with a dot '.' instead of an alphanumeric character) mapping in the group-mapfile which will provide it with a list of local groups. The group-mapfile is similar to a grid-mapfile.

The groupmapdir directory is going to be used as a persistent and open mapping database. A pool is defined as being a set of groups following a particular pattern in their naming, e.g. pool001 or atlas001. In the directory the plug-in will make a new filename consisting of the lowercase URL-encoded VOMS FQAN.

For example, if the FQAN is mapped to .atlas in the group-mapfile, it will be mapped to the pool groups atlas001, atlas002, etc., the names of which can be found in the groupmapdir.

If there is no pool group assigned to the FQAN yet, the plugin will try to find a free pool group (i.e. one for which the link count is 1) and make a new hardlink to it with the URL-encoded FQAN as name.

When a user returns to this site the plugin will look for the FQAN of the user (URL encoded) in this directory. If found, the corresponding pool group will be reassigned.

Example showing the output of ls -li:
1836080 -rw-r--r-- 2 root root %2fdteam%2f
1836080 -rw-r--r-- 2 root root dteam001
The filename is hardlinked to the mapped group name. Creating this hardlink is designed to be an atomic operation and verified to work on large installations serving multiple services from one NFS-share.

OPTIONS

-groupmapfile group-mapfile
    This file must contain FQAN to pool group name mappings, similar to the grid-mapfile. The same formatting rules of the grid-mapfile apply to the group-mapfile. It is strongly advised to set it to an absolute path to avoid usage of the wrong file(path). In a (setuid-)root application, relative paths are taken with respect to /etc/grid-security/. It is important to not mix the grid-mapfile and group-mapfile.

-groupmapdir groupmapdir"
    A directory used for the group mapping database, similar to the gridmapdir. If this option is unset, the plugin will try to obtain the value from the environment variable GROUPMAPDIR (see ENVIRONMENT). In a (setuid-)root application, relative paths are taken with respect to /etc/grid-security/. It is important to not mix the gridmapdir and groupmapdir directories.

--map-to-secondary-groups
    When enabled, the plug-in will map also the first FQAN of the user to secondary Group IDs, hence there will be no primary Group ID set by this plug-in when enabled. Note that also if the first FQAN does not give a mapping, there will be no primary Group ID set by this plug-in.

-override_inconsistency
    Moving a user from one pool to another (because of a VO change) should normally only be done by changing the group-mapfile indicating the new pool for this user. If the resulting URL-encoded lease (hardlink) already exists but points to a different pool group then would result from the running of this plugin, the plugin would normally fail. This option instructs the plugin to remap to the new pool group.

-mapall
    When enabled, a failure will be triggered if not all of the FQANs were successfully mapped to primary or secondary Group IDs.

-mapmin minimum number of mappings
    This option will set a minimum amount of FQANs that have to be mapped for the plugin to succeed. Default is '0'. Note: if the minimum is unset or set to 0 the plugin will succeed (if no other errors occur) even if no pool groups were found.

-strict_poolprefix_match {yes|no}
    If this is set to 'yes', a line in the group-mapfile like <FQAN> .poolgr will result in mapping pool groups matching only the regexp poolgr[0-9]+. Otherwise it will be allowed to match the wider range of poolgr.* (legacy behaviour).

RETURN VALUES

LCMAPS_MOD_SUCCESS
    Success.

LCMAPS_MOD_FAIL
    Failure.

ENVIRONMENT

GROUPMAPDIR
    When no groupmapdir is specified as option to the plugin, it will try to obtain the file location from this environment variable.

BUGS
Please report any errors to the Nikhef Grid Middleware Security Team <grid-mw-security-support@nikhef.nl>.

SEE ALSO
lcmaps.db(5), lcmaps(3).

AUTHORS
LCMAPS and the LCMAPS plug-ins were written by the Grid Middleware Security Team <grid-mw-security@nikhef.nl>.