Adding upstream version 252.22.upstream/252.22

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 175 insertions, 0 deletions

diff --git a/man/pam_systemd_home.xml b/man/pam_systemd_home.xml
new file mode 100644
index 0000000..ff4735c
--- /dev/null
+++ b/man/pam_systemd_home.xml
@@ -0,0 +1,175 @@
+<?xml version='1.0'?> <!--*-nxml-*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
+
+<refentry id="pam_systemd_home" conditional='ENABLE_PAM_HOME'>
+
+  <refentryinfo>
+    <title>pam_systemd_home</title>
+    <productname>systemd</productname>
+  </refentryinfo>
+
+  <refmeta>
+    <refentrytitle>pam_systemd_home</refentrytitle>
+    <manvolnum>8</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname>pam_systemd_home</refname>
+    <refpurpose>Authenticate users and mount home directories via <filename>systemd-homed.service</filename>
+    </refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <para><filename>pam_systemd_home.so</filename></para>
+  </refsynopsisdiv>
+
+  <refsect1>
+    <title>Description</title>
+
+    <para><command>pam_systemd_home</command> ensures that home directories managed by
+    <citerefentry><refentrytitle>systemd-homed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+    are automatically activated (mounted) on user login, and are deactivated (unmounted) when the last
+    session of the user ends. For such users, it also provides authentication (when per-user disk encryption
+    is used, the disk encryption key is derived from the authentication credential supplied at login time),
+    account management (the <ulink url="https://systemd.io/USER_RECORD/">JSON user record</ulink> embedded in
+    the home store contains account details), and implements the updating of the encryption password (which
+    is also used for user authentication).</para>
+  </refsect1>
+
+  <refsect1>
+    <title>Options</title>
+
+    <para>The following options are understood:</para>
+
+    <variablelist class='pam-directives'>
+
+      <varlistentry>
+        <term><varname>suspend=</varname></term>
+
+        <listitem><para>Takes a boolean argument. If true, the home directory of the user will be suspended
+        automatically during system suspend; if false it will remain active. Automatic suspending of the home
+        directory improves security substantially as secret key material is automatically removed from memory
+        before the system is put to sleep and must be re-acquired (through user re-authentication) when
+        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 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>
+        <term><varname>debug</varname><optional>=</optional></term>
+
+        <listitem><para>Takes an optional boolean argument. If yes or without the argument, the module will log
+        debugging information as it operates.</para></listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+
+  <refsect1>
+    <title>Module Types Provided</title>
+
+    <para>The module implements all four PAM operations: <option>auth</option> (reason: to allow
+    authentication using the encrypted data), <option>account</option> (reason: users with
+    <filename>systemd-homed.service</filename> user accounts are described in a <ulink
+    url="https://systemd.io/USER_RECORD/">JSON user record</ulink> and may be configured in more detail than
+    in the traditional Linux user database), <option>session</option> (user sessions must be tracked in order
+    to implement automatic release when the last session of the user is gone), <option>password</option> (to
+    change the encryption password — also used for user authentication — through PAM).</para>
+  </refsect1>
+
+  <refsect1>
+    <title>Environment</title>
+
+    <para>The following environment variables are initialized by the module and available to the processes of the
+    user's session:</para>
+
+    <variablelist class='environment-variables'>
+      <varlistentry>
+        <term><varname>$SYSTEMD_HOME=1</varname></term>
+
+        <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>
+
+  <refsect1>
+    <title>Example</title>
+
+    <para>Here's an example PAM configuration fragment that permits users managed by
+    <filename>systemd-homed.service</filename> to log in:</para>
+
+    <programlisting>#%PAM-1.0
+auth      sufficient pam_unix.so
+<command>-auth     sufficient pam_systemd_home.so</command>
+auth      required   pam_deny.so
+
+account   required   pam_nologin.so
+<command>-account  sufficient pam_systemd_home.so</command>
+account   sufficient pam_unix.so
+account   required   pam_permit.so
+
+<command>-password sufficient pam_systemd_home.so</command>
+password  sufficient pam_unix.so sha512 shadow try_first_pass
+password  required   pam_deny.so
+
+-session  optional   pam_keyinit.so revoke
+-session  optional   pam_loginuid.so
+<command>-session  optional   pam_systemd_home.so</command>
+-session  optional   pam_systemd.so
+session   required   pam_unix.so</programlisting>
+  </refsect1>
+
+  <refsect1>
+    <title>See Also</title>
+    <para>
+      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>systemd-homed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>homed.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>homectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>pam_systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+      <citerefentry project='man-pages'><refentrytitle>pam.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+      <citerefentry project='man-pages'><refentrytitle>pam.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+      <citerefentry project='man-pages'><refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+    </para>
+  </refsect1>
+
+</refentry>