contribs/pam/README

Module Name:
  pam_slurm

Authors:
  Chris Dunlap <cdunlap@llnl.gov>
  Jim Garlick  <garlick@llnl.gov>
  Moe Jette    <jette1@llnl.gov>

Management Groups Provided:
  account

System Dependencies:
  libslurm.so

Overview:
  Restricts access to compute nodes in a cluster using Slurm.

Recognized Arguments:
  debug; no_sys_info; no_warn; rsh_kludge; rlogin_kludge

Description:
  This module restricts access to compute nodes in a cluster where the
  Slurm workload manager is in use.  Access is granted to root, any user
  with an Slurm-launched job currently running on the node, or any user
  who has allocated resources on the node according to the Slurm database.

  The behavior of this module can be modified with the following flags:

    debug         - log debugging information to the system log file
    no_sys_info   - suppress system logging of "access granted for user ...",
                    access denied and other errors will still be logged
    no_warn       - suppress warning messages to the application
    rsh_kludge    - prevent truncation of first char from rsh error msg
    rlogin_kludge - prevent "staircase-effect" following rlogin error msg

Notes:
  This module will not work on systems where the hostname returned by the
     gethostname() differs from the Slurm node name.
  rsh_kludge - The rsh service under RH71 (rsh-0.17-2.5) truncates the first
     character of this message.  The rsh client sends 3 NUL-terminated ASCII
     strings: client-user-name, server-user-name, and command string.  The
     server then validates the user.  If the user is valid, it responds with a
     1-byte zero; otherwise, it responds with a 1-byte one followed by an ASCII
     error message and a newline.  RH's server is using the default PAM
     conversation function which doesn't prepend the message with a
     single-byte error code.  As a result, the client receives a string,
     interprets the first byte as a non-zero status, and treats the
     remaining string as an error message.  The rsh_kludge prepends a
     newline which will be interpreted by the rsh client as an error status.
  rlogin_kludge - The rlogin service under RH71 (rsh-0.17-2.5) does not perform
     a carriage-return after the PAM error message is displayed which results
     in the "staircase-effect" of the next message. The rlogin_kludge appends
     a carriage-return to prevent this.

Examples / Suggested Usage:
  Use of this module is recommended on any compute node where you want to
  limit access to just those users who are currently scheduled to run jobs.

  For /etc/pam.d/ style configurations where modules live in /lib/security/,
  add the following line to the PAM configuration file for the appropriate
  service(s) (eg, /etc/pam.d/system-auth):

    account    required     /lib/security/pam_slurm.so

  If you always want to allow access for an administrative group (eg, wheel),
  stack the pam_access module ahead of pam_slurm:

    account    sufficient   /lib/security/pam_access.so
    account    required     /lib/security/pam_slurm.so

  Then edit the pam_access configuration file (/etc/security/access.conf):

    +:wheel:ALL
    -:ALL:ALL

  When access is denied because the user does not have an active job running
  on the node, an error message is returned to the application:

    Access denied: user foo (uid=1313) has no active jobs.

  This message can be suppressed by specifying the "no_warn" argument in the
  PAM configuration file.