man: rework BPFForeign= documentation a bit

Various assorted changes, among them make clear that a missing BPF
program is not reason to abort unit activation.

diff --git a/man/systemd.resource-control.xml b/man/systemd.resource-control.xml
index 1cd0beea046164f8fc506872673e0bae35a31e54..57ebb8e1ea16144e57a6105f35242bcf7f9c62ad 100644 (file)
--- a/man/systemd.resource-control.xml
+++ b/man/systemd.resource-control.xml
@@ -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 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>,
+          <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>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 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>