Provided by: lcmaps-plugins-voms_1.7.1-1ubuntu2_amd64 bug

NAME

       lcmaps_voms_poolaccount.mod  -  LCMAPS  plugin  to  switch  user  identity  based  on VOMS
       credentials by pool accounts

SYNOPSIS

       lcmaps_voms_poolaccount.mod [-gridmapfile grid-mapfile] [-gridmapdir gridmapdir] [--do-
       not-add-primary-gid-from-mapped-account] [--add-primary-gid-from-mapped-account] [--add-
       primary-gid-as-secondary-gid-from-mapped-account] [--do-not-add-secondary-gids-from-
       mapped-account] [--add-secondary-gids-from-mapped-account] [--use-voms-
       gid|--use_voms_gid|-use_voms_gid] [--use-account-gid] [--do-not-require-primary-gid]
       [--require-primary-gid] [--do-not-use-secondary-gids|-do_not_use_secondary_gids]
       [-override_inconsistency] [-max_mappings_per_credential maxnrofmappings]
       [-strict_poolprefix_match {yes|no}]

DESCRIPTION

       The   VOMS   poolaccount   acquisition  plugin  is  a  'VOMS-aware'  modification  of  the
       lcmaps_poolaccount.mod.8  plugin.   The  plugin  tries  to  find  a  local  account  (more
       specifically  a  UserID)  based  on the VOMS information that is available from LCMAPS, in
       particular the Fully Qualified Attribute Names (FQANs).  The account is acquired  from  an
       account pool. The accounts in the account pool must exist on the system, either locally or
       through a centralised account database, e.g. LDAP.

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

       The gridmapdir directory is going to be used as a persistent and open mapping database.  A
       pool is defined as being a set of accounts 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 Subject-DN of the user, followed by the name of
       the Unix groups that are already mapped by other plug-ins.

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

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

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

       Example showing the output of ls -li:
       1836080 -rw-r--r-- 2 root root %2fo%3ddutchgrid%2fo%3dusers%2fo%3dnikhef%2fcn%3djohn%20doe:pool:group004
       1836080 -rw-r--r-- 2 root root pool003
       The  filename is hardlinked to the mapped account 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.

       The plugin will resolve the UID of the mapped local (system) account username.

