Merge pull request #15433 from mrc0mmand/test-reintroduce-parallelization

[thirdparty/systemd.git] / man / pam_systemd_home.xml

diff --git a/man/pam_systemd_home.xml b/man/pam_systemd_home.xml
index 6dc1a830b69e67d2db9b67f56429569dd3d9e2c8..ab02f98337202e60dbc21d42e27de819796e3c9b 100644 (file)
--- a/man/pam_systemd_home.xml
+++ b/man/pam_systemd_home.xml
@@ -51,8 +51,34 @@
         coming back from suspend. It is recommended to set this parameter for all PAM applications that have
         support for automatically re-authenticating via PAM on system resume. If multiple sessions of the
         same user are open in parallel the user's home directory will be left unsuspended on system suspend
-        as long as at least one of the sessions does not set this parameter. Defaults to
-        off.</para></listitem>
+        as long as at least one of the sessions does not set this parameter to on. Defaults to
+        off.</para>
+
+        <para>Note that TTY logins generally do not support re-authentication on system resume.
+        Re-authentication on system resume is primarily a concept implementable in graphical environments, in
+        the form of lock screens brought up automatically when the system goes to sleep. This means that if a
+        user concurrently uses graphical login sessions that implement the required re-authentication
+        mechanism and console logins that do not, the home directory is not locked during suspend, due to the
+        logic explained above. That said, it is possible to set this field for TTY logins too, ignoring the
+        fact that TTY logins actually don't support the re-authentication mechanism. In that case the TTY
+        sessions will appear hung until the user logs in on another virtual terminal (regardless if via
+        another TTY session or graphically) which will resume the home directory and unblock the original TTY
+        session. (Do note that lack of screen locking on TTY sessions means even though the TTY session
+        appears hung, keypresses can still be queued into it, and the existing screen contents be read
+        without re-authentication; this limitation is unrelated to the home directory management
+        <command>pam_systemd_home</command> and <filename>systemd-homed.service</filename> implement.)</para>
+
+        <para>Turning this option on by default is highly recommended for all sessions, but only if the
+        service managing these sessions correctly implements the aforementioned re-authentication. Note that
+        the re-authentication must take place from a component running outside of the user's context, so that
+        it does not require access to the user's home directory for operation. Traditionally, most desktop
+        environments do not implement screen locking this way, and need to be updated
+        accordingly.</para>
+
+        <para>This setting may also be controlled via the <varname>$SYSTEMD_HOME_SUSPEND</varname>
+        environment variable (see below), which <command>pam_systemd_home</command> reads during initialization and sets
+        for sessions. If both the environment variable is set and the module parameter specified the latter
+        takes precedence.</para></listitem>
       </varlistentry>
 
       <varlistentry>
@@ -84,6 +110,15 @@
         <listitem><para>Indicates that the user's home directory is managed by <filename>systemd-homed.service</filename>.</para></listitem>
       </varlistentry>
 
+      <varlistentry>
+        <term><varname>$SYSTEMD_HOME_SUSPEND=</varname></term>
+
+        <listitem><para>Indicates whether the session has been registered with the suspend mechanism enabled
+        or disabled (see above). The variable's value is either <literal>0</literal> or
+        <literal>1</literal>. Note that the module both reads the variable when initializing, and sets it for
+        sessions.</para></listitem>
+      </varlistentry>
+
     </variablelist>
   </refsect1>
 
@@ -95,21 +130,21 @@
 
     <programlisting>#%PAM-1.0
 auth      sufficient pam_unix.so
--auth     sufficient pam_systemd_home.so
+<command>-auth     sufficient pam_systemd_home.so</command>
 auth      required   pam_deny.so
 
 account   required   pam_nologin.so
--account  sufficient pam_systemd_home.so
+<command>-account  sufficient pam_systemd_home.so</command>
 account   sufficient pam_unix.so
 account   required   pam_permit.so
 
--password sufficient pam_systemd_home.so
+<command>-password sufficient pam_systemd_home.so</command>
 password  sufficient pam_unix.so sha512 shadow try_first_pass try_authtok
 password  required   pam_deny.so
 
 -session  optional   pam_keyinit.so revoke
 -session  optional   pam_loginuid.so
--session  optional   pam_systemd_home.so
+<command>-session  optional   pam_systemd_home.so</command>
 -session  optional   pam_systemd.so
 session   required   pam_unix.so</programlisting>
   </refsect1>