[pam] rewrite pam_oar_adopt and its documentation

Author: Vincent Danjean

Makefiles/node.mk

@@ -9,7 +9,8 @@ SBINDIR_FILES=$(SRCDIR)/tools/oarnodecheck/oarnodecheckrun.in \
 SHAREDIR_FILES= $(SRCDIR)/scripts/prologue \
 		$(SRCDIR)/scripts/epilogue \
 		$(SRCDIR)/tools/sshd_config.in \
-		$(SRCDIR)/scripts/oar-node-service
+		$(SRCDIR)/scripts/oar-node-service \
+		$(SRCDIR)/tools/$(OARSH_DIR)/pam_oar_adopt.conf
 
 MAN8DIR_FILES = $(SRCDIR)/man/man8/oarnodecheckrun.8 \
 				$(SRCDIR)/man/man8/pam_oar_adopt.8

sources/core/man/man8/pam_oar_adopt.pod

@@ -24,9 +24,11 @@ Please note that while using ssh is very convenient, B<oarsh> provides extra fea
 
 =head1 CONFIGURATION
 
-To B<enable> this feature, one must configure B<pam_oar_adopt> in PAM and make sure the B</etc/oar/pam_oar_adopt_enabled> file exists on nodes. Removing this file allows one to disable B<pam_oar_adopt> (let I<ssh> return to its normal behavior) without requiring to undo the whole PAM configuration.
+To B<enable> this feature, one must configure B<pam_oar_adopt> in PAM and activate it in its configuration file (B</etc/oar/pam_oar_adopt.conf>).
 
