summaryrefslogtreecommitdiff
path: root/man/pam_systemd.xml
diff options
context:
space:
mode:
Diffstat (limited to 'man/pam_systemd.xml')
-rw-r--r--man/pam_systemd.xml316
1 files changed, 316 insertions, 0 deletions
diff --git a/man/pam_systemd.xml b/man/pam_systemd.xml
new file mode 100644
index 000000000..c07b46bab
--- /dev/null
+++ b/man/pam_systemd.xml
@@ -0,0 +1,316 @@
+<?xml version='1.0'?> <!--*-nxml-*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<!--
+ This file is part of systemd.
+
+ Copyright 2010 Lennart Poettering
+
+ systemd is free software; you can redistribute it and/or modify it
+ under the terms of the GNU General Public License as published by
+ the Free Software Foundation; either version 2 of the License, or
+ (at your option) any later version.
+
+ systemd is distributed in the hope that it will be useful, but
+ WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ General Public License for more details.
+
+ You should have received a copy of the GNU General Public License
+ along with systemd; If not, see <http://www.gnu.org/licenses/>.
+-->
+
+<refentry id="pam_systemd">
+
+ <refentryinfo>
+ <title>pam_systemd</title>
+ <productname>systemd</productname>
+
+ <authorgroup>
+ <author>
+ <contrib>Developer</contrib>
+ <firstname>Lennart</firstname>
+ <surname>Poettering</surname>
+ <email>lennart@poettering.net</email>
+ </author>
+ </authorgroup>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>pam_systemd</refentrytitle>
+ <manvolnum>8</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>pam_systemd</refname>
+ <refpurpose>Register user sessions in the systemd control group hierarchy</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>pam_systemd.so</command>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+
+ <para><command>pam_systemd</command> registers user
+ sessions in the systemd control group
+ hierarchy.</para>
+
+ <para>On login, this module ensures the following:</para>
+
+ <orderedlist>
+ <listitem><para>If it does not exist yet, the
+ user runtime directory
+ <filename>/run/user/$USER</filename> is
+ created and its ownership changed to the user
+ that is logging in.</para></listitem>
+
+ <listitem><para>The
+ <varname>$XDG_SESSION_ID</varname> environment
+ variable is initialized. If auditing is
+ available and
+ <command>pam_loginuid.so</command> run before
+ this module (which is highly recommended), the
+ variable is initialized from the auditing
+ session id
+ (<filename>/proc/self/sessionid</filename>). Otherwise
+ an independent session counter is
+ used.</para></listitem>
+
+ <listitem><para>A new control group
+ <filename>/user/$USER/$XDG_SESSION_ID</filename>
+ is created and the login process moved into
+ it.</para></listitem>
+ </orderedlist>
+
+ <para>On logout, this module ensures the following:</para>
+
+ <orderedlist>
+ <listitem><para>If
+ <varname>$XDG_SESSION_ID</varname> is set and
+ <option>kill-session-processes=1</option> specified, all
+ remaining processes in the
+ <filename>/user/$USER/$XDG_SESSION_ID</filename>
+ control group are killed and the control group
+ is removed.</para></listitem>
+
+ <listitem><para>If last subgroup of the
+ <filename>/user/$USER</filename> control group
+ was removed the
+ <varname>$XDG_RUNTIME_DIR</varname> directory
+ and all its contents are
+ removed, too.</para></listitem>
+ </orderedlist>
+
+ <para>If the system was not booted up with systemd as
+ init system, this module does nothing and immediately
+ returns PAM_SUCCESS.</para>
+
+ </refsect1>
+
+ <refsect1>
+ <title>Options</title>
+
+ <para>The following options are understood:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><option>kill-session-processes=</option></term>
+
+ <listitem><para>Takes a boolean
+ argument. If true, all processes
+ created by the user during his session
+ and from his session will be
+ terminated when he logs out from his
+ session.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>kill-only-users=</option></term>
+
+ <listitem><para>Takes a comma
+ separated list of user names or
+ numeric user ids as argument. If this
+ option is used the effect of the
+ <option>kill-session-processes=</option> options
+ will apply only to the listed
+ users. If this option is not used the
+ option applies to all local
+ users. Note that
+ <option>kill-exclude-users=</option>
+ takes precedence over this list and is
+ hence subtracted from the list
+ specified here.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>kill-exclude-users=</option></term>
+
+ <listitem><para>Takes a comma
+ separated list of user names or
+ numeric user ids as argument. Users
+ listed in this argument will not be
+ subject to the effect of
+ <option>kill-session-processes=</option>. Note
+ that that this option takes precedence
+ over
+ <option>kill-only-users=</option>, and
+ hence whatever is listed for
+ <option>kill-exclude-users=</option>
+ is guaranteed to never be killed by
+ this PAM module, independent of any
+ other configuration
+ setting.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>controllers=</option></term>
+
+ <listitem><para>Takes a comma
+ separated list of control group
+ controllers in which hierarchies a
+ user/session control group will be
+ created by default for each user
+ logging in, in addition to the control
+ group in the named 'name=systemd'
+ hierarchy. If omitted, defaults to an
+ empty list.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>reset-controllers=</option></term>
+
+ <listitem><para>Takes a comma
+ separated list of control group
+ controllers in which hierarchies the
+ logged in processes will be reset to
+ the root control
+ group.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>debug=</option></term>
+
+ <listitem><para>Takes a boolean
+ argument. If yes, the module will log
+ debugging information as it
+ operates.</para></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>Note that setting
+ <varname>kill-session-processes=1</varname> will break tools
+ like
+ <citerefentry><refentrytitle>screen</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
+
+ <para>Note that
+ <varname>kill-session-processes=1</varname> is a
+ stricter version of
+ <varname>KillUserProcesses=1</varname> which may be
+ configured system-wide in
+ <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>. The
+ former kills processes of a session as soon as it
+ ends, the latter kills processes as soon as the last
+ session of the user ends.</para>
+
+ <para>If the options are omitted they default to
+ <option>kill-session-processes=0</option>,
+ <option>kill-only-users=</option>,
+ <option>kill-exclude-users=</option>,
+ <option>controllers=</option>,
+ <option>reset-controllers=</option>,
+ <option>debug=no</option>.</para>
+ </refsect1>
+
+ <refsect1>
+ <title>Module Types Provided</title>
+
+ <para>Only <option>session</option> is provided.</para>
+ </refsect1>
+
+ <refsect1>
+ <title>Environment</title>
+
+ <para>The following environment variables are set for the processes of the user's session:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>$XDG_SESSION_ID</varname></term>
+
+ <listitem><para>A session identifier,
+ suitable to be used in file names. The
+ string itself should be considered
+ opaque, although often it is just the
+ audit session ID as reported by
+ <filename>/proc/self/sessionid</filename>. Each
+ ID will be assigned only once during
+ machine uptime. It may hence be used
+ to uniquely label files or other
+ resources of this
+ session.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>$XDG_RUNTIME_DIR</varname></term>
+
+ <listitem><para>Path to a user-private
+ user-writable directory that is bound
+ to the user login time on the
+ machine. It is automatically created
+ the first time a user logs in and
+ removed on his final logout. If a user
+ logs in twice at the same time, both
+ sessions will see the same
+ <varname>$XDG_RUNTIME_DIR</varname>
+ and the same contents. If a user logs
+ in once, then logs out again, and logs
+ in again, the directory contents will
+ have been lost in between, but
+ applications should not rely on this
+ behaviour and must be able to deal with
+ stale files. To store session-private
+ data in this directory the user should
+ include the value of <varname>$XDG_SESSION_ID</varname>
+ in the filename. This directory shall
+ be used for runtime file system
+ objects such as AF_UNIX sockets,
+ FIFOs, PID files and similar. It is
+ guaranteed that this directory is
+ local and offers the greatest possible
+ file system feature set the
+ operating system
+ provides.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+
+ <refsect1>
+ <title>Example</title>
+
+ <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 kill-session-processes=1</programlisting>
+ </refsect1>
+
+ <refsect1>
+ <title>See Also</title>
+ <para>
+ <citerefentry><refentrytitle>pam.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>pam.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>pam_loginuid</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ </para>
+ </refsect1>
+
+</refentry>
generated by cgit v1.2.3 (git 2.25.1) at 2024-04-25 07:56:46 +0000