OPTIONS

       -gridmapfile grid-mapfile
              This  file  must contain FQAN to pool name mappings.  It is strongly advised to set
              this option and to set it  to  an  absolute  path  to  avoid  usage  of  the  wrong
              file(path).   When  unset,  the plugin will try to obtain the value from one of the
              environment variables (see ENVIRONMENT). When those are  also  unset,  the  default
              depends  on  whether  the  plugin  runs  inside a (setuid-)root application. In the
              (setuid-)root  case,  the  default  is  /etc/grid-security/grid-mapfile.   In   the
              non-(setuid-)root  case,  the  default  is  <homedir>/.gridmap.  In a (setuid-)root
              application, relative paths are taken with respect to /etc/grid-security/.

       -gridmapdir gridmapdir
              A directory used for the mapping database.  If this option  is  unset,  the  plugin
              will  try  to  obtain  the  value  from  the  environment  variable GRIDMAPDIR (see
              ENVIRONMENT).  In a  (setuid-)root  application,  relative  paths  are  taken  with
              respect to /etc/grid-security/.

       --do-not-add-primary-gid-from-mapped-account
              After  the  account  is  mapped,  do  NOT add the primary Group ID from the passwd-
              file/LDAP of the mapped account as a part of the mapping result.  Default is NOT to
              add  the  primary  Group ID, unless --use-account-gid is specified. See also --add-
              primary-gid-from-mapped-account,    --add-primary-gid-as-secondary-gid-from-mapped-
              account and --use-account-gid.

       --add-primary-gid-from-mapped-account
              After  the account is mapped, add the primary Group ID from the passwd-file/LDAP of
              the mapped account as a part of the mapping result.  Default  is  NOT  to  add  the
              primary  Group  ID,  unless  --use-account-gid is specified. See also --do-not-add-
              primary-gid-from-mapped-account,    --add-primary-gid-as-secondary-gid-from-mapped-
              account and --use-account-gid.

       --add-primary-gid-as-secondary-gid-from-mapped-account
              After  the account is mapped, add the primary Group ID from the passwd-file/LDAP of
              the mapped account as a secondary  Group  ID  as  a  part  of  the  mapping  result
              (possibly  in  addition to adding it as a primary Group ID).  Default is NOT to add
              it at all. See  also  --do-not-add-primary-gid-from-mapped-account,  --add-primary-
              gid-from-mapped-account and --use-account-gid.

       --do-not-add-secondary-gids-from-mapped-account
              After  the account is mapped, do NOT add the secondary Group ID(s) from the groups-
              file/LDAP of the mapped account as secondary Group ID(s) as a part of  the  mapping
              result.   Default  is  NOT to add the sGIDs, unless --use-account-gid is specified.
              See also --add-secondary-gids-from-mapped-account --use-account-gid.

       --add-secondary-gids-from-mapped-account
              After the account is mapped,  add  the  secondary  Group  ID(s)  from  the  groups-
              file/LDAP  of  the mapped account as secondary Group ID(s) as a part of the mapping
              result.  Default is NOT to add the secondary Group ID(s), unless  --use-account-gid
              is  specified.   See  also  --do-not-add-secondary-gids-from-mapped-account  --use-
              account-gid.

       --use-voms-gid|--use_voms_gid|-use_voms_gid
              This option has the opposite effect of the  option  --use-account-gid,  instructing
              the  plugin  NOT to add the mapped account group information to the mapping result.
              This is currently already the default and hence this option  has  no  effect.   See
              also --use-account-gid.

       --use-account-gid
              By  default this plugin will NOT add the primary and secondary Group ID(s) from the
              passwd-file/groups-file/LDAP of the mapped account as part of the  mapping  result.
              Specifying  this  option  will  override  that  default.  Part  or all of the group
              information can still be added or removed by using the --add-*  and  --do-not-add-*
              flags.  See also --use-voms-gid.

       --require-primary-gid
              The group names already present in the LCMAPS mapping store prior to the running of
              this plugin will be used to create the (URL encoded) lease name in the  gridmapdir.
              This  option  can  be  used to enforce the existence of a primary Group ID prior to
              running this plug-in, which can be done by running other plugins earlier on in  the
              policy. Default is not to require a primary GID.

       --do-not-require-primary-gid
              This   option   has  the  opposite  effect  of  the  option  --require-primary-gid,
              instructing the plugin NOT to enforce the presence of a primary GID  prior  to  its
              running. This is currently already the default and hence this option has no effect.
              See also --require-primary-gid.

       --do-not-use-secondary-gids
              This option will prevent adding mapped secondary group names  to  the  lease  name.
              Default is: add secondary group names to the lease name.

       -override_inconsistency
              Moving  a  user  from  one pool to another (because of a VO change) should normally
              only be done by changing the grid-mapfile indicating the new pool  for  this  user.
              If  the  resulting  URL-encoded  lease  (hardlink)  already  exists but points to a
              different pool account 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 account.

       -max_mappings_per_credential maximum number of mappings
              This feature is deprecated. It was  intended  to  work  together  with  the  Globus
              Dynamic Account Service/Workspace Service.  This value indicates the maximum number
              of accounts a user, or more specifically a set of credentials (=DN + FQANS), can be
              mapped  to.  Normally  this  number is 1.  But if each job should run under its own
              account the number should be increased.   Whether  LCMAPS  will  actually  use  the
              mapcounter  depends  on  the  LCMAPS  interface  being  used.  The  lease  name (or
              poolindex) in the case of mapcounters looks like:

                  url_encoded(<DN>):gid1[:gid2[:gid3[...]]]:mapcount=<mapnumber>)

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

RETURN VALUES

       LCMAPS_MOD_SUCCESS
              Success.

       LCMAPS_MOD_FAIL
              Failure.

ENVIRONMENT

       GRIDMAP | GLOBUSMAP | globusmap | GlobusMap
              When no grid-mapfile is specified as option to the plugin, it will  try  to  obtain
              the file location from one of these environment variables.

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

NOTES

       Since version 1.6.0 the voms_poolaccount plugin also takes the  requested username   (such
       as  forwarded  by gsissh) into consideration. When present, the resulting pool account has
       to match it in order for the plugin to succeed. This  requires  LCMAPS  version  1.6.0  or
       newer.

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