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