diff options
Diffstat (limited to 'man')
| -rw-r--r-- | man/hostnamectl.xml | 43 | ||||
| -rw-r--r-- | man/journalctl.xml | 6 | ||||
| -rw-r--r-- | man/logind.conf.xml | 5 | ||||
| -rw-r--r-- | man/sd_journal_open.xml | 11 | ||||
| -rw-r--r-- | man/systemctl.xml | 23 | ||||
| -rw-r--r-- | man/systemd.exec.xml | 76 | ||||
| -rw-r--r-- | man/systemd.resource-control.xml | 98 | ||||
| -rw-r--r-- | man/systemd.service.xml | 19 |
8 files changed, 159 insertions, 122 deletions
diff --git a/man/hostnamectl.xml b/man/hostnamectl.xml index 60004e9d04..9e1b593e6d 100644 --- a/man/hostnamectl.xml +++ b/man/hostnamectl.xml @@ -71,10 +71,9 @@ set, and is valid (something other than localhost), then the transient hostname is not used.</para> - <para>Note that the pretty hostname has little restrictions on the - characters used, while the static and transient hostnames are - limited to the usually accepted characters of Internet domain - names.</para> + <para>Note that the pretty hostname has little restrictions on the characters and length used, while the static and + transient hostnames are limited to the usually accepted characters of Internet domain names, and 64 characters at + maximum (the latter being a Linux limitation).</para> <para>The static hostname is stored in <filename>/etc/hostname</filename>, see @@ -107,15 +106,11 @@ <term><option>--transient</option></term> <term><option>--pretty</option></term> - <listitem><para>If <command>status</command> is used (or no - explicit command is given) and one of those fields is given, - <command>hostnamectl</command> will print out just this - selected hostname.</para> + <listitem><para>If <command>status</command> is invoked (or no explicit command is given) and one of these + switches is specified, <command>hostnamectl</command> will print out just this selected hostname.</para> - <para>If used with <command>set-hostname</command>, only the - selected hostname(s) will be updated. When more than one of - those options is used, all the specified hostnames will be - updated. </para></listitem> + <para>If used with <command>set-hostname</command>, only the selected hostname(s) will be updated. When more + than one of these switches are specified, all the specified hostnames will be updated. </para></listitem> </varlistentry> <xi:include href="user-system-options.xml" xpointer="host" /> @@ -139,22 +134,14 @@ <varlistentry> <term><command>set-hostname <replaceable>NAME</replaceable></command></term> - <listitem><para>Set the system hostname to - <replaceable>NAME</replaceable>. By default, this will alter - the pretty, the static, and the transient hostname alike; - however, if one or more of <option>--static</option>, - <option>--transient</option>, <option>--pretty</option> are - used, only the selected hostnames are changed. If the pretty - hostname is being set, and static or transient are being set - as well, the specified hostname will be simplified in regards - to the character set used before the latter are updated. This - is done by replacing spaces with <literal>-</literal> and - removing special characters. This ensures that the pretty and - the static hostname are always closely related while still - following the validity rules of the specific name. This - simplification of the hostname string is not done if only the - transient and/or static host names are set, and the pretty - host name is left untouched.</para> + <listitem><para>Set the system hostname to <replaceable>NAME</replaceable>. By default, this will alter the + pretty, the static, and the transient hostname alike; however, if one or more of <option>--static</option>, + <option>--transient</option>, <option>--pretty</option> are used, only the selected hostnames are changed. If + the pretty hostname is being set, and static or transient are being set as well, the specified hostname will be + simplified in regards to the character set used before the latter are updated. This is done by removing special + characters and spaces. This ensures that the pretty and the static hostname are always closely related while + still following the validity rules of the specific name. This simplification of the hostname string is not done + if only the transient and/or static host names are set, and the pretty host name is left untouched.</para> <para>Pass the empty string <literal></literal> as the hostname to reset the selected hostnames to their default diff --git a/man/journalctl.xml b/man/journalctl.xml index c448a29a51..63b4a267b8 100644 --- a/man/journalctl.xml +++ b/man/journalctl.xml @@ -659,10 +659,12 @@ <term><option>--root=<replaceable>ROOT</replaceable></option></term> <listitem><para>Takes a directory path as an argument. If - specified, journalctl will operate on catalog file hierarchy + specified, journalctl will operate on journal directories and catalog file hierarchy underneath the specified directory instead of the root directory (e.g. <option>--update-catalog</option> will create - <filename><replaceable>ROOT</replaceable>/var/lib/systemd/catalog/database</filename>). + <filename><replaceable>ROOT</replaceable>/var/lib/systemd/catalog/database</filename>, + and journal files under <filename><replaceable>ROOT</replaceable>/run/journal</filename> + or <filename><replaceable>ROOT</replaceable>/var/log/journal</filename> will be displayed). </para></listitem> </varlistentry> diff --git a/man/logind.conf.xml b/man/logind.conf.xml index 5931832996..9b0e181849 100644 --- a/man/logind.conf.xml +++ b/man/logind.conf.xml @@ -328,8 +328,9 @@ <listitem><para>Sets the maximum number of OS tasks each user may run concurrently. This controls the <varname>TasksMax=</varname> setting of the per-user slice unit, see <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details. Defaults to 33%, which equals 10813 with the kernel's defaults on the host, but might be smaller - in OS containers.</para></listitem> + for details. If assigned the special value <literal>infinity</literal>, no tasks limit is applied. + Defaults to 33%, which equals 10813 with the kernel's defaults on the host, but might be smaller in + OS containers.</para></listitem> </varlistentry> <varlistentry> diff --git a/man/sd_journal_open.xml b/man/sd_journal_open.xml index 153af2387f..74e67023b5 100644 --- a/man/sd_journal_open.xml +++ b/man/sd_journal_open.xml @@ -129,10 +129,13 @@ <para><function>sd_journal_open_directory()</function> is similar to <function>sd_journal_open()</function> but takes an absolute directory path as argument. All journal files in this directory will be opened and interleaved - automatically. This call also takes a flags argument. The only flags parameter accepted by this call is - <constant>SD_JOURNAL_OS_ROOT</constant>. If specified, the journal files are searched below the usual - <filename>/var/log/journal</filename> and <filename>/run/log/journal</filename> relative to the specified path, - instead of directly beneath it.</para> + automatically. This call also takes a flags argument. The flags parameters accepted by this call are + <constant>SD_JOURNAL_OS_ROOT</constant>, <constant>SD_JOURNAL_SYSTEM</constant>, and + <constant>SD_JOURNAL_CURRENT_USER</constant>. If <constant>SD_JOURNAL_OS_ROOT</constant> is specified, journal + files are searched for below the usual <filename>/var/log/journal</filename> and + <filename>/run/log/journal</filename> relative to the specified path, instead of directly beneath it. + The other two flags limit which files are opened, the same as for <function>sd_journal_open()</function>. + </para> <para><function>sd_journal_open_directory_fd()</function> is similar to <function>sd_journal_open_directory()</function>, but takes a file descriptor referencing a directory in the file diff --git a/man/systemctl.xml b/man/systemctl.xml index 0ad0ad6d7e..9762fd0450 100644 --- a/man/systemctl.xml +++ b/man/systemctl.xml @@ -1680,20 +1680,15 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service <term><command>switch-root <replaceable>ROOT</replaceable> <optional><replaceable>INIT</replaceable></optional></command></term> <listitem> - <para>Switches to a different root directory and executes a - new system manager process below it. This is intended for - usage in initial RAM disks ("initrd"), and will transition - from the initrd's system manager process (a.k.a. "init" - process) to the main system manager process. This call takes two - arguments: the directory that is to become the new root directory, and - the path to the new system manager binary below it to - execute as PID 1. If the latter is omitted or the empty - string, a systemd binary will automatically be searched for - and used as init. If the system manager path is omitted or - equal to the empty string, the state of the initrd's system - manager process is passed to the main system manager, which - allows later introspection of the state of the services - involved in the initrd boot.</para> + <para>Switches to a different root directory and executes a new system manager process below it. This is + intended for usage in initial RAM disks ("initrd"), and will transition from the initrd's system manager + process (a.k.a. "init" process) to the main system manager process which is loaded from the actual host + volume. This call takes two arguments: the directory that is to become the new root directory, and the path + to the new system manager binary below it to execute as PID 1. If the latter is omitted or the empty + string, a systemd binary will automatically be searched for and used as init. If the system manager path is + omitted, equal to the empty string or identical to the path to the systemd binary, the state of the + initrd's system manager process is passed to the main system manager, which allows later introspection of + the state of the services involved in the initrd boot phase.</para> </listitem> </varlistentry> diff --git a/man/systemd.exec.xml b/man/systemd.exec.xml index f8b2aff81b..bcedebd5bb 100644 --- a/man/systemd.exec.xml +++ b/man/systemd.exec.xml @@ -160,14 +160,14 @@ use. However, UID/GIDs are recycled after a unit is terminated. Care should be taken that any processes running as part of a unit for which dynamic users/groups are enabled do not leave files or directories owned by these users/groups around, as a different unit might get the same UID/GID assigned later on, and thus gain access to - these files or directories. If <varname>DynamicUser=</varname> is enabled, <varname>PrivateTmp=</varname> is - implied. This ensures that the lifetime of temporary files created by the executed processes is bound to the - runtime of the service, and hence the lifetime of the dynamic user/group. Since <filename>/tmp</filename> and - <filename>/var/tmp</filename> are usually the only world-writable directories on a system this ensures that a - unit making use of dynamic user/group allocation cannot leave files around after unit termination. Use - <varname>RuntimeDirectory=</varname> (see below) in order to assign a writable runtime directory to a service, - owned by the dynamic user/group and removed automatically when the unit is terminated. Defaults to - off.</para></listitem> + these files or directories. If <varname>DynamicUser=</varname> is enabled, <varname>RemoveIPC=</varname> and + <varname>PrivateTmp=</varname> are implied. This ensures that the lifetime of IPC objects and temporary files + created by the executed processes is bound to the runtime of the service, and hence the lifetime of the dynamic + user/group. Since <filename>/tmp</filename> and <filename>/var/tmp</filename> are usually the only + world-writable directories on a system this ensures that a unit making use of dynamic user/group allocation + cannot leave files around after unit termination. Use <varname>RuntimeDirectory=</varname> (see below) in order + to assign a writable runtime directory to a service, owned by the dynamic user/group and removed automatically + when the unit is terminated. Defaults to off.</para></listitem> </varlistentry> <varlistentry> @@ -186,6 +186,18 @@ </varlistentry> <varlistentry> + <term><varname>RemoveIPC=</varname></term> + + <listitem><para>Takes a boolean parameter. If set, all System V and POSIX IPC objects owned by the user and + group the processes of this unit are run as are removed when the unit is stopped. This setting only has an + effect if at least one of <varname>User=</varname>, <varname>Group=</varname> and + <varname>DynamicUser=</varname> are used. It has no effect on IPC objects owned by the root user. Specifically, + this removes System V semaphores, as well as System V and POSIX shared memory segments and message queues. If + multiple units use the same user or group the IPC objects are removed when the last of these units is + stopped. This setting is implied if <varname>DynamicUser=</varname> is set.</para></listitem> + </varlistentry> + + <varlistentry> <term><varname>Nice=</varname></term> <listitem><para>Sets the default nice level (scheduling @@ -920,27 +932,19 @@ <varlistentry> <term><varname>PrivateTmp=</varname></term> - <listitem><para>Takes a boolean argument. If true, sets up a - new file system namespace for the executed processes and - mounts private <filename>/tmp</filename> and - <filename>/var/tmp</filename> directories inside it that is - not shared by processes outside of the namespace. This is - useful to secure access to temporary files of the process, but - makes sharing between processes via <filename>/tmp</filename> - or <filename>/var/tmp</filename> impossible. If this is - enabled, all temporary files created by a service in these - directories will be removed after the service is stopped. - Defaults to false. It is possible to run two or more units - within the same private <filename>/tmp</filename> and - <filename>/var/tmp</filename> namespace by using the + <listitem><para>Takes a boolean argument. If true, sets up a new file system namespace for the executed + processes and mounts private <filename>/tmp</filename> and <filename>/var/tmp</filename> directories inside it + that is not shared by processes outside of the namespace. This is useful to secure access to temporary files of + the process, but makes sharing between processes via <filename>/tmp</filename> or <filename>/var/tmp</filename> + impossible. If this is enabled, all temporary files created by a service in these directories will be removed + after the service is stopped. Defaults to false. It is possible to run two or more units within the same + private <filename>/tmp</filename> and <filename>/var/tmp</filename> namespace by using the <varname>JoinsNamespaceOf=</varname> directive, see - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details. Note that using this setting will disconnect - propagation of mounts from the service to the host - (propagation in the opposite direction continues to work). - This means that this setting may not be used for services - which shall be able to install mount points in the main mount - namespace.</para></listitem> + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> for + details. Note that using this setting will disconnect propagation of mounts from the service to the host + (propagation in the opposite direction continues to work). This means that this setting may not be used for + services which shall be able to install mount points in the main mount namespace. This setting is implied if + <varname>DynamicUser=</varname> is set.</para></listitem> </varlistentry> <varlistentry> @@ -1669,6 +1673,18 @@ <tbody> <row> + <entry morerows="1" valign="top"><literal>timeout</literal></entry> + <entry valign="top"><literal>killed</literal></entry> + <entry><literal>TERM</literal><sbr/><literal>KILL</literal></entry> + </row> + + <row> + <entry valign="top"><literal>exited</literal></entry> + <entry><literal>0</literal><sbr/><literal>1</literal><sbr/><literal>2</literal><sbr/><literal + >3</literal><sbr/>…<sbr/><literal>255</literal></entry> + </row> + + <row> <entry valign="top"><literal>exit-code</literal></entry> <entry valign="top"><literal>exited</literal></entry> <entry><literal>0</literal><sbr/><literal>1</literal><sbr/><literal>2</literal><sbr/><literal @@ -1707,6 +1723,10 @@ <entry>any of the above</entry> <entry>any of the above</entry> </row> + + <row> + <entry namest="results" nameend="code">Note: the process may be also terminated by a signal not sent by systemd. In particular the process may send an arbitrary signal to itself in a handler for any of the non-maskable signals. Nevertheless, in the <literal>timeout</literal> and <literal>watchdog</literal> rows above only the signals that systemd sends have been included.</entry> + </row> </tbody> </tgroup> </table> diff --git a/man/systemd.resource-control.xml b/man/systemd.resource-control.xml index 0e98ca78b8..84dbfa2ff3 100644 --- a/man/systemd.resource-control.xml +++ b/man/systemd.resource-control.xml @@ -106,13 +106,21 @@ <para> <variablelist> + <varlistentry> - <term><option>IO</option></term> + <term><option>CPU</option></term> <listitem> - <para><varname>IO</varname> prefixed settings are superset of and replace <varname>BlockIO</varname> - prefixed ones. On unified hierarchy, IO resource control also applies to buffered writes.</para> + <para>Due to the lack of consensus in the kernel community, the CPU controller support on the unified + cgroup hierarchy requires out-of-tree kernel patches. See <ulink + url="https://git.kernel.org/cgit/linux/kernel/git/tj/cgroup.git/tree/Documentation/cgroup-v2-cpu.txt?h=cgroup-v2-cpu">cgroup-v2-cpu.txt</ulink>.</para> + + <para><varname>CPUWeight=</varname> and <varname>StartupCPUWeight=</varname> replace + <varname>CPUShares=</varname> and <varname>StartupCPUShares=</varname>, respectively.</para> + + <para>The <literal>cpuacct</literal> controller does not exist separately on the unified hierarchy.</para> </listitem> </varlistentry> + <varlistentry> <term><option>Memory</option></term> <listitem> @@ -120,6 +128,15 @@ and <varname>MemoryHigh=</varname> are effective only on unified hierarchy.</para> </listitem> </varlistentry> + + <varlistentry> + <term><option>IO</option></term> + <listitem> + <para><varname>IO</varname> prefixed settings are superset of and replace <varname>BlockIO</varname> + prefixed ones. On unified hierarchy, IO resource control also applies to buffered writes.</para> + </listitem> + </varlistentry> + </variablelist> </para> @@ -160,30 +177,49 @@ </varlistentry> <varlistentry> + <term><varname>CPUWeight=<replaceable>weight</replaceable></varname></term> + <term><varname>StartupCPUWeight=<replaceable>weight</replaceable></varname></term> + + <listitem> + <para>Assign the specified CPU time weight to the processes executed, if the unified control group hierarchy + is used on the system. These options take an integer value and control the <literal>cpu.weight</literal> + control group attribute. The allowed range is 1 to 10000. Defaults to 100. For details about this control + group attribute, see <ulink + url="https://www.kernel.org/doc/Documentation/cgroup-v2.txt">cgroup-v2.txt</ulink> and <ulink + url="https://www.kernel.org/doc/Documentation/scheduler/sched-design-CFS.txt">sched-design-CFS.txt</ulink>. + The available CPU time is split up among all units within one slice relative to their CPU time weight.</para> + + <para>While <varname>StartupCPUWeight=</varname> only applies to the startup phase of the system, + <varname>CPUWeight=</varname> applies to normal runtime of the system, and if the former is not set also to + the startup phase. Using <varname>StartupCPUWeight=</varname> allows prioritizing specific services at + boot-up differently than during normal runtime.</para> + + <para>Implies <literal>CPUAccounting=true</literal>.</para> + + <para>These settings are supported only if the unified control group hierarchy is used.</para> + </listitem> + </varlistentry> + + <varlistentry> <term><varname>CPUShares=<replaceable>weight</replaceable></varname></term> <term><varname>StartupCPUShares=<replaceable>weight</replaceable></varname></term> <listitem> - <para>Assign the specified CPU time share weight to the - processes executed. These options take an integer value and - control the <literal>cpu.shares</literal> control group - attribute. The allowed range is 2 to 262144. Defaults to - 1024. For details about this control group attribute, see - <ulink + <para>Assign the specified CPU time share weight to the processes executed. These options take an integer + value and control the <literal>cpu.shares</literal> control group attribute. The allowed range is 2 to + 262144. Defaults to 1024. For details about this control group attribute, see <ulink url="https://www.kernel.org/doc/Documentation/scheduler/sched-design-CFS.txt">sched-design-CFS.txt</ulink>. - The available CPU time is split up among all units within - one slice relative to their CPU time share weight.</para> + The available CPU time is split up among all units within one slice relative to their CPU time share + weight.</para> - <para>While <varname>StartupCPUShares=</varname> only - applies to the startup phase of the system, - <varname>CPUShares=</varname> applies to normal runtime of - the system, and if the former is not set also to the startup - phase. Using <varname>StartupCPUShares=</varname> allows - prioritizing specific services at boot-up differently than - during normal runtime.</para> + <para>While <varname>StartupCPUShares=</varname> only applies to the startup phase of the system, + <varname>CPUShares=</varname> applies to normal runtime of the system, and if the former is not set also to + the startup phase. Using <varname>StartupCPUShares=</varname> allows prioritizing specific services at + boot-up differently than during normal runtime.</para> - <para>These options imply - <literal>CPUAccounting=true</literal>.</para> + <para>Implies <literal>CPUAccounting=true</literal>.</para> + + <para>These settings are supported only if the legacy control group hierarchy is used.</para> </listitem> </varlistentry> @@ -191,22 +227,20 @@ <term><varname>CPUQuota=</varname></term> <listitem> - <para>Assign the specified CPU time quota to the processes - executed. Takes a percentage value, suffixed with "%". The - percentage specifies how much CPU time the unit shall get at - maximum, relative to the total CPU time available on one - CPU. Use values > 100% for allotting CPU time on more than - one CPU. This controls the - <literal>cpu.cfs_quota_us</literal> control group - attribute. For details about this control group attribute, - see <ulink + <para>Assign the specified CPU time quota to the processes executed. Takes a percentage value, suffixed with + "%". The percentage specifies how much CPU time the unit shall get at maximum, relative to the total CPU time + available on one CPU. Use values > 100% for allotting CPU time on more than one CPU. This controls the + <literal>cpu.max</literal> attribute on the unified control group hierarchy and + <literal>cpu.cfs_quota_us</literal> on legacy. For details about these control group attributes, see <ulink + url="https://www.kernel.org/doc/Documentation/cgroup-v2.txt">cgroup-v2.txt</ulink> and <ulink url="https://www.kernel.org/doc/Documentation/scheduler/sched-design-CFS.txt">sched-design-CFS.txt</ulink>.</para> - <para>Example: <varname>CPUQuota=20%</varname> ensures that - the executed processes will never get more than 20% CPU time - on one CPU.</para> + <para>Example: <varname>CPUQuota=20%</varname> ensures that the executed processes will never get more than + 20% CPU time on one CPU.</para> <para>Implies <literal>CPUAccounting=true</literal>.</para> + + <para>This setting is supported on both unified and legacy control group hierarchies.</para> </listitem> </varlistentry> diff --git a/man/systemd.service.xml b/man/systemd.service.xml index e82edbe93e..b58e887662 100644 --- a/man/systemd.service.xml +++ b/man/systemd.service.xml @@ -276,17 +276,12 @@ below (see section "Command Lines" below). </para> - <para>When <varname>Type=</varname> is not - <option>oneshot</option>, only one command may and must be - given. When <varname>Type=oneshot</varname> is used, zero or - more commands may be specified. This can be specified by - providing multiple command lines in the same directive, or - alternatively, this directive may be specified more than once - with the same effect. If the empty string is assigned to this - option, the list of commands to start is reset, prior - assignments of this option will have no effect. If no - <varname>ExecStart=</varname> is specified, then the service - must have <varname>RemainAfterExit=yes</varname> set.</para> + <para>Unless <varname>Type=</varname> is <option>oneshot</option>, exactly one command must be given. When + <varname>Type=oneshot</varname> is used, zero or more commands may be specified. Commands may be specified by + providing multiple command lines in the same directive, or alternatively, this directive may be specified more + than once with the same effect. If the empty string is assigned to this option, the list of commands to start + is reset, prior assignments of this option will have no effect. If no <varname>ExecStart=</varname> is + specified, then the service must have <varname>RemainAfterExit=yes</varname> set.</para> <para>For each of the specified commands, the first argument must be an absolute path to an executable. Optionally, if this file name is prefixed with <literal>@</literal>, the second token will be @@ -294,7 +289,7 @@ the absolute filename is prefixed with <literal>-</literal>, an exit code of the command normally considered a failure (i.e. non-zero exit status or abnormal exit due to signal) is ignored and considered success. If the absolute path is prefixed with <literal>+</literal> then it is executed with full - privileges. <literal>-</literal>, <literal>@</literal>, and <literal>+</literal> may be used together and they + privileges. <literal>@</literal>, <literal>-</literal>, and <literal>+</literal> may be used together and they can appear in any order.</para> <para>If more than one command is specified, the commands are |