<?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+ -->
+<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
-<refentry id="pam_systemd" conditional='HAVE_PAM'>
+<refentry id="pam_systemd" conditional='HAVE_PAM' xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>pam_systemd</title>
<citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
and hence the systemd control group hierarchy.</para>
+ <para>The module also applies various resource management and runtime parameters to the new session, as
+ configured in the <ulink url="https://systemd.io/USER_RECORD">JSON User Records</ulink> of the user, when
+ one is defined.</para>
+
<para>On login, this module — in conjunction with <filename>systemd-logind.service</filename> — ensures the
following:</para>
<listitem><para>A new systemd scope unit is created for the session. If this is the first concurrent session of
the user, an implicit per-user slice unit below <filename>user.slice</filename> is automatically created and the
scope placed into it. An instance of the system service <filename>user@.service</filename>, which runs the
- systemd user manager instance, is started. </para></listitem>
+ systemd user manager instance, is started.</para></listitem>
+
+ <listitem><para>The <literal>$TZ</literal>, <literal>$EMAIL</literal> and <literal>$LANG</literal>
+ environment variables are configured for the user, based on the respective data from the user's JSON
+ record (if it is defined). Moreover, any environment variables explicitly configured in the user record
+ are imported, and the umask, nice level, and resource limits initialized.</para></listitem>
</orderedlist>
<para>On logout, this module ensures the following:</para>
indicate the session desktop used, where this applies and if this information is available. For example:
<literal>GNOME</literal>, or <literal>KDE</literal>. It is recommended to use the same identifiers and
capitalization as for <varname>$XDG_CURRENT_DESKTOP</varname>, as defined by the <ulink
- url="http://standards.freedesktop.org/desktop-entry-spec/latest/">Desktop Entry
+ url="https://standards.freedesktop.org/desktop-entry-spec/latest/">Desktop Entry
Specification</ulink>. (However, note that the option only takes a single item, and not a colon-separated list
like <varname>$XDG_CURRENT_DESKTOP</varname>.) See
<citerefentry><refentrytitle>sd_session_get_desktop</refentrytitle><manvolnum>3</manvolnum></citerefentry> for
further details.</para></listitem>
</varlistentry>
+ <varlistentry>
+ <term><varname>default-capability-bounding-set=</varname></term>
+ <term><varname>default-capability-ambient-set=</varname></term>
+
+ <listitem><para>Takes a comma-separated list of process capabilities
+ (e.g. <constant>CAP_WAKE_ALARM</constant>, <constant>CAP_BLOCK_SUSPEND</constant>, …) to set for the
+ invoked session's processes, if the user record does not encode appropriate sets of capabilities
+ directly. See <citerefentry
+ project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+ for details on the capabilities concept. If not specified, the default bounding set is left as is
+ (i.e. usually contains the full set of capabilities). The default ambient set is set to
+ <constant>CAP_WAKE_ALARM</constant> for regular users if the PAM session is associated with a local
+ seat or if it is invoked for the <literal>systemd-user</literal> service. Otherwise defaults to the
+ empty set.</para></listitem>
+ </varlistentry>
+
<varlistentry>
<term><varname>debug</varname><optional>=</optional></term>
hence be used to uniquely label files or other resources of this session. Combine this ID with the boot
identifier, as returned by
<citerefentry><refentrytitle>sd_id128_get_boot</refentrytitle><manvolnum>3</manvolnum></citerefentry>, for a
- globally unique identifier for the current session.</para></listitem>
+ globally unique identifier.</para></listitem>
</varlistentry>
<varlistentry>
similar. It is guaranteed that this directory is local and
offers the greatest possible file system feature set the
operating system provides. For further details, see the <ulink
- url="http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html">XDG
+ url="https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html">XDG
Base Directory Specification</ulink>. <varname>$XDG_RUNTIME_DIR</varname>
is not set if the current user is not the original user of the session.</para></listitem>
</varlistentry>
+ <varlistentry>
+ <term><varname>$TZ</varname></term>
+ <term><varname>$EMAIL</varname></term>
+ <term><varname>$LANG</varname></term>
+
+ <listitem><para>If a JSON user record is known for the user logging in these variables are
+ initialized from the respective data in the record.</para></listitem>
+ </varlistentry>
+
</variablelist>
<para>The following environment variables are read by the module and may be used by the PAM service to pass
<varlistentry>
<term><varname>$XDG_SESSION_TYPE</varname></term>
- <listitem><para>The session type. This may be used instead of <varname>session=</varname> on the module parameter
+ <listitem><para>The session type. This may be used instead of <varname>type=</varname> on the module parameter
line, and is usually preferred.</para></listitem>
</varlistentry>
<title>Session limits</title>
<para>PAM modules earlier in the stack, that is those that come before <command>pam_systemd.so</command>,
- can set session scope limits using the PAM context objects. The data for these objects is provided as NUL-terminated C strings
+ can set session scope limits using the PAM context objects. The data for these objects is provided as <constant>NUL</constant>-terminated C strings
and maps directly to the respective unit resource control directives. Note that these limits apply to individual sessions of the user,
they do not apply to all user processes as a combined whole. In particular, the per-user <command>user@.service</command> unit instance,
which runs the <command>systemd --user</command> manager process and its children, and is tracked outside of any session, being shared
<para> See
<citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry> for more information about the resources.
- Also, see <citerefentry><refentrytitle>pam_set_data</refentrytitle><manvolnum>3</manvolnum></citerefentry> for additional information about how to set
+ Also, see <citerefentry project='man-pages'><refentrytitle>pam_set_data</refentrytitle><manvolnum>3</manvolnum></citerefentry> for additional information about how to set
the context objects.
</para>
<variablelist class='pam-directives'>
<varlistentry>
- <term><varname>systemd.memory_max</varname></term>
+ <term><varname>systemd.memory_max=</varname></term>
<listitem><para>Sets unit <varname>MemoryMax=</varname>.</para></listitem>
</varlistentry>
<varlistentry>
- <term><varname>systemd.tasks_max</varname></term>
+ <term><varname>systemd.tasks_max=</varname></term>
<listitem><para>Sets unit <varname>TasksMax=</varname>.</para></listitem>
</varlistentry>
<varlistentry>
- <term><varname>systemd.cpu_weight</varname></term>
+ <term><varname>systemd.cpu_weight=</varname></term>
<listitem><para>Sets unit <varname>CPUWeight=</varname>.</para></listitem>
</varlistentry>
<varlistentry>
- <term><varname>systemd.io_weight</varname></term>
+ <term><varname>systemd.io_weight=</varname></term>
<listitem><para>Sets unit <varname>IOWeight=</varname>.</para></listitem>
</varlistentry>
<varlistentry>
- <term><varname>systemd.runtime_max_sec</varname></term>
+ <term><varname>systemd.runtime_max_sec=</varname></term>
<listitem><para>Sets unit <varname>RuntimeMaxSec=</varname>.</para></listitem>
</varlistentry>
<refsect1>
<title>Example</title>
+ <para>Here's an example PAM configuration fragment that allows users sessions to be managed by
+ <filename>systemd-logind.service</filename>:</para>
+
<programlisting>#%PAM-1.0
-auth required pam_unix.so
-auth required pam_nologin.so
-account required pam_unix.so
-password required pam_unix.so
-session required pam_unix.so
-session required pam_loginuid.so
-session required pam_systemd.so</programlisting>
+auth sufficient pam_unix.so
+-auth sufficient pam_systemd_home.so
+auth required pam_deny.so
+
+account required pam_nologin.so
+-account sufficient pam_systemd_home.so
+account sufficient pam_unix.so
+account required pam_permit.so
+
+-password sufficient pam_systemd_home.so
+password sufficient pam_unix.so sha512 shadow try_first_pass use_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.so</command>
+session required pam_unix.so</programlisting>
</refsect1>
<refsect1>
<citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
<citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<citerefentry><refentrytitle>loginctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>pam_systemd_home</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>,