-<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+<?xml version='1.0'?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
-
-<!--
- SPDX-License-Identifier: LGPL-2.1+
-
- This file is part of systemd.
-
- Copyright 2010 Lennart Poettering
--->
+<!-- SPDX-License-Identifier: LGPL-2.1+ -->
<refentry id="systemd.socket">
<refentryinfo>
<title>systemd.socket</title>
<productname>systemd</productname>
-
- <authorgroup>
- <author>
- <contrib>Developer</contrib>
- <firstname>Lennart</firstname>
- <surname>Poettering</surname>
- <email>lennart@poettering.net</email>
- </author>
- </authorgroup>
</refentryinfo>
<refmeta>
which configure resource control settings for the processes of the
socket.</para>
- <para>For each socket file, a matching service file must exist,
+ <para>For each socket unit, a matching service unit must exist,
describing the service to start on incoming traffic on the socket
(see
<citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
- for more information about .service files). The name of the
+ for more information about .service units). The name of the
.service unit is by default the same as the name of the .socket
unit, but can be altered with the <option>Service=</option> option
described below. Depending on the setting of the
or it must be a template unit named the same way. Example: a
socket file <filename>foo.socket</filename> needs a matching
service <filename>foo.service</filename> if
- <option>Accept=false</option> is set. If
- <option>Accept=true</option> is set, a service template file
+ <option>Accept=no</option> is set. If
+ <option>Accept=yes</option> is set, a service template
<filename>foo@.service</filename> must exist from which services
are instantiated for each incoming connection.</para>
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
+ project='man-pages'><refentrytitle>network_namespaces</refentrytitle><manvolnum>7</manvolnum></citerefentry>). This
+ does not mean however that the service activated by a configured socket unit has to be part of the host's network
+ namespace as well. It is supported and even good practice to run services in their own network namespace (for
+ example through <varname>PrivateNetwork=</varname>, see
+ <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>), receiving only
+ the sockets configured through socket-activation from the host's namespace. In such a set-up communication within
+ the host's network namespace is only permitted through the activation sockets passed in while all sockets allocated
+ from the service code itself will be associated with the service's own namespace, and thus possibly subject to a a
+ much more restrictive configuration.</para>
</refsect1>
<refsect1>
<listitem><para>Socket units automatically gain a <varname>Before=</varname>
dependency on the service units they activate.</para></listitem>
- <listitem><para>Socket units referring to file system paths (such as AF_UNIX
- sockets or FIFOs) implicitly gain <varname>Requires=</varname> and
- <varname>After=</varname> dependencies on all mount units
- necessary to access those paths.</para></listitem>
+ <listitem><para>Socket units referring to file system paths (such as <constant>AF_UNIX</constant>
+ sockets or FIFOs) implicitly gain <varname>Requires=</varname> and <varname>After=</varname>
+ dependencies on all mount units necessary to access those paths.</para></listitem>
<listitem><para>Socket units using the <varname>BindToDevice=</varname>
setting automatically gain a <varname>BindsTo=</varname> and
url="https://www.kernel.org/doc/Documentation/usb/functionfs.txt">USB
FunctionFS</ulink> endpoints location to listen on, for
implementation of USB gadget functions. This expects an
- absolute file system path of functionfs mount point as the argument.
+ absolute file system path of FunctionFS mount point as the argument.
Behavior otherwise is very similar to the <varname>ListenFIFO=</varname>
directive above. Use this to open the FunctionFS endpoint
<filename>ep0</filename>. When using this option, the
<varlistentry>
<term><varname>SocketProtocol=</varname></term>
- <listitem><para>Takes a one of <option>udplite</option>
- or <option>sctp</option>. Specifies a socket protocol
- (<constant>IPPROTO_UDPLITE</constant>) UDP-Lite
- (<constant>IPPROTO_SCTP</constant>) SCTP socket respectively. </para>
+ <listitem><para>Takes one of <option>udplite</option>
+ or <option>sctp</option>. The socket will use the UDP-Lite
+ (<constant>IPPROTO_UDPLITE</constant>) or SCTP
+ (<constant>IPPROTO_SCTP</constant>) protocol, respectively.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>BindIPv6Only=</varname></term>
- <listitem><para>Takes a one of <option>default</option>,
+ <listitem><para>Takes one of <option>default</option>,
<option>both</option> or <option>ipv6-only</option>. Controls
the IPV6_V6ONLY socket option (see
<citerefentry project='die-net'><refentrytitle>ipv6</refentrytitle><manvolnum>7</manvolnum></citerefentry>
<varlistentry>
<term><varname>BindToDevice=</varname></term>
- <listitem><para>Specifies a network interface name to bind
- this socket to. If set, traffic will only be accepted from the
- specified network interfaces. This controls the
- SO_BINDTODEVICE socket option (see <citerefentry
- project='man-pages'><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>
- for details). If this option is used, an implicit dependency
- from this socket unit on the network interface device unit
- (<citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>
- is created. Note that setting this parameter might result in
- additional dependencies to be added to the unit (see
+ <listitem><para>Specifies a network interface name to bind this socket to. If set, traffic will only
+ be accepted from the specified network interfaces. This controls the
+ <constant>SO_BINDTODEVICE</constant> socket option (see <citerefentry
+ project='man-pages'><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
+ details). If this option is used, an implicit dependency from this socket unit on the network
+ interface device unit is created
+ (see <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
+ Note that setting this parameter might result in additional dependencies to be added to the unit (see
above).</para></listitem>
</varlistentry>
<term><varname>SocketUser=</varname></term>
<term><varname>SocketGroup=</varname></term>
- <listitem><para>Takes a UNIX user/group name. When specified,
- all AF_UNIX sockets and FIFO nodes in the file system are
- owned by the specified user and group. If unset (the default),
- the nodes are owned by the root user/group (if run in system
- context) or the invoking user/group (if run in user context).
- If only a user is specified but no group, then the group is
+ <listitem><para>Takes a UNIX user/group name. When specified, all <constant>AF_UNIX</constant>
+ sockets and FIFO nodes in the file system are owned by the specified user and group. If unset (the
+ default), the nodes are owned by the root user/group (if run in system context) or the invoking
+ user/group (if run in user context). If only a user is specified but no group, then the group is
derived from the user's default group.</para></listitem>
</varlistentry>
incoming traffic. Defaults to <option>false</option>. For
performance reasons, it is recommended to write new daemons
only in a way that is suitable for
- <option>Accept=false</option>. A daemon listening on an
+ <option>Accept=no</option>. A daemon 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=false</varname>, but it
+ on sockets it got with <varname>Accept=no</varname>, but it
may do so for sockets it got with
- <varname>Accept=true</varname> set. Setting
- <varname>Accept=true</varname> is mostly useful to allow
+ <varname>Accept=yes</varname> set. Setting
+ <varname>Accept=yes</varname> is mostly useful to allow
daemons designed for usage with
<citerefentry project='freebsd'><refentrytitle>inetd</refentrytitle><manvolnum>8</manvolnum></citerefentry>
to work unmodified with systemd socket
activation.</para>
- <para>For IPv4 and IPv6 connections, the <varname>REMOTE_ADDR</varname>
- environment variable will contain the remote IP address, and <varname>REMOTE_PORT</varname>
- will contain the remote port. This is the same as the format used by CGI.
- For SOCK_RAW, the port is the IP protocol.</para></listitem>
+ <para>For IPv4 and IPv6 connections, the <varname>REMOTE_ADDR</varname> environment variable will
+ contain the remote IP address, and <varname>REMOTE_PORT</varname> will contain the remote port. This
+ is the same as the format used by CGI. For <constant>SOCK_RAW</constant>, the port is the IP
+ protocol.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>MaxConnections=</varname></term>
<listitem><para>The maximum number of connections to
simultaneously run services instances for, when
- <option>Accept=true</option> is set. If more concurrent
+ <option>Accept=yes</option> is set. If more concurrent
connections are coming in, they will be refused until at least
one existing connection is terminated. This setting has no
effect on sockets configured with
- <option>Accept=false</option> or datagram sockets. Defaults to
+ <option>Accept=no</option> or datagram sockets. Defaults to
64.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>KeepAlive=</varname></term>
- <listitem><para>Takes a boolean argument. If true, the TCP/IP
- stack will send a keep alive message after 2h (depending on
- the configuration of
- <filename>/proc/sys/net/ipv4/tcp_keepalive_time</filename>)
- for all TCP streams accepted on this socket. This controls the
- SO_KEEPALIVE socket option (see
- <citerefentry project='man-pages'><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>
- and the <ulink
- url="http://www.tldp.org/HOWTO/html_single/TCP-Keepalive-HOWTO/">TCP
- Keepalive HOWTO</ulink> for details.) Defaults to
- <option>false</option>.</para></listitem>
+ <listitem><para>Takes a boolean argument. If true, the TCP/IP stack will send a keep alive message
+ after 2h (depending on the configuration of
+ <filename>/proc/sys/net/ipv4/tcp_keepalive_time</filename>) for all TCP streams accepted on this
+ socket. This controls the <constant>SO_KEEPALIVE</constant> socket option (see <citerefentry
+ project='man-pages'><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry> and
+ the <ulink url="http://www.tldp.org/HOWTO/html_single/TCP-Keepalive-HOWTO/">TCP Keepalive
+ HOWTO</ulink> for details.) Defaults to <option>false</option>.</para></listitem>
</varlistentry>
<varlistentry>
<varlistentry>
<term><varname>KeepAliveIntervalSec=</varname></term>
- <listitem><para>Takes time (in seconds) as argument between
- individual keepalive probes, if the socket option SO_KEEPALIVE
- has been set on this socket. This controls
- the TCP_KEEPINTVL socket option (see
- <citerefentry project='man-pages'><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>
- and the <ulink
- url="http://www.tldp.org/HOWTO/html_single/TCP-Keepalive-HOWTO/">TCP
- Keepalive HOWTO</ulink> for details.) Defaults value is 75
- seconds.</para></listitem>
+ <listitem><para>Takes time (in seconds) as argument between individual keepalive probes, if the
+ socket option <constant>SO_KEEPALIVE</constant> has been set on this socket. This controls the
+ <constant>TCP_KEEPINTVL</constant> socket option (see <citerefentry
+ project='man-pages'><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry> and
+ the <ulink url="http://www.tldp.org/HOWTO/html_single/TCP-Keepalive-HOWTO/">TCP Keepalive
+ HOWTO</ulink> for details.) Defaults value is 75 seconds.</para></listitem>
</varlistentry>
<varlistentry>
algorithm works by combining a number of small outgoing
messages, and sending them all at once. This controls the
TCP_NODELAY socket option (see
- <citerefentry project='die-net'><refentrytitle>tcp</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+ <citerefentry project='die-net'><refentrytitle>tcp</refentrytitle><manvolnum>7</manvolnum></citerefentry>).
Defaults to <option>false</option>.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>Priority=</varname></term>
- <listitem><para>Takes an integer argument controlling the
- priority for all traffic sent from this socket. This controls
- the SO_PRIORITY socket option (see
- <citerefentry project='man-pages'><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>
- for details.).</para></listitem>
+ <listitem><para>Takes an integer argument controlling the priority for all traffic sent from this
+ socket. This controls the <constant>SO_PRIORITY</constant> socket option (see <citerefentry
+ project='man-pages'><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
+ details.).</para></listitem>
</varlistentry>
<varlistentry>
<varlistentry>
<term><varname>ReceiveBuffer=</varname></term>
<term><varname>SendBuffer=</varname></term>
- <listitem><para>Takes an integer argument controlling the
- receive or send buffer sizes of this socket, respectively.
- This controls the SO_RCVBUF and SO_SNDBUF socket options (see
- <citerefentry project='man-pages'><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>
- for details.). The usual suffixes K, M, G are supported and
- are understood to the base of 1024.</para></listitem>
+ <listitem><para>Takes an integer argument controlling the receive or send buffer sizes of this
+ socket, respectively. This controls the <constant>SO_RCVBUF</constant> and
+ <constant>SO_SNDBUF</constant> socket options (see <citerefentry
+ project='man-pages'><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
+ details.). The usual suffixes K, M, G are supported and are understood to the base of
+ 1024.</para></listitem>
</varlistentry>
<varlistentry>
<varlistentry>
<term><varname>Mark=</varname></term>
- <listitem><para>Takes an integer value. Controls the firewall
- mark of packets generated by this socket. This can be used in
- the firewall logic to filter packets from this socket. This
- sets the SO_MARK socket option. See
- <citerefentry project='die-net'><refentrytitle>iptables</refentrytitle><manvolnum>8</manvolnum></citerefentry>
- for details.</para></listitem>
+ <listitem><para>Takes an integer value. Controls the firewall mark of packets generated by this
+ socket. This can be used in the firewall logic to filter packets from this socket. This sets the
+ <constant>SO_MARK</constant> socket option. See <citerefentry
+ project='die-net'><refentrytitle>iptables</refentrytitle><manvolnum>8</manvolnum></citerefentry> for
+ details.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>ReusePort=</varname></term>
- <listitem><para>Takes a boolean value. If true, allows
- multiple
- <citerefentry><refentrytitle>bind</refentrytitle><manvolnum>2</manvolnum></citerefentry>s
- to this TCP or UDP port. This controls the SO_REUSEPORT socket
- option. See
- <citerefentry project='man-pages'><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>
- for details.</para></listitem>
+ <listitem><para>Takes a boolean value. If true, allows multiple
+ <citerefentry><refentrytitle>bind</refentrytitle><manvolnum>2</manvolnum></citerefentry>s to this TCP
+ or UDP port. This controls the <constant>SO_REUSEPORT</constant> socket option. See <citerefentry
+ project='man-pages'><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
+ details.</para></listitem>
</varlistentry>
<varlistentry>
<varlistentry>
<term><varname>Broadcast=</varname></term>
- <listitem><para>Takes a boolean value. This controls the
- SO_BROADCAST socket option, which allows broadcast datagrams
- to be sent from this socket. Defaults to
+ <listitem><para>Takes a boolean value. This controls the <constant>SO_BROADCAST</constant> socket
+ option, which allows broadcast datagrams to be sent from this socket. Defaults to
<option>false</option>.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>PassCredentials=</varname></term>
- <listitem><para>Takes a boolean value. This controls the
- SO_PASSCRED socket option, which allows
- <constant>AF_UNIX</constant> sockets to receive the
- credentials of the sending process in an ancillary message.
- Defaults to <option>false</option>.</para></listitem>
+ <listitem><para>Takes a boolean value. This controls the <constant>SO_PASSCRED</constant> socket
+ option, which allows <constant>AF_UNIX</constant> sockets to receive the credentials of the sending
+ process in an ancillary message. Defaults to <option>false</option>.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>PassSecurity=</varname></term>
- <listitem><para>Takes a boolean value. This controls the
- SO_PASSSEC socket option, which allows
- <constant>AF_UNIX</constant> sockets to receive the security
- context of the sending process in an ancillary message.
+ <listitem><para>Takes a boolean value. This controls the <constant>SO_PASSSEC</constant> socket
+ option, which allows <constant>AF_UNIX</constant> sockets to receive the security context of the
+ sending process in an ancillary message. Defaults to <option>false</option>.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>PassPacketInfo=</varname></term>
+ <listitem><para>Takes a boolean value. This controls the <constant>IP_PKTINFO</constant>,
+ <constant>IPV6_RECVPKTINFO</constant> and <constant>NETLINK_PKTINFO</constant> socket options, which
+ enable reception of additional per-packet metadata as ancillary message, on
+ <constant>AF_INET</constant>, <constant>AF_INET6</constant> and <constant>AF_UNIX</constant> sockets.
Defaults to <option>false</option>.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>TCPCongestion=</varname></term>
- <listitem><para>Takes a string value. Controls the TCP
- congestion algorithm used by this socket. Should be one of
- "westwood", "veno", "cubic", "lp" or any other available
- algorithm supported by the IP stack. This setting applies only
- to stream sockets.</para></listitem>
+ <listitem><para>Takes a string value. Controls the TCP congestion algorithm used by this
+ socket. Should be one of <literal>westwood</literal>, <literal>veno</literal>,
+ <literal>cubic</literal>, <literal>lp</literal> or any other available algorithm supported by the IP
+ stack. This setting applies only to stream sockets.</para></listitem>
</varlistentry>
<varlistentry>
<varlistentry>
<term><varname>RemoveOnStop=</varname></term>
- <listitem><para>Takes a boolean argument. If enabled, any file
- nodes created by this socket unit are removed when it is
- stopped. This applies to AF_UNIX sockets in the file system,
- POSIX message queues, FIFOs, as well as any symlinks to them
- configured with <varname>Symlinks=</varname>. Normally, it
- should not be necessary to use this option, and is not
- recommended as services might continue to run after the socket
- unit has been terminated and it should still be possible to
- communicate with them via their file system node. Defaults to
+ <listitem><para>Takes a boolean argument. If enabled, any file nodes created by this socket unit are
+ removed when it is stopped. This applies to <constant>AF_UNIX</constant> sockets in the file system,
+ POSIX message queues, FIFOs, as well as any symlinks to them configured with
+ <varname>Symlinks=</varname>. Normally, it should not be necessary to use this option, and is not
+ recommended as services might continue to run after the socket unit has been terminated and it should
+ still be possible to communicate with them via their file system node. Defaults to
off.</para></listitem>
</varlistentry>
<para>
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
projects / thirdparty / systemd.git / blobdiff