Merge pull request #3005 from keszybz/kill-user-proceses

Kill user session scope by default

3 files changed, 142 insertions, 37 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..3217ece21a 100644
--- a/man/logind.conf.xml
+++ b/man/logind.conf.xml
@@ -119,30 +119,46 @@
       <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>yes</literal>,
+        but see the options <varname>KillOnlyUsers=</varname> and
+        <varname>KillExcludeUsers=</varname> below.</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 override
+        the <varname>KillUserProcesses=</varname> setting. 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. If this setting is specified, only the session scopes of those users
+        will be killed. Otherwise, users are subject to the
+        <varname>KillUserProcesses=yes</varname> setting.</para></listitem>
       </varlistentry>
 
       <varlistentry>
diff --git a/man/systemd-run.xml b/man/systemd-run.xml
index 245daae946..9c1a29218e 100644
--- a/man/systemd-run.xml
+++ b/man/systemd-run.xml
@@ -341,10 +341,10 @@
   <refsect1>
     <title>Examples</title>
 
-    <para>The following command will log the environment variables
-    provided by systemd to services:</para>
+    <example>
+      <title>Logging environment variables provided by systemd to services</title>
 
-    <programlisting># systemd-run env
+      <programlisting># systemd-run env
 Running as unit: run-19945.service
 # journalctl -u run-19945.service
 Sep 08 07:37:21 bupkis systemd[1]: Starting /usr/bin/env...
@@ -352,19 +352,27 @@ Sep 08 07:37:21 bupkis systemd[1]: Started /usr/bin/env.
 Sep 08 07:37:21 bupkis env[19948]: PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin
 Sep 08 07:37:21 bupkis env[19948]: LANG=en_US.UTF-8
 Sep 08 07:37:21 bupkis env[19948]: BOOT_IMAGE=/vmlinuz-3.11.0-0.rc5.git6.2.fc20.x86_64</programlisting>
+    </example>
 
-    <para>The following command invokes the
-    <citerefentry project='man-pages'><refentrytitle>updatedb</refentrytitle><manvolnum>8</manvolnum></citerefentry>
-    tool, but lowers the block I/O weight for it to 10. See
-    <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>
-    for more information on the <varname>BlockIOWeight=</varname>
-    property.</para>
+    <example>
+      <title>Limiting resources available to a command</title>
 
-    <programlisting># systemd-run -p BlockIOWeight=10 updatedb</programlisting>
+      <programlisting># systemd-run -p BlockIOWeight=10 updatedb</programlisting>
 
-    <para>The following command will touch a file after 30 seconds.</para>
+      <para>This command invokes the
+      <citerefentry project='man-pages'><refentrytitle>updatedb</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+      tool, but lowers the block I/O weight for it to 10. See
+      <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+      for more information on the <varname>BlockIOWeight=</varname>
+      property.</para>
+    </example>
 
-    <programlisting># date; systemd-run --on-active=30 --timer-property=AccuracySec=100ms /bin/touch /tmp/foo
+    <example>
+      <title>Running commands at a specified time</title>
+
+      <para>The following command will touch a file after 30 seconds.</para>
+
+      <programlisting># date; systemd-run --on-active=30 --timer-property=AccuracySec=100ms /bin/touch /tmp/foo
 Mon Dec  8 20:44:24 KST 2014
 Running as unit: run-71.timer
 Will run service as unit: run-71.service
@@ -376,13 +384,60 @@ Dec 08 20:44:38 container systemd[1]: Started /bin/touch /tmp/foo.
 -- Logs begin at Fri 2014-12-05 19:09:21 KST, end at Mon 2014-12-08 20:44:54 KST. --
 Dec 08 20:44:48 container systemd[1]: Starting /bin/touch /tmp/foo...
 Dec 08 20:44:48 container systemd[1]: Started /bin/touch /tmp/foo.</programlisting>
-
-    <para>The following command invokes <filename>/bin/bash</filename>
-    as a service passing its standard input, output and error to
-    the calling TTY.</para>
-
-    <programlisting># systemd-run -t --send-sighup /bin/bash</programlisting>
-
+    </example>
+
+    <example>
+      <title>Allowing access to the tty</title>
+
+      <para>The following command invokes <filename>/bin/bash</filename> as a service
+      passing its standard input, output and error to the calling TTY.</para>
+
+      <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>