From 78e3988dd377a043c5b6c9a898994be68a8bf6f8 Mon Sep 17 00:00:00 2001
From: Thorsten Kukuk <kukuk@suse.com>
Date: Wed, 27 Mar 2024 11:25:37 +0100
Subject: pam_env: document when the module is executed

Document that pam_env.so is only called by pam_setcred() and
not by pam_authenticate() when added to the auth stack.

Resolves: https://github.com/linux-pam/linux-pam/issues/680
Signed-off-by: Thorsten Kukuk <kukuk@suse.com>
---
 modules/pam_env/pam_env.8.xml | 21 +++++++++++++++++++--
 1 file changed, 19 insertions(+), 2 deletions(-)

(limited to 'modules/pam_env')

diff --git a/modules/pam_env/pam_env.8.xml b/modules/pam_env/pam_env.8.xml
index 3af52ea6..c7889e0f 100644
--- a/modules/pam_env/pam_env.8.xml
+++ b/modules/pam_env/pam_env.8.xml
@@ -114,6 +114,19 @@
       Since setting of PAM environment variables can have side effects
       to other modules, this module should be the last one on the stack.
     </para>
+    <para>
+      This module is only executed if the main application calls
+      <citerefentry>
+        <refentrytitle>pam_setcred</refentrytitle><manvolnum>3</manvolnum>
+      </citerefentry> or
+      <citerefentry>
+        <refentrytitle>pam_open_session</refentrytitle><manvolnum>3</manvolnum>
+      </citerefentry>.
+      The module does nothing and returns <emphasis>PAM_IGNORE</emphasis> if called by
+      <citerefentry>
+        <refentrytitle>pam_authenticate</refentrytitle><manvolnum>3</manvolnum>
+      </citerefentry>.
+    </para>
   </refsect1>
 
   <refsect1 xml:id="pam_env-options">
@@ -244,7 +257,11 @@
         <term>PAM_IGNORE</term>
         <listitem>
            <para>
-             No pam_env.conf and environment file was found.
+             No pam_env.conf and environment file was found or the module got
+	     called by
+	     <citerefentry>
+               <refentrytitle>pam_authenticate</refentrytitle><manvolnum>3</manvolnum>
+	     </citerefentry>.
           </para>
         </listitem>
       </varlistentry>
@@ -309,4 +326,4 @@
       pam_env was written by Dave Kinchlea &lt;kinch@kinch.ark.com&gt;.
     </para>
   </refsect1>
-</refentry>
\ No newline at end of file
+</refentry>
-- 
cgit v1.2.3