man: expand description of lingering and KillUserProcesses setting

The description in the man page was wrong, KillUserProcesses does
not kill all processes of the user. Describe what the setting
does, and also add links between the relavant sections of the
manual.

Also, add an extensive example which shows how to launch screen
in the background.

1 files changed, 32 insertions, 17 deletions

diff --git a/man/logind.conf.xml b/man/logind.conf.xml
index 597759e33a..10a23955a4 100644
--- a/man/logind.conf.xml
+++ b/man/logind.conf.xml
@@ -119,30 +119,45 @@
       <varlistentry>
         <term><varname>KillUserProcesses=</varname></term>
 
-        <listitem><para>Takes a boolean argument. Configures whether
-        the processes of a user should be killed when the user
-        completely logs out (i.e. after the user's last session
-        ended). Defaults to <literal>no</literal>.</para>
-
-        <para>Note that setting <varname>KillUserProcesses=1</varname>
+        <listitem><para>Takes a boolean argument. Configures whether the processes of a
+        user should be killed when the user logs out. If true, the scope unit
+        corresponding to the session and all processes inside that scope will be
+        terminated. If false, the scope is "abandonded", see
+        <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+        and processes are not killed. Defaults to <literal>no</literal>.</para>
+
+        <para>In addition to session processes, user process may run under the user
+        manager unit <filename>user@.service</filename>. Depending on the linger
+        settings, this may allow users to run processes independent of their login
+        sessions. See the description of <command>enable-linger</command> in
+        <citerefentry><refentrytitle>loginctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
+        </para>
+
+        <para>Note that setting <varname>KillUserProcesses=yes</varname>
         will break tools like
-        <citerefentry project='die-net'><refentrytitle>screen</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para></listitem>
+        <citerefentry project='die-net'><refentrytitle>screen</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+        and
+        <citerefentry project='die-net'><refentrytitle>tmux</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+        unless they are moved out of the session scope. See example in
+        <citerefentry><refentrytitle>systemd-run</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
+        </para></listitem>
       </varlistentry>
 
       <varlistentry>
         <term><varname>KillOnlyUsers=</varname></term>
         <term><varname>KillExcludeUsers=</varname></term>
 
-        <listitem><para>These settings take space-separated lists of
-        usernames that influence the effect of
-        <varname>KillUserProcesses=</varname>. If not empty, only
-        processes of users listed in <varname>KillOnlyUsers=</varname>
-        will be killed when they log out entirely. Processes of users
-        listed in <varname>KillExcludeUsers=</varname> are excluded
-        from being killed. <varname>KillExcludeUsers=</varname>
-        defaults to <literal>root</literal> and takes precedence over
-        <varname>KillOnlyUsers=</varname>, which defaults to the empty
-        list.</para></listitem>
+        <listitem><para>These settings take space-separated lists of usernames that
+        determine to which users the <varname>KillUserProcesses=</varname> setting
+        applies. A user name may be added to <varname>KillExcludeUsers=</varname> to
+        exclude the processes in the session scopes of that user from being killed even if
+        <varname>KillUserProcesses=yes</varname> is set. If
+        <varname>KillExcludeUsers=</varname> is not set, the <literal>root</literal> user
+        is excluded by default. <varname>KillExcludeUsers=</varname> may be set to an
+        empty value to override this default. If a user is not excluded,
+        <varname>KillOnlyUsers=</varname> is checked next. A list of user names may be
+        specified in <varname>KillOnlyUsers=</varname>, to only include those
+        users. Otherwise, all users are included.</para></listitem>
       </varlistentry>
 
       <varlistentry>