-<?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">
-
-<!--
- This file is part of systemd.
-
- Copyright 2010 Lennart Poettering
-
- systemd is free software; you can redistribute it and/or modify it
- under the terms of the GNU Lesser General Public License as published by
- the Free Software Foundation; either version 2.1 of the License, or
- (at your option) any later version.
-
- systemd is distributed in the hope that it will be useful, but
- WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
- Lesser General Public License for more details.
-
- You should have received a copy of the GNU Lesser General Public License
- along with systemd; If not, see <http://www.gnu.org/licenses/>.
--->
+<!-- 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>
this unit type. See
<citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
for the common options of all unit configuration files. The common
- configuration items are configured in the generic [Unit] and
- [Install] sections. The socket specific configuration options are
- configured in the [Socket] section.</para>
+ configuration items are configured in the generic <literal>[Unit]</literal> and
+ <literal>[Install]</literal> sections. The socket specific configuration options are
+ configured in the <literal>[Socket]</literal> section.</para>
<para>Additional options are listed in
<citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
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>
- <para>Unless <varname>DefaultDependencies=</varname> in the <literal>[Unit]</literal> section is set to
- <option>false</option>, socket units will implicitly have dependencies of type <varname>Requires=</varname> and
- <varname>After=</varname> on <filename>sysinit.target</filename> as well as dependencies of type
- <varname>Conflicts=</varname> and <varname>Before=</varname> on <filename>shutdown.target</filename>. These ensure
- that socket units pull in basic system initialization, and are terminated cleanly prior to system shutdown. Only
- sockets involved with early boot or late system shutdown should disable this option.</para>
-
- <para>Socket units will have a <varname>Before=</varname>
- dependency on the service which they trigger added implicitly. No
- implicit <varname>WantedBy=</varname> or
+ <para>No implicit <varname>WantedBy=</varname> or
<varname>RequiredBy=</varname> dependency from the socket to the
service is added. This means that the service may be started
without the socket, in which case it must be able to open sockets
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>
<title>Automatic Dependencies</title>
- <para>Socket units automatically gain a <varname>Before=</varname>
- dependency on the service units they activate.</para>
-
- <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>
-
- <para>Socket units using the <varname>BindToDevice=</varname>
- setting automatically gain a <varname>BindsTo=</varname> and
- <varname>After=</varname> dependency on the device unit
- encapsulating the specified network interface.</para>
-
- <para>If <varname>DefaultDependencies=yes</varname> is set (the
- default), socket units automatically gain a
- <varname>Before=</varname> dependency on
- <filename>sockets.target</filename>. They also gain a pair of
- <varname>After=</varname> and <varname>Requires=</varname>
- dependency on <filename>sysinit.target</filename>, and a pair of
- <varname>Before=</varname> and <varname>Conflicts=</varname>
- dependencies on <filename>shutdown.target</filename>. These
- dependencies ensure that the socket unit is started before normal
- services at boot, and is stopped on shutdown.</para>
-
- <para>Additional implicit dependencies may be added as result of
- execution and resource control parameters as documented in
- <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
- and
- <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
+ <refsect2>
+ <title>Implicit Dependencies</title>
+
+ <para>The following dependencies are implicitly added:</para>
+
+ <itemizedlist>
+ <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 using the <varname>BindToDevice=</varname>
+ setting automatically gain a <varname>BindsTo=</varname> and
+ <varname>After=</varname> dependency on the device unit
+ encapsulating the specified network interface.</para></listitem>
+ </itemizedlist>
+
+ <para>Additional implicit dependencies may be added as result of
+ execution and resource control parameters as documented in
+ <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ and
+ <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
+ </refsect2>
+
+ <refsect2>
+ <title>Default Dependencies</title>
+
+ <para>The following dependencies are added unless
+ <varname>DefaultDependencies=no</varname> is set:</para>
+
+ <itemizedlist>
+ <listitem><para>Socket units automatically gain a
+ <varname>Before=</varname> dependency on
+ <filename>sockets.target</filename>.</para></listitem>
+
+ <listitem><para>Socket units automatically gain a pair of
+ <varname>After=</varname> and <varname>Requires=</varname>
+ dependency on <filename>sysinit.target</filename>, and a pair of
+ <varname>Before=</varname> and <varname>Conflicts=</varname>
+ dependencies on <filename>shutdown.target</filename>. These
+ dependencies ensure that the socket unit is started before normal
+ services at boot, and is stopped on shutdown. Only sockets
+ involved with early boot or late system shutdown should disable
+ <varname>DefaultDependencies=</varname> option.</para></listitem>
+ </itemizedlist>
+ </refsect2>
</refsect1>
<refsect1>
<varlistentry>
<term><varname>SocketProtocol=</varname></term>
- <listitem><para>Takes a one of <option>udplite</option>
+ <listitem><para>Takes 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>
<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>
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 automatic dependency
+ 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
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
<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>Symlinks=</varname></term>
- <listitem><para>Takes a list of file system paths. The
- specified paths will be created as symlinks to the AF_UNIX
- socket path or FIFO path of this socket unit. If this setting
- is used, only one AF_UNIX socket in the file system or one
- FIFO may be configured for the socket unit. Use this option to
- manage one or more symlinked alias names for a socket, binding
- their lifecycle together. If the empty string is assigned, the
- list of paths is reset. Defaults to the empty list.</para></listitem>
+ <listitem><para>Takes a list of file system paths. The specified paths will be created as symlinks to the
+ <constant>AF_UNIX</constant> socket path or FIFO path of this socket unit. If this setting is used, only one
+ <constant>AF_UNIX</constant> socket in the file system or one FIFO may be configured for the socket unit. Use
+ this option to manage one or more symlinked alias names for a socket, binding their lifecycle together. Note
+ that if creation of a symlink fails this is not considered fatal for the socket unit, and the socket unit may
+ still start. If an empty string is assigned, the list of paths is reset. Defaults to an empty
+ list.</para></listitem>
</varlistentry>
<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