picnoir
/
Systemd
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

doc: cross link sd_listen_fd() docs a bit 

Let's make sure the sd_listen_fd() docs are really found from the
.socket file documentation as well as the FileDescriptorStoreMax=
documentation.

Let's also emphasize that that's where the order in which the fds are
passed are documented.

Fixes: #16647
This commit is contained in:
Lennart Poettering 2020-08-31 23:41:30 +02:00 committed by Zbigniew Jędrzejewski-Szmek
parent 0419dae715
commit df2f58176d
3 changed files with 35 additions and 38 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

25
man/sd_listen_fds.xml
View File

@ -54,24 +54,19 @@
(i.e. <constant>SD_LISTEN_FDS_START</constant>), the remaining
descriptors follow at 4, 5, 6, …, if any.</para>
<para>If a daemon receives more than one file descriptor, they
will be passed in the same order as configured in the systemd
socket unit file (see
<citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>
for details). Nonetheless, it is recommended to verify the correct
socket types before using them. To simplify this checking, the
functions
<para>If a daemon receives more than one file descriptor, they will be passed in the same order as
configured in the systemd socket unit file (see
<citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
details) — if there's only one such file (see below). Nonetheless, it is recommended to verify the
correct socket types before using them. To simplify this checking, the functions
<citerefentry><refentrytitle>sd_is_fifo</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_is_socket</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_is_socket_inet</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_is_socket_unix</refentrytitle><manvolnum>3</manvolnum></citerefentry>
are provided. In order to maximize flexibility, it is recommended
to make these checks as loose as possible without allowing
incorrect setups. i.e. often, the actual port number a socket is
bound to matters little for the service to work, hence it should
not be verified. On the other hand, whether a socket is a datagram
or stream socket matters a lot for the most common program logics
and should be checked.</para>
<citerefentry><refentrytitle>sd_is_socket_unix</refentrytitle><manvolnum>3</manvolnum></citerefentry> are
provided. In order to maximize flexibility, it is recommended to make these checks as loose as possible
without allowing incorrect setups. i.e. often, the actual port number a socket is bound to matters little
for the service to work, hence it should not be verified. On the other hand, whether a socket is a
datagram or stream socket matters a lot for the most common program logics and should be checked.</para>
<para>This function call will set the FD_CLOEXEC flag for all
passed file descriptors to avoid further inheritance to children

30
man/systemd.service.xml
View File

@ -1028,20 +1028,24 @@
<varlistentry>
<term><varname>FileDescriptorStoreMax=</varname></term>
<listitem><para>Configure how many file descriptors may be stored in the service manager for the service using
<listitem><para>Configure how many file descriptors may be stored in the service manager for the
service using
<citerefentry><refentrytitle>sd_pid_notify_with_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>'s
<literal>FDSTORE=1</literal> messages. This is useful for implementing services that can restart after an
explicit request or a crash without losing state. Any open sockets and other file descriptors which should not
be closed during the restart may be stored this way. Application state can either be serialized to a file in
<filename>/run</filename>, or better, stored in a
<citerefentry><refentrytitle>memfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry> memory file
descriptor. Defaults to 0, i.e. no file descriptors may be stored in the service manager. All file descriptors
passed to the service manager from a specific service are passed back to the service's main process on the next
service restart. Any file descriptors passed to the service manager are automatically closed when
<constant>POLLHUP</constant> or <constant>POLLERR</constant> is seen on them, or when the service is fully
stopped and no job is queued or being executed for it. If this option is used, <varname>NotifyAccess=</varname>
(see above) should be set to open access to the notification socket provided by systemd. If
<varname>NotifyAccess=</varname> is not set, it will be implicitly set to
<literal>FDSTORE=1</literal> messages. This is useful for implementing services that can restart
after an explicit request or a crash without losing state. Any open sockets and other file
descriptors which should not be closed during the restart may be stored this way. Application state
can either be serialized to a file in <filename>/run</filename>, or better, stored in a
<citerefentry><refentrytitle>memfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry>
memory file descriptor. Defaults to 0, i.e. no file descriptors may be stored in the service
manager. All file descriptors passed to the service manager from a specific service are passed back
to the service's main process on the next service restart (see
<citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry> for
details about the precise protocol used and the order in which the file descriptors are passed). Any
file descriptors passed to the service manager are automatically closed when
<constant>POLLHUP</constant> or <constant>POLLERR</constant> is seen on them, or when the service is
fully stopped and no job is queued or being executed for it. If this option is used,
<varname>NotifyAccess=</varname> (see above) should be set to open access to the notification socket
provided by systemd. If <varname>NotifyAccess=</varname> is not set, it will be implicitly set to
<option>main</option>.</para></listitem>
</varlistentry>

18
man/systemd.socket.xml
View File

@ -81,16 +81,14 @@
services, as well as parallelized starting of services. See the
blog stories linked at the end for an introduction.</para>
<para>Note that the daemon software configured for socket
activation with socket units needs to be able to accept sockets
from systemd, either via systemd's native socket passing interface
(see
<citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>
for details) or via the traditional
<citerefentry project='freebsd'><refentrytitle>inetd</refentrytitle><manvolnum>8</manvolnum></citerefentry>-style
socket passing (i.e. sockets passed in via standard input and
output, using <varname>StandardInput=socket</varname> in the
service file).</para>
<para>Note that the daemon software configured for socket activation with socket units needs to be able
to accept sockets from systemd, either via systemd's native socket passing interface (see
<citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry> for
details about the precise protocol used and the order in which the file descriptors are passed) or via
traditional <citerefentry
project='freebsd'><refentrytitle>inetd</refentrytitle><manvolnum>8</manvolnum></citerefentry>-style
socket passing (i.e. sockets passed in via standard input and output, using
<varname>StandardInput=socket</varname> in the service file).</para>
<para>All network sockets allocated through <filename>.socket</filename> units are allocated in the host's network
namespace (see <citerefentry