blob: 906d1c151695b84ac6f8f8d036bbb036a00668ee [file] [log] [blame]
<?xml version='1.0'?> <!--*-nxml-*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
<refentry id="pam_systemd_home" conditional='ENABLE_PAM_HOME'>
<refpurpose>Automatically mount home directories managed by <filename>systemd-homed.service</filename> on
login, and unmount them on logout</refpurpose>
<para><command>pam_systemd_home</command> ensures that home directories managed by
are automatically activated (mounted) on user login, and are deactivated (unmounted) when the last
session of the user ends.</para>
<para>The following options are understood:</para>
<variablelist class='pam-directives'>
<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
<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
<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>
<listitem><para>Takes an optional boolean argument. If yes or without the argument, the module will log
debugging information as it operates.</para></listitem>
<title>Module Types Provided</title>
<para>The module provides all four management operations: <option>auth</option>, <option>account</option>,
<option>session</option>, <option>password</option>.</para>
<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'>
<listitem><para>Indicates that the user's home directory is managed by <filename>systemd-homed.service</filename>.</para></listitem>
<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
<para>Here's an example PAM configuration fragment that permits users managed by
<filename>systemd-homed.service</filename> to log in:</para>
auth sufficient
<command>-auth sufficient</command>
auth required
account required
<command>-account sufficient</command>
account sufficient
account required
<command>-password sufficient</command>
password sufficient sha512 shadow try_first_pass use_authtok
password required
-session optional revoke
-session optional
<command>-session optional</command>
-session optional
session required</programlisting>
<title>See Also</title>
<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>