-Also make sure the B<ssh> service (on port 22, not OAR's dedicated ssh service on port 6667) enables PAM. B</etc/ssh/sshd_config> must contain:
+=head2 PAM CONFIGURATION
+
+Make sure the B<ssh> service (on port 22, not OAR's dedicated ssh service on port 6667) enables PAM. B</etc/ssh/sshd_config> must contain:
 
  UsePAM yes
 
@@ -38,17 +40,58 @@ Follows an example of configuration of PAM with B<pam_oar_adopt>:
 
 The following can be set as the first PAM directive in common-account:
 
- account required      pam_exec.so quiet debug stdout /usr/sbin/pam_oar_adopt -a
+ account required      pam_exec.so quiet stdout /usr/sbin/pam_oar_adopt -a
 
 =item B</etc/pam.d/common-session> and B</etc/pam.d/common-session-noninteractive>
 
 The following can be set as the last PAM directives in common-session and common-session-noninteractive:
 
- session required   pam_exec.so stdout /usr/sbin/pam_oar_adopt -s
+ session required   pam_exec.so quiet stdout /usr/sbin/pam_oar_adopt -s
  session optional   pam_env.so readenv=1 envfile=/var/lib/oar/pam.env
 
 =back
 
+On Debian-like systems, one can also use the B<pam-auth-update> command to configure PAM and, by default, this PAM profile is installed with the oar-node package.
+
+=head2 PAM_OAR_ADOPT CONFIGURATION
+
+The B</etc/oar/pam_oar_adopt.conf> file contains the following configuration options:
+
+=over
+
+=item B<MODE>
+weather B<pam_oar_adopt> is enabled or not. Possible values are:
+
+=over
+
+=item B<enforced>: B<pam_oar_adopt> is enabled and will prevent any ssh connection to nodes that are not properly reserved.
+
+=item B<disabled>: B<pam_oar_adopt> is disabled.
+
+=back
+
+By default, B<pam_oar_adopt> is disabled.
+
+[DEPRECATED] For compatibility reasons, if the B<MODE> is not set and the B</etc/oar/pam_oar_adopt_enabled> file is present, then B<pam_oar_adopt> is enabled.
+
+=item B<WARN>
+
+In B<disabled> mode, B<pam_oar_adopt> will warn users about what would have been done if it was enabled. Possible values are:
+
+=over
+
+=item B<yes>: warn users (default).
+
+=item B<no>: do not warn users about B<pam_oar_adopt> doing nothing.
+
+=back
+
+=item B<USER_UID_MIN>
+
+In B<enforced> mode, B<pam_oar_adopt> will ignore (not prevent) ssh connections from users with a UID lower than B<USER_UID_MIN>. This is useful to allow system users to connect to nodes without being part of a job. The default value is 1000.
+
+=back
+
 =head1 NOTES
 
 It is a good practice to prevent users to connect to OAR nodes outside of jobs (except system users: at least root and the B<oar> user).

sources/core/tools/oarsh/pam_oar_adopt

@@ -16,6 +16,45 @@ CGROUP_MOUNT_POINT=$(sed -ne 's/^[^ ]\+ \([^ ]\+\) cgroup2 .*/\1/p' /proc/mounts
 OAR_CGROUP_BASE="$CGROUP_MOUNT_POINT/oar.slice"
 USER_UID_MIN=1000
 
+exit_with_warning_or_error() {
+    if [ "$MODE" = "enforced" ]; then
+	printf "$1\n\n" 1>&2
+	exit 1
+    elif [ "$WARN" = true ]; then
+	printf "pam_oar_adopt disabled, warns only: %s\n" "$1"
+    fi
+    exit 0
+}
+
+pam_oar_adopt_load_config() {
+    if [ -f "/etc/oar/pam_oar_adopt_enabled" ]; then
+        MODE="enforced"
+    else
+        MODE="disabled"
+    fi
+    WARN=true
+
+    if [ -r /etc/oar/pam_oar_adopt.conf ]; then
+        . /etc/oar/pam_oar_adopt.conf
+    fi
+
+    case "$MODE" in
+        enforced|disabled) ;;
+	*)
+	    echo "Invalid value for MODE in /etc/oar/pam_oar_adopt.conf." 1>&2
+	    exit 0
+	    ;;
+    esac
+    case "${WARN,,}" in
+	1|yes|on|true) WARN=true ;;
+	0|no|off|false) WARN=false ;;
+	*)
+	    echo "Invalid value for WARN in /etc/oar/pam_oar_adopt.conf." 1>&2
+	    WARN=true
+	    ;;
+    esac
+}
+
 get_oar_cgroups_of_user() {
     # Exit if the PAM service is not sshd (e.g. su, su-l, sudo, sudo-i, ...)
     if [ "$PAM_SERVICE" != "sshd" ]; then
@@ -38,21 +77,17 @@ get_oar_cgroups_of_user() {
         exit 0
     fi
 
-    # Exit if oar.slice does not exist (job_resource_manager did not run yet, not job run since last reboot)
     if [ ! -d "$OAR_CGROUP_BASE" ]; then
-        cat <<EOF 1>&2
-No running job found for $OAR_USER on this node.
-
-EOF
-        exit 1
+        # Exit if oar.slice does not exist (job_resource_manager did not run yet, not job run since last reboot)
+        exit_with_warning_or_error "No running job found for $OAR_USER on this node."
     fi
 
     readarray -t OAR_SLICES < <( cd "$OAR_CGROUP_BASE" && ls -d "oar-u$USER_UID.slice/oar-u$USER_UID"-j*.slice 2>/dev/null )
     OAR_SLICE=${OAR_SLICES[0]}
 }
 
 pam_account() {
-    pam_oar_adopt_enabled_or_exit
+    pam_oar_adopt_load_config
 
     get_oar_cgroups_of_user
 
@@ -61,34 +96,22 @@ pam_account() {
     # - the user has more than one cgroup or one but without all cores
     # - the user has one cgroup with all cores
     if [ -z "$OAR_SLICE" ]; then
-        cat <<EOF 1>&2
-No running job found for $OAR_USER on this node.
-
-EOF
-        exit 1
+        exit_with_warning_or_error "No running job found for $OAR_USER on this node."
     elif [ ${#OAR_SLICES[*]} -ne 1 ]; then
-        cat << EOF 1>&2
-Cannot connect to node using 'ssh', because it appears there are more than one
+        exit_with_warning_or_error "Cannot connect to node using 'ssh', because it appears there are more than one
 job on running on the node. Make sure to only have one job on the node, or use
-'oarsh' to connect to a specific job.
-
-EOF
-        exit 1
+'oarsh' to connect to a specific job."
     elif [ "$(< "$OAR_CGROUP_BASE/$OAR_SLICE"/cpuset.cpus.effective)" != "$(< "${OAR_CGROUP_BASE}"/cpuset.cpus.effective)" ]; then
-        cat << EOF 1>&2
-Cannot connect to node using 'ssh' because not all its compute resources
+        exit_with_warning_or_error "Cannot connect to node using 'ssh' because not all its compute resources
 (e.g. CPU cores or threads) are assigned to the job which reserves it.
-Reserve the whole node, or use 'oarsh' instead.
-
-EOF
-        exit 1
+Reserve the whole node, or use 'oarsh' instead."
     else
         exit 0
     fi
 }
 
 pam_session() {
-    pam_oar_adopt_enabled_or_exit
+    pam_oar_adopt_load_config
 
     get_oar_cgroups_of_user
 
@@ -110,16 +133,23 @@ pam_session() {
     fi
 
     if [ ! -d /var/lib/oar ]; then
-        echo "OAR directory not found: /var/lib/oar." 1>&2
-        exit 1
+        exit_with_warning_or_error "OAR directory not found: /var/lib/oar."
     fi
 
+    if [ "$MODE" != enforced ]; then
+        if [ "$WARN" = true ]; then
+	    printf "pam_oar_adopt disabled, not adding job into cgroup.\n"
+	fi
+        return 0
+    fi
+    # We are in enforced mode here, handling cgroup assignment
+
     # To have the job environment variables, we create a symkink to the already
     # created job environment file and let pam_env load it.
     OAR_JOB_ENV=${OAR_SLICE%.slice}
     OAR_JOB_ENV=/var/lib/oar/${OAR_USER}_${OAR_JOB_ENV#*-j}.env
     if [ ! -e "$OAR_JOB_ENV" ]; then
-        echo "Could not find job env file." 1>&2
+        echo "OAR directory not found: /var/lib/oar." 1>&2
         exit 1
     fi
 
@@ -134,12 +164,6 @@ pam_session() {
     done
 }
 
-pam_oar_adopt_enabled_or_exit() {
-    if [ ! -f "/etc/oar/pam_oar_adopt_enabled" ]; then
-        exit 0
-    fi
-}
-
 if [ $# -eq 0 ]; then
    echo "Please provide the PAM mode." 1>&2
    exit 1

sources/core/tools/oarsh/pam_oar_adopt.conf

@@ -0,0 +1,38 @@
+# configuration file for the pam_oar_adopt PAM module
+#
+# This file is sourced by the pam_oar_adopt script run by the pam_exec module
+# that is used when the sshd PAM service is invoked. For any other PAM service,
+# the pam_oar_adopt script does nothing.
+# When activated, the pam_oar_adopt script will enforce the OAR job cgroup
+# assignment and environment variables setting for the user if the user has
+# one, and only one valid OAR job on the node using all the ressources. Else,
+# the direct ssh connection will be refused (oarsh must be then used).
+
+# The mode of the pam_oar_adopt module. Possible values are:
+# - enforced: the module will enforce the OAR job cgroup assignment and
+#   environment variables setting. If the user does not have a valid OAR job
+#   on the node, the ssh connection will be refused.
+# - disabled: the module will not enforce the OAR job cgroup assignment and
+#   environment variables setting. Only a warning message will be printed
+#   by default (see below). A warning message will also be printed if the
+#   connection would have been refused if in enforced mode (but the connection
+#   will not be refused). This mode is useful for debugging or testing to be sure
+#   that the module works as expected without blocking the connection.
+# By default, the module is in disabled mode.
+# [DEPRECATED] For compatibility reasons, the module is in enforced mode if the
+# file /etc/oar/pam_oar_adopt_enabled exists.
+#MODE=disabled
+
+# Verbosity of the pam_oar_adopt module. Possible values are:
+# - true: the module will print a warning message in disabled mode (default)
+# - false: the module will not print warning messages in disabled mode
+#   false is useful if you want to keep this module in the PAM stack but
+#   without any effect (including warning messages).
+# In enforced mode, this setting has no effect.
+#WARN=true
+
+# USER_UID_MIN is the minimum user id for which the pam_oar_adopt module will
+# enforce the OAR job cgroup assignment and environment variables setting. If
+# the user id is inferior to USER_UID_MIN, the pam_oar_adopt module does
+# nothing. Default value is 1000.
+#USER_UID_MIN=1000