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_poolac‐
       count.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 result‐
       ing 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 char‐
       acter)  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  de‐
       fined  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  di‐
       rectory. 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, rela‐
              tive  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 un‐
              set, the plugin will try to obtain the value from the environment variable GROUPMAPDIR (see  ENVI‐
              RONMENT).   In a (setuid-)root application, relative paths are taken with respect to /etc/grid-se‐
              curity/.  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 pri‐
              mary 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-sup‐
       port@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-securi‐
       ty@nikhef.nl>.

Stichting FOM/Nikhef                            February 6, 2015                    LCMAPS_VOMS_POOLGROUP.MOD(8)