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 | 47 | ||||
| -rw-r--r-- | man/sd_journal_open.xml | 11 | ||||
| -rw-r--r-- | man/systemctl.xml | 23 | ||||
| -rw-r--r-- | man/systemd-inhibit.xml | 2 | ||||
| -rw-r--r-- | man/systemd-logind.service.xml | 2 | ||||
| -rw-r--r-- | man/systemd.exec.xml | 60 | ||||
| -rw-r--r-- | man/systemd.resource-control.xml | 98 |
9 files changed, 164 insertions, 128 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 adba5a4131..9b0e181849 100644 --- a/man/logind.conf.xml +++ b/man/logind.conf.xml @@ -211,7 +211,7 @@ <term><varname>HandleLidSwitch=</varname></term> <term><varname>HandleLidSwitchDocked=</varname></term> - <listitem><para>Controls whether logind shall handle the + <listitem><para>Controls how logind shall handle the system power and sleep keys and the lid switch to trigger actions such as system power-off or suspend. Can be one of <literal>ignore</literal>, @@ -240,7 +240,16 @@ docking station, or if more than one display is connected, the action specified by <varname>HandleLidSwitchDocked=</varname> occurs; otherwise the <varname>HandleLidSwitch=</varname> - action occurs.</para></listitem> + action occurs.</para> + + <para>A different application may disable logind's handling of system power and + sleep keys and the lid switch by taking a low-level inhibitor lock + ("handle-power-key", "handle-suspend-key", "handle-hibernate-key", + "handle-lid-switch"). This is most commonly used by graphical desktop environments + to take over suspend and hibernation handling, and to use their own configuration + mechanisms. If a low-level inhibitor lock is taken, logind will not take any + action when that key or switch is triggered and the <varname>Handle*=</varname> + settings are irrelevant.</para></listitem> </varlistentry> <varlistentry> @@ -249,21 +258,22 @@ <term><varname>HibernateKeyIgnoreInhibited=</varname></term> <term><varname>LidSwitchIgnoreInhibited=</varname></term> - <listitem><para>Controls whether actions triggered by the - power and sleep keys and the lid switch are subject to - inhibitor locks. These settings take boolean arguments. If - <literal>no</literal>, the inhibitor locks taken by - applications in order to block the requested operation are - respected. If <literal>yes</literal>, the requested operation - is executed in any case. + <listitem><para>Controls whether actions that <command>systemd-logind</command> + takes when the power and sleep keys and the lid switch are triggered are subject + to high-level inhibitor locks ("shutdown", "sleep", "idle"). Low level inhibitor + locks ("handle-*-key"), are always honoured, irrespective of this setting.</para> + + <para>These settings take boolean arguments. If <literal>no</literal>, the + inhibitor locks taken by applications are respected. If <literal>yes</literal>, + "shutdown", "sleep", and "idle" inhibitor locks are ignored. <varname>PowerKeyIgnoreInhibited=</varname>, - <varname>SuspendKeyIgnoreInhibited=</varname> and - <varname>HibernateKeyIgnoreInhibited=</varname> default to - <literal>no</literal>. - <varname>LidSwitchIgnoreInhibited=</varname> defaults to - <literal>yes</literal>. This means that the lid switch does - not respect suspend blockers by default, but the power and - sleep keys do. </para></listitem> + <varname>SuspendKeyIgnoreInhibited=</varname>, and + <varname>HibernateKeyIgnoreInhibited=</varname> default to <literal>no</literal>. + <varname>LidSwitchIgnoreInhibited=</varname> defaults to <literal>yes</literal>. + This means that when <command>systemd-logind</command> is handling events by + itself (no low level inhibitor locks are taken by another application), the lid + switch does not respect suspend blockers by default, but the power and sleep keys + do.</para></listitem> </varlistentry> <varlistentry> @@ -318,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 78607c9ba3..fde4f4f3bb 100644 --- a/man/systemctl.xml +++ b/man/systemctl.xml @@ -1681,20 +1681,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-inhibit.xml b/man/systemd-inhibit.xml index 9d85908f97..ce169960d8 100644 --- a/man/systemd-inhibit.xml +++ b/man/systemd-inhibit.xml @@ -61,7 +61,7 @@ <title>Description</title> <para><command>systemd-inhibit</command> may be used to execute a - program with a shutdown, sleep or idle inhibitor lock taken. The + program with a shutdown, sleep, or idle inhibitor lock taken. The lock will be acquired before the specified command line is executed and released afterwards.</para> diff --git a/man/systemd-logind.service.xml b/man/systemd-logind.service.xml index 5733e42cd1..f0bdb1c756 100644 --- a/man/systemd-logind.service.xml +++ b/man/systemd-logind.service.xml @@ -84,7 +84,7 @@ management</para></listitem> </itemizedlist> - <para>User sessions are registered in logind via the + <para>User sessions are registered with logind via the <citerefentry><refentrytitle>pam_systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry> PAM module.</para> diff --git a/man/systemd.exec.xml b/man/systemd.exec.xml index bf82326096..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> 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> |