From: Lennart Poettering <lennart@poettering.net>
Date: Thu, 15 May 2025 16:46:03 +0000 (+0200)
Subject: man: reword recommendations around Accept=
X-Git-Tag: v258-rc1~581
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=fbf43297dd5a0c57aa47776addc7d3e22b8d1203;p=thirdparty%2Fsystemd.git

man: reword recommendations around Accept=

Accept=yes has very valid usecases (i.e. for sporadically invoked
services) and strong benefits (i.e. better security because connections
can be sandboxed nicely, isolating them). Let's hence reword things and
stop claiming that Accept=yes was a legacy thing, because it really
isn't.

Some other man fixes, too
---

diff --git a/man/systemd.socket.xml b/man/systemd.socket.xml
index 39bd0dd6262..b2779e84a2f 100644
--- a/man/systemd.socket.xml
+++ b/man/systemd.socket.xml
@@ -405,17 +405,26 @@
         connection and only the connection socket is passed to it. If no, all listening sockets themselves
         are passed to the started service unit, and only one service unit is spawned for all connections
         (also see above). This value is ignored for datagram sockets and FIFOs where a single service unit
-        unconditionally handles all incoming traffic. Defaults to <option>no</option>. For performance
-        reasons, it is recommended to write new daemons only in a way that is suitable for
-        <option>Accept=no</option>. A daemon listening on an <constant>AF_UNIX</constant> socket may, but
-        does not need to, call
+        unconditionally handles all incoming traffic. Defaults to <option>no</option>.</para>
+
+        <para>Typically, for performance sensitive services, a choice of <option>Accept=no</option> is
+        preferable, since that way only the first connection will have to pay the activation resource
+        cost. On the other hand, for sporadically used services <option>Accept=yes</option> can be preferable
+        as it simplifies the implementation (as the service program code only has to process a single
+        connection instead of handling multiple) and enables stronger security (since the various sandboxing
+        options can be used to isolate parallel connections from each other, as each is serviced by a
+        separate service instance and process).</para>
+
+        <para>A service listening on an <constant>AF_UNIX</constant> socket may, but does not need to, call
         <citerefentry><refentrytitle>close</refentrytitle><manvolnum>2</manvolnum></citerefentry> on the
         received socket before exiting. However, it must not unlink the socket from a file system. It should
         not invoke
         <citerefentry><refentrytitle>shutdown</refentrytitle><manvolnum>2</manvolnum></citerefentry> on
         sockets it got with <varname>Accept=no</varname>, but it may do so for sockets it got with
-        <varname>Accept=yes</varname> set. Setting <varname>Accept=yes</varname> is mostly useful to allow
-        daemons designed for usage with <citerefentry
+        <varname>Accept=yes</varname> set.</para>
+
+        <para>Setting <varname>Accept=yes</varname> is in particular useful for allowing daemons designed for
+        usage with <citerefentry
         project='freebsd'><refentrytitle>inetd</refentrytitle><manvolnum>8</manvolnum></citerefentry> to work
         unmodified with systemd socket activation.</para>
 
@@ -435,8 +444,9 @@
         (<literal>@</literal>). If the socket is unnamed, <varname>$REMOTE_ADDR</varname> will not be
         set.</para>
 
-        <para>The <varname>$SO_COOKIE</varname> environment variable is set to the Linux socket cookie,
-        formatted as decimal integer. The socket cookie can otherwise be acquired via <citerefentry
+        <para>If <varname>Accept=yes</varname> is used, the activated service process will have set the
+        <varname>$SO_COOKIE</varname> environment variable to the Linux socket cookie, formatted as decimal
+        integer. The socket cookie can otherwise be acquired via <citerefentry
         project='man-pages'><refentrytitle>getsockopt</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
 
         <para>It is recommended to set <varname>CollectMode=inactive-or-failed</varname> for service