system/systemd
system/systemd
1
0
Fork 0
mirror of https://github.com/systemd/systemd synced 2024-09-06 16:56:43 +00:00
Code Issues Packages Projects Releases Wiki Activity

man: rework BPFForeign= documentation a bit

Browse source 
Various assorted changes, among them make clear that a missing BPF
program is not reason to abort unit activation.
This commit is contained in:
Lennart Poettering 2023-06-26 13:16:11 +02:00
parent 228459f5d7
commit a27e6fb71b
1 changed files with 28 additions and 23 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

51
man/systemd.resource-control.xml
View file

@ -1003,24 +1003,22 @@ RestrictNetworkInterfaces=~eth1</programlisting>
</varlistentry>
<varlistentry>
<term><varname>BPFProgram=<replaceable>type</replaceable><constant>:</constant><replaceable>program-path</replaceable></varname></term>
<term><varname>BPFProgram=<replaceable>type</replaceable>:<replaceable>program-path</replaceable></varname></term>
<listitem>
<para>Add a custom cgroup BPF program.</para>
<para><varname>BPFProgram=</varname> allows attaching custom BPF programs to the cgroup of a
unit. (This generalizes the functionality exposed via <varname>IPEgressFilterPath=</varname> and
and <varname>IPIngressFilterPath=</varname> for other hooks.) 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"><filename>bpf.h</filename></ulink>. Also
refer to the general <ulink url="https://docs.kernel.org/bpf/">BPF documentation</ulink>.</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 pair of BPF program type and program path in
the file system, with <literal>:</literal> as the separator:
<replaceable>type</replaceable>:<replaceable>program-path</replaceable>.</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>,
<para>The BPF program type is equivalent to the BPF attach type used in
<command>bpftool</command>. It may 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>,
@ -1028,21 +1026,28 @@ RestrictNetworkInterfaces=~eth1</programlisting>
<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>The specified program path must be an absolute path referencing a BPF program inode in the
bpffs file system (which generally means it must begin with <filename>/sys/fs/bpf/</filename>). If
a specified program does not exist (i.e. has not been uploaded to the BPF subsystem of the kernel
yet), it will not be installed but unit activation will continue (a warning will be printed to the
logs).</para>
<para>Setting <varname>BPFProgram=</varname> to an empty value makes previous assignments
ineffective.</para>
<para>Multiple assignments of the same program type/path pair have the same effect as a single
assignment: the program will be attached 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
<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
<para>Examples:<programlisting>BPFProgram=egress:/sys/fs/bpf/egress-hook
BPFProgram=bind6:/sys/fs/bpf/sock-addr-hook
</programlisting></para>
</listitem>