man: update pam_systemd documentation to current state of the code

2 files changed, 26 insertions, 116 deletions

diff --git a/TODO b/TODO
index ffd845b38e..a4535b5d9f 100644
--- a/TODO
+++ b/TODO
@@ -46,7 +46,7 @@ CGroup Rework Completion:
 * introduce high-level settings for RT budget, swappiness
 
 * wiki: document new bus APIs of PID 1 (transient units, Reloading signal)
-* review: scope units, slice units, pam_system, systemctl commands
+* review: scope units, slice units, systemctl commands
 
 * Send SIGHUP and SIGTERM in session scopes
 
diff --git a/man/pam_systemd.xml b/man/pam_systemd.xml
index 4e5cdf248b..1d924bc319 100644
--- a/man/pam_systemd.xml
+++ b/man/pam_systemd.xml
@@ -80,29 +80,32 @@
                         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>
+                        <listitem><para>A new systemd scope unit is
+                        created for the session. If this is the first
+                        concurrent session of the user an implicit
+                        slice below <filename>user.slice</filename> is
+                        automatically created and the scope placed in
+                        it. In instance of the system service
+                        <filename>user@.service</filename> which runt
+                        the systemd user manager
+                        instance.</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 the last subgroup of the
-                        <filename>/user/$USER</filename> control group
-                        was removed the
+                        <listitem><para>If this is enabled all
+                        processes of the session are terminated. If
+                        the last concurrent session of a user ends his
+                        user systemd instance will be terminated too,
+                        and so will the user's slice
+                        unit.</para></listitem>
+
+                        <listitem><para>If the las concurrent session
+                        of a user ends the
                         <varname>$XDG_RUNTIME_DIR</varname> directory
-                        and all its contents are
-                        removed, too.</para></listitem>
+                        and all its contents are removed,
+                        too.</para></listitem>
                 </orderedlist>
 
                 <para>If the system was not booted up with systemd as
@@ -117,79 +120,6 @@
                 <para>The following options are understood:</para>
 
                 <variablelist class='pam-directives'>
-                        <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 usernames 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 usernames 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 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>class=</option></term>
@@ -209,29 +139,6 @@
                                 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>
@@ -306,7 +213,7 @@ 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>
+session    required     pam_systemd.so</programlisting>
         </refsect1>
 
         <refsect1>
@@ -319,7 +226,10 @@ session    required     pam_systemd.so kill-session-processes=1</programlisting>
                         <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>pam_loginuid</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+                        <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+                        <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+                        <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
                 </para>
         </refsect1>