picnoir/Systemd
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

man: expand description of lingering and KillUserProcesses setting

Browse source 
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.
This commit is contained in:
Zbigniew Jędrzejewski-Szmek 2016-04-09 16:22:08 -04:00
parent 4eac7f5ccc
commit 65eb37f8fc
3 changed files with 110 additions and 17 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

36
man/loginctl.xml
View file

@ -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>

47
man/logind.conf.xml
View file

@ -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>
<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>Note that setting <varname>KillUserProcesses=1</varname>
<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>

44
man/systemd-run.xml
View file

@ -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>