man: update pam_systemd page to document new behaviour

2 files changed, 56 insertions, 112 deletions

diff --git a/man/pam_systemd.xml b/man/pam_systemd.xml
index 7d5fcad631..883b50b640 100644
--- a/man/pam_systemd.xml
+++ b/man/pam_systemd.xml
@@ -69,8 +69,7 @@
                         created and its ownership changed to the user
                         that is logging in.</para></listitem>
 
-                        <listitem><para>If
-                        <option>create-session=1</option> is set, the
+                        <listitem><para>The
                         <varname>$XDG_SESSION_ID</varname> environment
                         variable is initialized. If auditing is
                         available and
@@ -82,20 +81,10 @@
                         an independent session counter is
                         used.</para></listitem>
 
-                        <listitem><para>If
-                        <option>create-session=1</option> is set, a new
-                        control group
+                        <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>If
-                        <option>create-session=0</option> is set, a new
-                        control group
-                        <filename>/user/$USER/user</filename>
-                        is created and the login process moved into
-                        it.</para></listitem>
-
                 </orderedlist>
 
                 <para>On logout, this module ensures the following:</para>
@@ -103,38 +92,13 @@
                 <orderedlist>
                         <listitem><para>If
                         <varname>$XDG_SESSION_ID</varname> is set and
-                        <option>kill-session=1</option> specified, all
+                        <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
-                        <varname>$XDG_SESSION_ID</varname> is set and
-                        <option>kill-session=0</option> specified, all
-                        remaining processes in the
-                        <filename>/user/$USER/$XDG_SESSION_ID</filename>
-                        control group are migrated to
-                        <filename>/user/$USER/user</filename> and
-                        the original control group is
-                        removed.</para></listitem>
-
-                        <listitem><para>If
-                        <option>kill-user=1</option> is specified, and
-                        no other user session control group remains,
-                        except
-                        <filename>/user/$USER/user</filename>,
-                        all remaining processes in the
-                        <filename>/user/$USER</filename> hierarchy
-                        are killed and the control group is removed.</para></listitem>
-
-                        <listitem><para>If
-                        <option>kill-user=0</option> is specified, and
-                        no process remains in the
-                        <filename>/user/$USER</filename> hierarchy the
-                        control group is removed.</para></listitem>
-
-                        <listitem><para>If the
+                        <listitem><para>If last subgroup of the
                         <filename>/user/$USER</filename> control group
                         was removed the
                         <varname>$XDG_RUNTIME_DIR</varname> directory
@@ -155,27 +119,7 @@
 
                 <variablelist>
                         <varlistentry>
-                                <term><option>create-session=</option></term>
-
-                                <listitem><para>Takes a boolean
-                                argument. If true, a new session is
-                                created: the
-                                <varname>$XDG_SESSION_ID</varname>
-                                environment variable is set and the
-                                login process moved to the
-                                <filename>/user/$USER/$XDG_SESSION_ID</filename>
-                                control group. It is recommended that
-                                all services which are directly created
-                                on the user's behalf set this
-                                option. Only for services that shall
-                                automatically be terminated when the
-                                user logs out completely, otherwise
-                                <varname>create-session=0</varname>
-                                should be set.</para></listitem>
-                        </varlistentry>
-
-                        <varlistentry>
-                                <term><option>kill-session=</option></term>
+                                <term><option>kill-session-processes=</option></term>
 
                                 <listitem><para>Takes a boolean
                                 argument. If true, all processes
@@ -186,30 +130,13 @@
                         </varlistentry>
 
                         <varlistentry>
-                                <term><option>kill-user=</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 after he logged out
-                                completely. This is a weaker version
-                                of <option>kill-session=1</option> and is
-                                more friendly for users logged in more
-                                than once, as their processes are
-                                terminated only on their complete
-                                logout.</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=</option> and
-                                <option>kill-user=</option> options
+                                <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
@@ -228,8 +155,7 @@
                                 numeric user ids as argument. Users
                                 listed in this argument will not be
                                 subject to the effect of
-                                <option>kill-session=</option> or
-                                <option>kill-user=</option>.  Note
+                                <option>kill-session-processes=</option>.  Note
                                 that that this option takes precedence
                                 over
                                 <option>kill-only-users=</option>, and
@@ -245,56 +171,59 @@
                                 <term><option>controllers=</option></term>
 
                                 <listitem><para>Takes a comma
-                                separated list of cgroup controllers
-                                in which hierarchies a user/session
-                                cgroup will be created by default for
-                                each user logging in, in addition to
-                                the cgroup in the named 'name=systemd'
+                                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. This may be used to move
-                                user sessions into their own groups in
-                                the 'cpu' hierarchy which ensures that
-                                every logged in user gets an equal
-                                amount of CPU time regardless how many
-                                processes he has
-                                started.</para></listitem>
+                                empty list.</para></listitem>
                         </varlistentry>
 
                         <varlistentry>
                                 <term><option>reset-controllers=</option></term>
 
                                 <listitem><para>Takes a comma
-                                separated list of cgroup controllers
-                                in which hierarchies the logged in
-                                processes will be reset to the root
-                                cgroup. If omitted, defaults to 'cpu',
-                                meaning that a 'cpu' cgroup grouping
-                                inherited from the login manager will
-                                be reset for the processes of the
-                                logged in user.</para></listitem>
+                                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 true, logs debugging
-                                information.</para></listitem>
+                                argument. If yes, the module will log
+                                debugging information as it
+                                operates.</para></listitem>
                         </varlistentry>
                 </variablelist>
 
-                <para>Note that setting <varname>kill-user=1</varname>
-                or even <varname>kill-session=1</varname> will break
-                tools like
+                <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>systemd-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>create-session=1</option>,
-                <option>kill-session=0</option>,
-                <option>kill-user=0</option>,
-                <option>reset-controllers=cpu</option>,
+                <option>kill-session-processes=0</option>,
                 <option>kill-only-users=</option>,
-                <option>kill-exclude-users=root</option>.</para>
+                <option>kill-exclude-users=</option>,
+                <option>controllers=</option>,
+                <option>reset-controllers=</option>,
+                <option>debug=no</option>.</para>
         </refsect1>
 
         <refsect1>
@@ -369,7 +298,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-user=1</programlisting>
+session    required     pam_systemd.so kill-session-processes=1</programlisting>
         </refsect1>
 
         <refsect1>
@@ -379,6 +308,7 @@ session    required     pam_systemd.so kill-user=1</programlisting>
                         <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>systemd-logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
                 </para>
         </refsect1>
diff --git a/man/systemd-logind.conf.xml b/man/systemd-logind.conf.xml
index 889bd1567e..2dc9994954 100644
--- a/man/systemd-logind.conf.xml
+++ b/man/systemd-logind.conf.xml
@@ -147,6 +147,20 @@
                                 <literal>cpu</literal>.</para></listitem>
                         </varlistentry>
                 </variablelist>
+
+                <para>Note that setting
+                <varname>KillUserProcesses=1</varname> will break tools
+                like
+                <citerefentry><refentrytitle>screen</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
+
+                <para>Note that <varname>KillUserProcesses=1</varname>
+                is a weaker version of
+                <varname>kill-session-processes=1</varname> which may
+                be configured per-service for
+                <citerefentry><refentrytitle>pam_systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry>. The
+                latter kills processes of a session as soon as it
+                ends, the former kills processes as soon as the last
+                session of the user ends.</para>
         </refsect1>
 
         <refsect1>