NAME

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

SYNOPSIS

       lcmaps_poolaccount.mod [-gridmapfile gridmapfile] [-gridmapdir gridmapdir]
       [-override_inconsistency] [-max_mappings_per_credential max nr of mappings]

DESCRIPTION

       This plugin is a Acquisition Plugin and will provide the LCMAPS system with  Pool  Account
       information.  To  do  this  it  needs to look up the Distinguished Name (DN) from a user's
       certificate in the gridmapfile. If this DN is found in  the  gridmapfile  the  plugin  now
       knows  to  which  pool  of  local  system  accounts  the user will be mapped. The poolname
       (starting with a dot ('.') instead of an alphanumeric character) will  be  converted  into
       the an account from a list of local accounts. This list is located in the \ gridmapdir and
       is made out of filenames. These filenames correspond  to  the  system  poolaccount  names.
       (E.g.  if  a  DN  corresponds  to  .test in the gridmapfile, it will be mapped to test001,
       test002, etc., which names can be found in the gridmapdir.

       If there is no pool account assigned to the user yet, the  plugin  will  get  a  directory
       listing  of  the  gridmapdir.   This  list  will contain usernames corresponding to system
       accounts specially designated for pool accounting.  If the plugin resolved the mapping  of
       a  certain  pool name, let's say '.test', the plugin will look into the directory list and
       will find the first available file in the list corresponding with 'test' (e.g.  'test001')
       by checking the number of links to its i-node.  If this number is 1, this account is still
       available.  To lease this account a second hard link is  created,  named  after  the  URL-
       encoded, decapitalized DN.

       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 poolaccount will be assigned to the user.

       The plugin will resolve the  UID,  GID  and  all  the  secondary  GIDs  belonging  to  the
       poolaccount.  When  this has been done and there weren't any problems detected, the plugin
       will add this information to a datastructure in the Plugin Manager.  For version 1.6.0 and
       newer,  if  a   requested  username   is specified (such as via the gsisshd) this needs to
       match the resulting poolaccount for the plugin to succeed, see  NOTES .  The  plugin  will
       finish  its  run  with  a  LCMAPS_MOD_SUCCESS.  This result will be reported to the Plugin
       Manager which started this plugin and it  will  forward  this  result  to  the  Evaluation
       Manager,  which  will  take  appropriate actions for the next plugin to run. Normally this
       plugin would  be  followed  by  an  Enforcement  plugin  that  can  apply  these  gathered
       credentials in a way that is appropriate to a system administration's needs.

OPTIONS

       -gridmapfile gridmapfile
              If this option is set, it will override the default path of the gridmapfile.  It is
              advised to use an absolute path to the gridmapfile to  avoid  usage  of  the  wrong
              file(path).

       -gridmapdir gridmapdir
              If  this  option is set, it will override the default path to the gridmapdir. It is
              advised to use an absolute path to the gridmapdir to avoid usage of the wrong path.

       -override_inconsistency
              Moving a user from one pool to another (because of a VO change) should only be done
              by  changing  the gridmapfile indicating the new pool for this user.  If a user has
              already been mapped previously to a poolaccount, there is a  link  present  between
              this poolaccount and his DN.  In the good old days prior to LCMAPS, a 'pool change'
              would  still  result  in  a  mapping  to  the  old  pool  account,  neglecting  the
              administrative  changes  in  the  gridmapfile.   LCMAPS corrects this behaviour: By
              default the poolaccount plugin will fail if the pool designated by the  gridmapfile
              doesn't  match  the  previously  mapped poolaccount leasename.  If the site doesn't
              want a failure on this inconsistency it can  turn  on  this  parameter.   When  the
              inconsistency is detected the plugin will automatically unlink the previous mapping
              and will proceed by making a new lease from the new pool.

       -max_mappings_per_credential max nr of mappings
              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.   The
              leasename (or poolindex) in this case looks like:

                  url_encoded(<DN>):mapcount=<mapnumber>)

       -no_wildcard
              If this option is set, wildcards cannot be used in the grid-mapfile (on by default)

       -strict_poolprefix_match {yes|no}
              Default  is  'yes'.   If  this  is  set  to  'yes',  a line in the gridmapfile like
              <DN>.pool will result in accounts matching the regexp 'pool[0-9]+'.   Otherwise  it
              will be allowed to match 'pool.*' (legacy behaviour).

RETURN VALUES

       LCMAPS_MOD_SUCCESS
              Success.

       LCMAPS_MOD_FAIL
              Failure.

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

                                        February 25, 2013               LCMAPS_POOLACCOUNT.MOD(8)