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>.