diff options
Diffstat (limited to 'man')
| -rw-r--r-- | man/daemon.xml | 2 | ||||
| -rw-r--r-- | man/loginctl.xml | 36 | ||||
| -rw-r--r-- | man/logind.conf.xml | 50 | ||||
| -rw-r--r-- | man/sd_event_source_set_priority.xml | 2 | ||||
| -rw-r--r-- | man/sd_journal_add_match.xml | 18 | ||||
| -rw-r--r-- | man/sd_journal_get_data.xml | 2 | ||||
| -rw-r--r-- | man/systemd-ask-password.xml | 2 | ||||
| -rw-r--r-- | man/systemd-journal-gatewayd.service.xml | 2 | ||||
| -rw-r--r-- | man/systemd-nspawn.xml | 2 | ||||
| -rw-r--r-- | man/systemd-run.xml | 93 | ||||
| -rw-r--r-- | man/systemd.special.xml | 2 |
11 files changed, 162 insertions, 49 deletions
diff --git a/man/daemon.xml b/man/daemon.xml index b6125cb5c7..fed1ca1f49 100644 --- a/man/daemon.xml +++ b/man/daemon.xml @@ -234,7 +234,7 @@ bus-activatable by supplying a D-Bus service activation configuration file. This has multiple advantages: your daemon may be started lazily on-demand; it may be started in parallel - to other daemons requiring it -- which maximizes + to other daemons requiring it — which maximizes parallelization and boot-up speed; your daemon can be restarted on failure without losing any bus requests, as the bus queues requests for activatable services. See below for 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/sd_event_source_set_priority.xml b/man/sd_event_source_set_priority.xml index 9234f4233e..8c9b39fe5e 100644 --- a/man/sd_event_source_set_priority.xml +++ b/man/sd_event_source_set_priority.xml @@ -97,7 +97,7 @@ <constant>SD_EVENT_PRIORITY_IDLE</constant> (100) may be used to indicate event sources that shall be dispatched early, normally or late. It is recommended to specify priorities based on these - definitions, and relative to them -- however, the full 64bit + definitions, and relative to them — however, the full 64bit signed integer range is available for ordering event sources.</para> diff --git a/man/sd_journal_add_match.xml b/man/sd_journal_add_match.xml index 3b27444f8d..98415d53fd 100644 --- a/man/sd_journal_add_match.xml +++ b/man/sd_journal_add_match.xml @@ -88,11 +88,19 @@ <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry> and <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>. - Matches are of the form <literal>FIELD=value</literal>, where the - field part is a short uppercase string consisting only of 0–9, A–Z - and the underscore. It may not begin with two underscores or be - the empty string. The value part may be any value, including - binary. If a match is applied, only entries with this field set + Parameter <parameter>data</parameter> must be of the form + <literal><replaceable>FIELD</replaceable>=<replaceable>value</replaceable></literal>, + where the <replaceable>FIELD</replaceable> part is a short uppercase string consisting only + of 0–9, A–Z and the underscore; it may not begin with two underscores or be the empty + string. The <replaceable>value</replaceable> part may be anything, including binary. Parameter + <parameter>size</parameter> specifies the number of bytes in <parameter>data</parameter> + (i.e. the length of <replaceable>FIELD</replaceable>, plus one, plus the length of + <replaceable>value</replaceable>). Parameter <parameter>size</parameter> may also be + specified as <constant>0</constant>, in which case <parameter>data</parameter> + must be a <constant>NUL</constant>-terminated string, and the bytes before the terminating + zero are used as the match.</para> + + <para>If a match is applied, only entries with this field set will be iterated. Multiple matches may be active at the same time: If they apply to different fields, only entries with both fields set like this will be iterated. If they apply to the same fields, diff --git a/man/sd_journal_get_data.xml b/man/sd_journal_get_data.xml index 1f25d068d7..908ee7db16 100644 --- a/man/sd_journal_get_data.xml +++ b/man/sd_journal_get_data.xml @@ -148,7 +148,7 @@ <function>sd_journal_enumerate_unique()</function>. This threshold is a hint only: it indicates that the client program is interested only in the initial parts of the data fields, up to the threshold - in size -- but the library might still return larger data objects. + in size — but the library might still return larger data objects. That means applications should not rely exclusively on this setting to limit the size of the data fields returned, but need to apply a explicit size limit on the returned data as well. This diff --git a/man/systemd-ask-password.xml b/man/systemd-ask-password.xml index e84a15c554..2b6fb5a82f 100644 --- a/man/systemd-ask-password.xml +++ b/man/systemd-ask-password.xml @@ -67,7 +67,7 @@ processes.</para> <para>The purpose of this tool is to query system-wide passwords - -- that is passwords not attached to a specific user account. + — that is passwords not attached to a specific user account. Examples include: unlocking encrypted hard disks when they are plugged in or at boot, entering an SSL certificate passphrase for web and VPN servers.</para> diff --git a/man/systemd-journal-gatewayd.service.xml b/man/systemd-journal-gatewayd.service.xml index e32ac26850..9ed85c3950 100644 --- a/man/systemd-journal-gatewayd.service.xml +++ b/man/systemd-journal-gatewayd.service.xml @@ -262,7 +262,7 @@ <term><uri>boot</uri></term> <listitem><para>Limit events to the current boot of the system - (like <command>journalctl --this--boot</command>).</para></listitem> + (like <command>journalctl --this-boot</command>).</para></listitem> </varlistentry> <varlistentry> diff --git a/man/systemd-nspawn.xml b/man/systemd-nspawn.xml index 6732b9d7be..a0376ed3e0 100644 --- a/man/systemd-nspawn.xml +++ b/man/systemd-nspawn.xml @@ -502,7 +502,7 @@ host interface name and container interface name. The latter may be omitted in which case the container and host sides will be assigned the same name. This switch is independent of - <option>--network-veth</option>, and -- in contrast -- may be + <option>--network-veth</option>, and — in contrast — may be used multiple times, and allows configuration of the network interface names. Note that <option>--network-bridge=</option> has no effect on interfaces created with 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> diff --git a/man/systemd.special.xml b/man/systemd.special.xml index 80c15b700d..14998b9647 100644 --- a/man/systemd.special.xml +++ b/man/systemd.special.xml @@ -742,7 +742,7 @@ defined what that is supposed to mean, with one exception: at shutdown, a unit that is ordered after <filename>network.target</filename> will be stopped before - the network -- to whatever level it might be set up then -- + the network — to whatever level it might be set up then — is shut down. It is hence useful when writing service files that require network access on shutdown, which should order themselves after this target, but not pull it in. Also see |