Copyright 2010 Lennart Poettering
systemd is free software; you can redistribute it and/or modify it
- under the terms of the GNU General Public License as published by
- the Free Software Foundation; either version 2 of the License, or
+ 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
- General Public License for more details.
+ Lesser General Public License for more details.
- You should have received a copy of the GNU General Public License
+ You should have received a copy of the GNU Lesser General Public License
along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->
<refnamediv>
<refname>systemd.socket</refname>
- <refpurpose>systemd socket configuration files</refpurpose>
+ <refpurpose>Socket unit configuration</refpurpose>
</refnamediv>
<refsynopsisdiv>
<option>ExecStartPost=</option>,
<option>ExecStopPre=</option> and
<option>ExecStoptPost=</option> commands are executed
- in.</para>
+ in, and in
+ <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ which define the way the processes are
+ terminated.</para>
<para>For each socket file a matching service file
(see
<para>Socket units may be used to implement on-demand
starting of services, as well as parallelized starting
of services.</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><refentrytitle>inetd</refentrytitle><manvolnum>8</manvolnum></citerefentry>-style
+ socket passing (i.e. sockets passed in via STDIN and
+ STDOUT, using <varname>StandardInput=socket</varname>
+ in the service file).</para>
</refsect1>
<refsect1>
supervises. A number of options that may be used in
this section are shared with other unit types. These
options are documented in
- <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>. The
+ <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ and
+ <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>. The
options specific to the [Socket] section of socket
units are the following:</para>
<term><varname>ListenSequentialPacket=</varname></term>
<listitem><para>Specifies an address
to listen on for a stream
- (SOCK_STREAM), datagram (SOCK_DGRAM)
- resp. sequential packet
- (SOCK_SEQPACKET) socket. The address
+ (SOCK_STREAM), datagram (SOCK_DGRAM),
+ or sequential packet
+ (SOCK_SEQPACKET) socket, respectively. The address
can be written in various formats:</para>
<para>If the address starts with a
family.</para>
<para>If the address starts with an
- ampersand (@) it is read as abstract
+ at symbol (@) it is read as abstract
namespace socket in the AF_UNIX
family. The @ is replaced with a NUL
character before binding. For details
<para>If the address string is a
single number it is read as port
- number to listen on for both IPv4 and
- IPv6.</para>
+ number to listen on via
+ IPv6. Depending on the value of
+ <varname>BindIPv6Only=</varname> (see below) this
+ might result in the service being
+ available via both IPv6 and IPv4 (default) or
+ just via IPv6.
+ </para>
<para>If the address string is a
string in the format v.w.x.y:z it is
<para>If the address string is a
string in the format [x]:y it is read
- as IPv6 address x on a port y.</para>
+ as IPv6 address x on a port y. Note
+ that this might make the service
+ available via IPv4, too, depending on
+ the <varname>BindIPv6Only=</varname>
+ setting (see below).
+ </para>
<para>Note that SOCK_SEQPACKET
(i.e. <varname>ListenSequentialPacket=</varname>)
<listitem><para>Specifies a file
system FIFO to listen on. This expects
an absolute file system path as
- argument. Behaviour otherwise is very
+ argument. Behavior otherwise is very
similar to the
<varname>ListenDatagram=</varname>
directive above.</para></listitem>
</varlistentry>
+ <varlistentry>
+ <term><varname>ListenSpecial=</varname></term>
+ <listitem><para>Specifies a special
+ file in the file system to listen
+ on. This expects an absolute file
+ system path as argument. Behavior
+ otherwise is very similar to the
+ <varname>ListenFIFO=</varname>
+ directive above. Use this to open
+ character device nodes as well as
+ special files in
+ <filename>/proc</filename> and
+ <filename>/sys</filename>.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>ListenNetlink=</varname></term>
+ <listitem><para>Specifies a Netlink
+ family to create a socket for to
+ listen on. This expects a short string
+ referring to the AF_NETLINK family
+ name (such as <varname>audit</varname>
+ or <varname>kobject-uevent</varname>)
+ as argument, optionally suffixed by a
+ whitespace followed by a multicast
+ group integer. Behavior otherwise is
+ very similar to the
+ <varname>ListenDatagram=</varname>
+ directive above.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>ListenMessageQueue=</varname></term>
+ <listitem><para>Specifies a POSIX
+ message queue name to listen on. This
+ expects a valid message queue name
+ (i.e. beginning with /). Behavior
+ otherwise is very similar to the
+ <varname>ListenFIFO=</varname>
+ directive above. On Linux message
+ queue descriptors are actually file
+ descriptors and can be inherited
+ between processes.</para></listitem>
+ </varlistentry>
+
<varlistentry>
<term><varname>BindIPv6Only=</varname></term>
<listitem><para>Takes a one of
default, surprise!) the system wide
default setting is used, as controlled
by
- <filename>/proc/sys/net/ipv6/bindv6only</filename>.</para>
+ <filename>/proc/sys/net/ipv6/bindv6only</filename>,
+ which in turn defaults to the
+ equivalent of
+ <option>both</option>.</para>
</listitem>
</varlistentry>
<term><varname>SendBuffer=</varname></term>
<listitem><para>Takes an integer
argument controlling the receive
- resp. send buffer sizes of this
- socket. This controls the SO_RCVBUF
- resp. SO_SNDBUF socket options (see
+ or send buffer sizes of this
+ socket, respectively. This controls the SO_RCVBUF
+ and SO_SNDBUF socket options (see
<citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>
for details.).</para></listitem>
</varlistentry>
for details.</para></listitem>
</varlistentry>
+ <varlistentry>
+ <term><varname>SmackLabel=</varname></term>
+ <term><varname>SmackLabelIPIn=</varname></term>
+ <term><varname>SmackLabelIPOut=</varname></term>
+ <listitem><para>Takes a string
+ value. Controls the extended
+ attributes
+ <literal>security.SMACK64</literal>,
+ <literal>security.SMACK64IPIN</literal>
+ and
+ <literal>security.SMACK64IPOUT</literal>,
+ respectively, i.e. the security label
+ of the FIFO, or the security label for
+ the incoming or outgoing connections
+ of the socket, respectively. See
+ <ulink
+ url="https://www.kernel.org/doc/Documentation/security/Smack.txt">Smack.txt</ulink>
+ for details.</para></listitem>
+ </varlistentry>
+
<varlistentry>
<term><varname>PipeSize=</varname></term>
<listitem><para>Takes an integer
for details.</para></listitem>
</varlistentry>
+ <varlistentry>
+ <term><varname>MessageQueueMaxMessages=</varname>,
+ <varname>MessageQueueMessageSize=</varname></term>
+ <listitem><para>These two settings
+ take integer values and control the
+ mq_maxmsg field or the mq_msgsize field, respectively, when
+ creating the message queue. Note that
+ either none or both of these variables
+ need to be set. See
+ <citerefentry><refentrytitle>mq_setattr</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ for details.</para></listitem>
+ </varlistentry>
+
<varlistentry>
<term><varname>FreeBind=</varname></term>
<listitem><para>Takes a boolean
address. Defaults to <option>false</option>.</para></listitem>
</varlistentry>
+ <varlistentry>
+ <term><varname>Transparent=</varname></term>
+ <listitem><para>Takes a boolean
+ value. Controls the IP_TRANSPARENT
+ socket option. Defaults to
+ <option>false</option>.</para></listitem>
+ </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
+ <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 AF_UNIX 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 AF_UNIX
+ 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>TCPCongestion=</varname></term>
<listitem><para>Takes a string
<term><varname>ExecStartPost=</varname></term>
<listitem><para>Takes one or more
command lines, which are executed
- before (resp. after) the listening
+ before or after the listening
sockets/FIFOs are created and
- bound. The first token of the command
+ bound, respectively. The first token of the command
line must be an absolute file name,
then followed by arguments for the
process. Multiple command lines may be
<term><varname>ExecStopPre=</varname></term>
<term><varname>ExecStopPost=</varname></term>
<listitem><para>Additional commands
- that are executed before (resp. after)
+ that are executed before or after
the listening sockets/FIFOs are closed
- and removed. Multiple command lines
+ and removed, respectively. Multiple command lines
may be specified following the same
scheme as used for
<varname>ExecStartPre=</varname> of
will be terminated forcibly via
SIGTERM, and after another delay of
this time with SIGKILL. (See
- <option>KillMode=</option> below.)
+ <option>KillMode=</option> in <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>.)
Takes a unit-less value in seconds, or
a time span value such as "5min
20s". Pass 0 to disable the timeout
logic. Defaults to
- 60s.</para></listitem>
+ 90s.</para></listitem>
</varlistentry>
<varlistentry>
- <term><varname>KillMode=</varname></term>
- <listitem><para>Specifies how
- processes of this socket unit shall be
- killed. One of
- <option>control-group</option>,
- <option>process-group</option>,
- <option>process</option>,
- <option>none</option>.</para>
-
- <para>This option is mostly equivalent
- to the <option>KillMode=</option>
- option of service files. See
- <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
- for details.</para></listitem>
+ <term><varname>Service=</varname></term>
+ <listitem><para>Specifies the service
+ unit name to activate on incoming
+ traffic. This defaults to the service
+ that bears the same name as the socket
+ (ignoring the different suffixes). In
+ most cases it should not be necessary
+ to use this option.</para></listitem>
</varlistentry>
+
</variablelist>
+
+ <para>Check
+ <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ and
+ <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ for more settings.</para>
+
</refsect1>
<refsect1>
<citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>8</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>,
<citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
</para>
</refsect1>
~ianmdlvl / elogind.git / blobdiff