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.

3 files changed, 111 insertions, 18 deletions

diff --git a/man/loginctl.xml b/man/loginctl.xml
index 7f7252a5d9..fb51740503 100644
--- a/man/loginctl.xml
+++ b/man/loginctl.xml
@@ -312,7 +312,10 @@
         This allows users who are not logged in to run long-running
         services. Takes one or more user names or numeric UIDs as
         argument. If no argument is specified, enables/disables
-        lingering for the user of the session of the caller.
+        lingering for the user of the session of the caller.</para>
+
+        <para>See also <varname>KillUserProcesses=</varname> setting in
+        <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
         </para></listitem>
       </varlistentry>
 
@@ -410,6 +413,37 @@
     otherwise.</para>
   </refsect1>
 
+  <refsect1>
+    <title>Examples</title>
+
+    <example>
+      <title>Querying user status</title>
+
+      <programlisting>$ loginctl user-status
+fatima (1005)
+           Since: Sat 2016-04-09 14:23:31 EDT; 54min ago
+           State: active
+        Sessions: 5 *3
+            Unit: user-1005.slice
+                  ├─user@1005.service
+                    ...
+                  ├─session-3.scope
+                    ...
+                  └─session-5.scope
+                    ├─3473 login -- fatima
+                    └─3515 -zsh
+
+Apr 09 14:40:30 laptop login[2325]: pam_unix(login:session):
+                       session opened for user fatima by LOGIN(uid=0)
+Apr 09 14:40:30 laptop login[2325]: LOGIN ON tty3 BY fatima
+</programlisting>
+
+      <para>There are two sessions, 3 and 5. Session 3 is a graphical session,
+      marked with a star. The tree of processing including the two corresponding
+      scope units and the user manager unit are shown.</para>
+    </example>
+  </refsect1>
+
   <xi:include href="less-variables.xml" />
 
   <refsect1>
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>
diff --git a/man/systemd-run.xml b/man/systemd-run.xml
index 7b7c9305fb..0d58356e00 100644
--- a/man/systemd-run.xml
+++ b/man/systemd-run.xml
@@ -394,6 +394,50 @@ Dec 08 20:44:48 container systemd[1]: Started /bin/touch /tmp/foo.</programlisti
 
       <programlisting># systemd-run -t --send-sighup /bin/bash</programlisting>
     </example>
+
+    <example>
+      <title>Start <command>screen</command> as a user service</title>
+
+      <programlisting>$ systemd-run --scope --user screen
+Running scope as unit run-r14b0047ab6df45bfb45e7786cc839e76.scope.
+
+$ screen -ls
+There is a screen on:
+        492..laptop     (Detached)
+1 Socket in /var/run/screen/S-fatima.
+</programlisting>
+
+      <para>This starts the <command>screen</command> process as a child of the
+      <command>systemd --user</command> process that was started by
+      <filename>user@.service</filename>, in a scope unit. A
+      <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+      unit is used instead of a
+      <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+      unit, because <command>screen</command> will exit when detaching from the terminal,
+      and a service unit would be terminated. Running <command>screen</command>
+      as a user unit has the advantage that it is not part of the session scope.
+      If <varname>KillUserProcesses=yes</varname> is configured in
+      <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+      the default, the session scope will be terminated when the user logs
+      out of that session.</para>
+
+      <para>The <filename>user@.service</filename> is started automatically
+      when the user first logs in, and stays around as long as at least one
+      login session is open. After the user logs out of the last session,
+      <filename>user@.service</filename> and all services underneath it
+      are terminated. This behaviour is the default, when "lingering" is
+      not enabled for that user. Enabling lingering means that
+      <filename>user@.service</filename> is started automatically during
+      boot, even if the user is not logged in, and that the service is
+      not terminated when the user logs out.</para>
+
+      <para>Enabling lingering allows the user to run processes without being logged in,
+      for example to allow <command>screen</command> to persist after the user logs out,
+      even if the session scope is terminated. In the default configuration, users can
+      enable lingering for themselves:</para>
+
+      <programlisting>$ loginctl enable-linger</programlisting>
+    </example>
   </refsect1>
 
   <refsect1>