Provided by: lcmaps-plugins-basic-poolaccount_1.7.1-1build2_amd64 bug

NAME

       lcmaps_poolaccount.mod - LCMAPS plugin to switch user identity by pool accounts

SYNOPSIS

       lcmaps_poolaccount.mod [-gridmapfile grid-mapfile] [-gridmapdir gridmapdir]
       [-no_wildcard|-disablewildcard] [-override_inconsistency] [-max_mappings_per_credential
       maxnrofmappings] [-strict_poolprefix_match {yes|no}]

DESCRIPTION

       This  plugin is an acquisition plugin and will provide the LCMAPS system with Pool Account
       credential information.  The plugin tries to find a  pool  account  (more  specifically  a
       UserID)  based  on  the Distinguished Name (DN) of the user's end-entity certificate.  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  a  DN 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.  test001.   In  the  directory the plug-in will make a new filename consisting of the
       lowercase URL-encoded Subject-DN of the user.

       For example, if the DN is mapped to .test in the grid-mapfile, it will be  mapped  to  the
       pool accounts test001, test002, 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 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 assigned to the user.

       Example showing the output of ls -li:
       1836080 -rw-r--r-- 2 root root %2fdc%3dorg%2fdc%3dterena%2fdc%3dtcs%2fc%3dnl%2fo%3dnikhef%2fcn%3doscar%20koeroo%20okoeroo%40nikhef%2enl
       1836080 -rw-r--r-- 2 root root test003
       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, GID and all  the  secondary  GIDs  of  the  mapped  local
       (system) account username.

OPTIONS

       -gridmapfile grid-mapfile
              This  file  must  contain  DN 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/.

       -override_inconsistency
              Moving a user from one pool to another 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>):mapcount=<mapnumber>)

       -no_wildcard, -disablewildcard
              When   this   option   is   set  the  plug-in  will  only  match  exact  DNs,  i.e.
              /DC=org/DC=terena/DC=tcs/C=NL/* will not match.

       -strict_poolprefix_match {yes|no}
              If this is set to 'yes', a line in the grid-mapfile like <DN> .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 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>.