socket: pass socket FDs to all ExecXYZ= commands but ExecStartPre=

Today listen file descriptors created by socket unit don't get passed to
commands in Exec{Start,Stop}{Pre,Post}= socket options.

This prevents ExecXYZ= commands from accessing the created socket FDs to do
any kind of system setup which involves the socket but is not covered by
existing socket unit options.

One concrete example is to insert a socket FD into a BPF map capable of
holding socket references, such as BPF sockmap/sockhash [1] or
reuseport_sockarray [2]. Or, similarly, send the file descriptor with
SCM_RIGHTS to another process, which has access to a BPF map for storing
sockets.

To unblock this use case, pass ListenXYZ= file descriptors to ExecXYZ=
commands as listen FDs [4]. As an exception, ExecStartPre= command does not
inherit any file descriptors because it gets invoked before the listen FDs
are created.

This new behavior can potentially break existing configurations. Commands
invoked from ExecXYZ= might not expect to inherit file descriptors through
sd_listen_fds protocol.

To prevent breakage, add a new socket unit parameter,
PassFileDescriptorsToExec=, to control whether ExecXYZ= programs inherit
listen FDs.

[1] https://docs.kernel.org/bpf/map_sockmap.html
[2] https://lore.kernel.org/r/20180808075917.3009181-1-kafai@fb.com
[3] https://man.archlinux.org/man/socket.7#SO_INCOMING_CPU
[4] https://www.freedesktop.org/software/systemd/man/latest/sd_listen_fds.html

1 files changed, 14 insertions, 0 deletions

diff --git a/man/systemd.socket.xml b/man/systemd.socket.xml
index c7166e4f64..50871f7a74 100644
--- a/man/systemd.socket.xml
+++ b/man/systemd.socket.xml
@@ -922,6 +922,20 @@
         <xi:include href="version-info.xml" xpointer="v255"/></listitem>
       </varlistentry>
 
+      <varlistentry>
+        <term><varname>PassFileDescriptorsToExec=</varname></term>
+
+        <listitem><para>Takes a boolean argument. Defaults to off. If enabled, file descriptors created by
+        the socket unit are passed to <varname>ExecStartPost=</varname>, <varname>ExecStopPre=</varname>, and
+        <varname>ExecStopPost=</varname> commands from the socket unit. The passed file descriptors can be
+        accessed with
+        <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry> as
+        if the commands were invoked from the associated service units.  Note that
+        <varname>ExecStartPre=</varname> command cannot access socket file descriptors.</para>
+
+        <xi:include href="version-info.xml" xpointer="v256"/></listitem>
+      </varlistentry>
+
     </variablelist>
 
     <xi:include href="systemd.service.xml" xpointer="shared-unit-options" />