mirror of
https://github.com/systemd/systemd.git
synced 2024-12-23 21:35:11 +03:00
man: place options in a some limited form of subsections
Let's visually separate the options associated with cpu, io, memory, … in subsections This patch tries to be minimal. It just adds the section titles, and does minimal reordering to make sure the options on the same kind of resource are placed close to each other.
This commit is contained in:
Lennart Poettering
Zbigniew Jędrzejewski-Szmek
parent
d9714fe405
commit
5cbfbf2aaa
@ -174,8 +174,9 @@ CPUWeight=20 DisableControllers=cpu / \
|
||||
<refsect1>
|
||||
<title>Options</title>
|
||||
|
||||
<para>Units of the types listed above can have settings
|
||||
for resource control configuration:</para>
|
||||
<para>Units of the types listed above can have settings for resource control configuration:</para>
|
||||
|
||||
<refsect2><title>CPU Accounting and Control</title>
|
||||
|
||||
<variablelist class='unit-directives'>
|
||||
|
||||
@ -305,29 +306,11 @@ CPUWeight=20 DisableControllers=cpu / \
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><varname>AllowedMemoryNodes=</varname></term>
|
||||
<term><varname>StartupAllowedMemoryNodes=</varname></term>
|
||||
</variablelist>
|
||||
|
||||
<listitem>
|
||||
<para>These settings control the <option>cpuset</option> controller in the unified hierarchy.</para>
|
||||
</refsect2><refsect2><title>Memory Accounting and Control</title>
|
||||
|
||||
<para>Restrict processes to be executed on specific memory NUMA nodes. Takes a list of memory NUMA nodes indices
|
||||
or ranges separated by either whitespace or commas. Memory NUMA nodes ranges are specified by the lower and upper
|
||||
NUMA nodes indices separated by a dash.</para>
|
||||
|
||||
<para>Setting <varname>AllowedMemoryNodes=</varname> or <varname>StartupAllowedMemoryNodes=</varname> doesn't
|
||||
guarantee that all of the memory NUMA nodes will be used by the processes as it may be limited by parent units.
|
||||
The effective configuration is reported as <varname>EffectiveMemoryNodes=</varname>.</para>
|
||||
|
||||
<para>While <varname>StartupAllowedMemoryNodes=</varname> applies to the startup and shutdown phases of the system,
|
||||
<varname>AllowedMemoryNodes=</varname> applies to normal runtime of the system, and if the former is not set also to
|
||||
the startup and shutdown phases. Using <varname>StartupAllowedMemoryNodes=</varname> allows prioritizing specific services at
|
||||
boot-up and shutdown differently than during normal runtime.</para>
|
||||
|
||||
<para>This setting is supported only with the unified control group hierarchy.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<variablelist class='unit-directives'>
|
||||
|
||||
<varlistentry>
|
||||
<term><varname>MemoryAccounting=</varname></term>
|
||||
@ -492,6 +475,36 @@ CPUWeight=20 DisableControllers=cpu / \
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><varname>AllowedMemoryNodes=</varname></term>
|
||||
<term><varname>StartupAllowedMemoryNodes=</varname></term>
|
||||
|
||||
<listitem>
|
||||
<para>These settings control the <option>cpuset</option> controller in the unified hierarchy.</para>
|
||||
|
||||
<para>Restrict processes to be executed on specific memory NUMA nodes. Takes a list of memory NUMA nodes indices
|
||||
or ranges separated by either whitespace or commas. Memory NUMA nodes ranges are specified by the lower and upper
|
||||
NUMA nodes indices separated by a dash.</para>
|
||||
|
||||
<para>Setting <varname>AllowedMemoryNodes=</varname> or <varname>StartupAllowedMemoryNodes=</varname> doesn't
|
||||
guarantee that all of the memory NUMA nodes will be used by the processes as it may be limited by parent units.
|
||||
The effective configuration is reported as <varname>EffectiveMemoryNodes=</varname>.</para>
|
||||
|
||||
<para>While <varname>StartupAllowedMemoryNodes=</varname> applies to the startup and shutdown phases of the system,
|
||||
<varname>AllowedMemoryNodes=</varname> applies to normal runtime of the system, and if the former is not set also to
|
||||
the startup and shutdown phases. Using <varname>StartupAllowedMemoryNodes=</varname> allows prioritizing specific services at
|
||||
boot-up and shutdown differently than during normal runtime.</para>
|
||||
|
||||
<para>This setting is supported only with the unified control group hierarchy.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
</variablelist>
|
||||
|
||||
</refsect2><refsect2><title>Process Accounting and Control</title>
|
||||
|
||||
<variablelist class='unit-directives'>
|
||||
|
||||
<varlistentry>
|
||||
<term><varname>TasksAccounting=</varname></term>
|
||||
|
||||
@ -529,6 +542,12 @@ CPUWeight=20 DisableControllers=cpu / \
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
</variablelist>
|
||||
|
||||
</refsect2><refsect2><title>IO Accounting and Control</title>
|
||||
|
||||
<variablelist class='unit-directives'>
|
||||
|
||||
<varlistentry>
|
||||
<term><varname>IOAccounting=</varname></term>
|
||||
|
||||
@ -665,6 +684,12 @@ CPUWeight=20 DisableControllers=cpu / \
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
</variablelist>
|
||||
|
||||
</refsect2><refsect2><title>Network Accounting and Control</title>
|
||||
|
||||
<variablelist class='unit-directives'>
|
||||
|
||||
<varlistentry>
|
||||
<term><varname>IPAccounting=</varname></term>
|
||||
|
||||
@ -791,91 +816,6 @@ CPUWeight=20 DisableControllers=cpu / \
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><varname>IPIngressFilterPath=<replaceable>BPF_FS_PROGRAM_PATH</replaceable></varname></term>
|
||||
<term><varname>IPEgressFilterPath=<replaceable>BPF_FS_PROGRAM_PATH</replaceable></varname></term>
|
||||
|
||||
<listitem>
|
||||
<para>Add custom network traffic filters implemented as BPF programs, applying to all IP packets
|
||||
sent and received over <constant>AF_INET</constant> and <constant>AF_INET6</constant> sockets.
|
||||
Takes an absolute path to a pinned BPF program in the BPF virtual filesystem (<filename>/sys/fs/bpf/</filename>).
|
||||
</para>
|
||||
|
||||
<para>The filters configured with this option are applied to all sockets created by processes
|
||||
of this unit (or in the case of socket units, associated with it). The filters are loaded in addition
|
||||
to filters any of the parent slice units this unit might be a member of as well as any
|
||||
<varname>IPAddressAllow=</varname> and <varname>IPAddressDeny=</varname> filters in any of these units.
|
||||
By default there are no filters specified.</para>
|
||||
|
||||
<para>If these settings are used multiple times in the same unit all the specified programs are attached. If an
|
||||
empty string is assigned to these settings the program list is reset and all previous specified programs ignored.</para>
|
||||
|
||||
<para>If the path <replaceable>BPF_FS_PROGRAM_PATH</replaceable> in <varname>IPIngressFilterPath=</varname> assignment
|
||||
is already being handled by <varname>BPFProgram=</varname> ingress hook, e.g.
|
||||
<varname>BPFProgram=</varname><constant>ingress</constant>:<replaceable>BPF_FS_PROGRAM_PATH</replaceable>,
|
||||
the assignment will be still considered valid and the program will be attached to a cgroup. Same for
|
||||
<varname>IPEgressFilterPath=</varname> path and <constant>egress</constant> hook.</para>
|
||||
|
||||
<para>Note that for socket-activated services, the IP filter programs configured on the socket unit apply to
|
||||
all sockets associated with it directly, but not to any sockets created by the ultimately activated services
|
||||
for it. Conversely, the IP filter programs configured for the service are not applied to any sockets passed into
|
||||
the service via socket activation. Thus, it is usually a good idea, to replicate the IP filter programs on both
|
||||
the socket and the service unit, however it often makes sense to maintain one configuration more open and the other
|
||||
one more restricted, depending on the usecase.</para>
|
||||
|
||||
<para>Note that these settings might not be supported on some systems (for example if eBPF control group
|
||||
support is not enabled in the underlying kernel or container manager). These settings will fail the service in
|
||||
that case. If compatibility with such systems is desired it is hence recommended to attach your filter manually
|
||||
(requires <varname>Delegate=</varname><constant>yes</constant>) instead of using this setting.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><varname>BPFProgram=<replaceable>type</replaceable><constant>:</constant><replaceable>program-path</replaceable></varname></term>
|
||||
<listitem>
|
||||
<para>Add a custom cgroup BPF program.</para>
|
||||
|
||||
<para><varname>BPFProgram=</varname> allows attaching BPF hooks to the cgroup of a systemd unit.
|
||||
(This generalizes the functionality exposed via <varname>IPEgressFilterPath=</varname> for egress and
|
||||
<varname>IPIngressFilterPath=</varname> for ingress.)
|
||||
Cgroup-bpf hooks in the form of BPF programs loaded to the BPF filesystem are attached with cgroup-bpf attach
|
||||
flags determined by the unit. For details about attachment types and flags see <ulink
|
||||
url="https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/include/uapi/linux/bpf.h"/>.
|
||||
For general BPF documentation please refer to <ulink url="https://docs.kernel.org/bpf/index.html"/>.</para>
|
||||
|
||||
<para>The specification of BPF program consists of a <replaceable>type</replaceable> followed by a
|
||||
<replaceable>program-path</replaceable> with <literal>:</literal> as the separator:
|
||||
<replaceable>type</replaceable><constant>:</constant><replaceable>program-path</replaceable>.</para>
|
||||
|
||||
<para><replaceable>type</replaceable> is the string name of BPF attach type also used in
|
||||
<command>bpftool</command>. <replaceable>type</replaceable> can be one of <constant>egress</constant>,
|
||||
<constant>ingress</constant>, <constant>sock_create</constant>, <constant>sock_ops</constant>,
|
||||
<constant>device</constant>, <constant>bind4</constant>, <constant>bind6</constant>,
|
||||
<constant>connect4</constant>, <constant>connect6</constant>, <constant>post_bind4</constant>,
|
||||
<constant>post_bind6</constant>, <constant>sendmsg4</constant>, <constant>sendmsg6</constant>,
|
||||
<constant>sysctl</constant>, <constant>recvmsg4</constant>, <constant>recvmsg6</constant>,
|
||||
<constant>getsockopt</constant>, <constant>setsockopt</constant>.</para>
|
||||
|
||||
<para>Setting <varname>BPFProgram=</varname> to an empty value makes previous assignments ineffective.</para>
|
||||
<para>Multiple assignments of the same <replaceable>type</replaceable>:<replaceable>program-path</replaceable>
|
||||
value have the same effect as a single assignment: the program with the path <replaceable>program-path</replaceable>
|
||||
will be attached to cgroup hook <replaceable>type</replaceable> just once.</para>
|
||||
<para>If BPF <constant>egress</constant> pinned to <replaceable>program-path</replaceable> path is already being
|
||||
handled by <varname>IPEgressFilterPath=</varname>, <varname>BPFProgram=</varname>
|
||||
assignment will be considered valid and <varname>BPFProgram=</varname> will be attached to a cgroup.
|
||||
Similarly for <constant>ingress</constant> hook and <varname>IPIngressFilterPath=</varname> assignment.</para>
|
||||
|
||||
<para>BPF programs passed with <varname>BPFProgram=</varname> are attached to the cgroup of a unit with BPF
|
||||
attach flag <constant>multi</constant>, that allows further attachments of the same
|
||||
<replaceable>type</replaceable> within cgroup hierarchy topped by the unit cgroup.</para>
|
||||
|
||||
<para>Examples:<programlisting>
|
||||
BPFProgram=egress:/sys/fs/bpf/egress-hook
|
||||
BPFProgram=bind6:/sys/fs/bpf/sock-addr-hook
|
||||
</programlisting></para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><varname>SocketBindAllow=<replaceable>bind-rule</replaceable></varname></term>
|
||||
<term><varname>SocketBindDeny=<replaceable>bind-rule</replaceable></varname></term>
|
||||
@ -1017,6 +957,103 @@ RestrictNetworkInterfaces=~eth1</programlisting>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
</variablelist>
|
||||
|
||||
</refsect2><refsect2><title>BPF Programs</title>
|
||||
|
||||
<variablelist class='unit-directives'>
|
||||
|
||||
<varlistentry>
|
||||
<term><varname>IPIngressFilterPath=<replaceable>BPF_FS_PROGRAM_PATH</replaceable></varname></term>
|
||||
<term><varname>IPEgressFilterPath=<replaceable>BPF_FS_PROGRAM_PATH</replaceable></varname></term>
|
||||
|
||||
<listitem>
|
||||
<para>Add custom network traffic filters implemented as BPF programs, applying to all IP packets
|
||||
sent and received over <constant>AF_INET</constant> and <constant>AF_INET6</constant> sockets.
|
||||
Takes an absolute path to a pinned BPF program in the BPF virtual filesystem (<filename>/sys/fs/bpf/</filename>).
|
||||
</para>
|
||||
|
||||
<para>The filters configured with this option are applied to all sockets created by processes
|
||||
of this unit (or in the case of socket units, associated with it). The filters are loaded in addition
|
||||
to filters any of the parent slice units this unit might be a member of as well as any
|
||||
<varname>IPAddressAllow=</varname> and <varname>IPAddressDeny=</varname> filters in any of these units.
|
||||
By default there are no filters specified.</para>
|
||||
|
||||
<para>If these settings are used multiple times in the same unit all the specified programs are attached. If an
|
||||
empty string is assigned to these settings the program list is reset and all previous specified programs ignored.</para>
|
||||
|
||||
<para>If the path <replaceable>BPF_FS_PROGRAM_PATH</replaceable> in <varname>IPIngressFilterPath=</varname> assignment
|
||||
is already being handled by <varname>BPFProgram=</varname> ingress hook, e.g.
|
||||
<varname>BPFProgram=</varname><constant>ingress</constant>:<replaceable>BPF_FS_PROGRAM_PATH</replaceable>,
|
||||
the assignment will be still considered valid and the program will be attached to a cgroup. Same for
|
||||
<varname>IPEgressFilterPath=</varname> path and <constant>egress</constant> hook.</para>
|
||||
|
||||
<para>Note that for socket-activated services, the IP filter programs configured on the socket unit apply to
|
||||
all sockets associated with it directly, but not to any sockets created by the ultimately activated services
|
||||
for it. Conversely, the IP filter programs configured for the service are not applied to any sockets passed into
|
||||
the service via socket activation. Thus, it is usually a good idea, to replicate the IP filter programs on both
|
||||
the socket and the service unit, however it often makes sense to maintain one configuration more open and the other
|
||||
one more restricted, depending on the usecase.</para>
|
||||
|
||||
<para>Note that these settings might not be supported on some systems (for example if eBPF control group
|
||||
support is not enabled in the underlying kernel or container manager). These settings will fail the service in
|
||||
that case. If compatibility with such systems is desired it is hence recommended to attach your filter manually
|
||||
(requires <varname>Delegate=</varname><constant>yes</constant>) instead of using this setting.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><varname>BPFProgram=<replaceable>type</replaceable><constant>:</constant><replaceable>program-path</replaceable></varname></term>
|
||||
<listitem>
|
||||
<para>Add a custom cgroup BPF program.</para>
|
||||
|
||||
<para><varname>BPFProgram=</varname> allows attaching BPF hooks to the cgroup of a systemd unit.
|
||||
(This generalizes the functionality exposed via <varname>IPEgressFilterPath=</varname> for egress and
|
||||
<varname>IPIngressFilterPath=</varname> for ingress.)
|
||||
Cgroup-bpf hooks in the form of BPF programs loaded to the BPF filesystem are attached with cgroup-bpf attach
|
||||
flags determined by the unit. For details about attachment types and flags see <ulink
|
||||
url="https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/include/uapi/linux/bpf.h"/>.
|
||||
For general BPF documentation please refer to <ulink url="https://docs.kernel.org/bpf/index.html"/>.</para>
|
||||
|
||||
<para>The specification of BPF program consists of a <replaceable>type</replaceable> followed by a
|
||||
<replaceable>program-path</replaceable> with <literal>:</literal> as the separator:
|
||||
<replaceable>type</replaceable><constant>:</constant><replaceable>program-path</replaceable>.</para>
|
||||
|
||||
<para><replaceable>type</replaceable> is the string name of BPF attach type also used in
|
||||
<command>bpftool</command>. <replaceable>type</replaceable> can be one of <constant>egress</constant>,
|
||||
<constant>ingress</constant>, <constant>sock_create</constant>, <constant>sock_ops</constant>,
|
||||
<constant>device</constant>, <constant>bind4</constant>, <constant>bind6</constant>,
|
||||
<constant>connect4</constant>, <constant>connect6</constant>, <constant>post_bind4</constant>,
|
||||
<constant>post_bind6</constant>, <constant>sendmsg4</constant>, <constant>sendmsg6</constant>,
|
||||
<constant>sysctl</constant>, <constant>recvmsg4</constant>, <constant>recvmsg6</constant>,
|
||||
<constant>getsockopt</constant>, <constant>setsockopt</constant>.</para>
|
||||
|
||||
<para>Setting <varname>BPFProgram=</varname> to an empty value makes previous assignments ineffective.</para>
|
||||
<para>Multiple assignments of the same <replaceable>type</replaceable>:<replaceable>program-path</replaceable>
|
||||
value have the same effect as a single assignment: the program with the path <replaceable>program-path</replaceable>
|
||||
will be attached to cgroup hook <replaceable>type</replaceable> just once.</para>
|
||||
<para>If BPF <constant>egress</constant> pinned to <replaceable>program-path</replaceable> path is already being
|
||||
handled by <varname>IPEgressFilterPath=</varname>, <varname>BPFProgram=</varname>
|
||||
assignment will be considered valid and <varname>BPFProgram=</varname> will be attached to a cgroup.
|
||||
Similarly for <constant>ingress</constant> hook and <varname>IPIngressFilterPath=</varname> assignment.</para>
|
||||
|
||||
<para>BPF programs passed with <varname>BPFProgram=</varname> are attached to the cgroup of a unit with BPF
|
||||
attach flag <constant>multi</constant>, that allows further attachments of the same
|
||||
<replaceable>type</replaceable> within cgroup hierarchy topped by the unit cgroup.</para>
|
||||
|
||||
<para>Examples:<programlisting>
|
||||
BPFProgram=egress:/sys/fs/bpf/egress-hook
|
||||
BPFProgram=bind6:/sys/fs/bpf/sock-addr-hook
|
||||
</programlisting></para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
</variablelist>
|
||||
|
||||
</refsect2><refsect2><title>Device Access</title>
|
||||
|
||||
<variablelist class='unit-directives'>
|
||||
|
||||
<varlistentry>
|
||||
<term><varname>DeviceAllow=</varname></term>
|
||||
|
||||
@ -1116,6 +1153,12 @@ DeviceAllow=/dev/loop-control
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
</variablelist>
|
||||
|
||||
</refsect2><refsect2><title>Control Group Management</title>
|
||||
|
||||
<variablelist class='unit-directives'>
|
||||
|
||||
<varlistentry>
|
||||
<term><varname>Slice=</varname></term>
|
||||
|
||||
@ -1234,6 +1277,12 @@ DeviceAllow=/dev/loop-control
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
</variablelist>
|
||||
|
||||
</refsect2><refsect2><title>Memory Pressure Control</title>
|
||||
|
||||
<variablelist class='unit-directives'>
|
||||
|
||||
<varlistentry>
|
||||
<term><varname>ManagedOOMSwap=auto|kill</varname></term>
|
||||
<term><varname>ManagedOOMMemoryPressure=auto|kill</varname></term>
|
||||
@ -1367,6 +1416,7 @@ DeviceAllow=/dev/loop-control
|
||||
details on the permitted syntax.</para></listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</refsect2>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user