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/>.
-->
<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>
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
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. Behaviour
+ 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. Behaviour 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 /). Behaviour
+ 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
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 resp. mq_msgsize field 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
+ 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>
+ </varlistentry>
+
<varlistentry>
<term><varname>ExecStartPre=</varname></term>
<term><varname>ExecStartPost=</varname></term>
- <listitem><para>Takes a command line,
- which is executed before (resp. after)
- the listening sockets/FIFOs are created and
+ <listitem><para>Takes one or more
+ command lines, which are executed
+ before (resp. after) the listening
+ sockets/FIFOs are created and
bound. The first token of the command
line must be an absolute file name,
then followed by arguments for the
- process. If specified more than once,
- all commands are executed one after
- the other, fully serialized. The use of
- these settings is optional.</para></listitem>
+ process. Multiple command lines may be
+ specified following the same scheme as
+ used for
+ <varname>ExecStartPre=</varname> of
+ service unit files.</para></listitem>
</varlistentry>
<varlistentry>
<listitem><para>Additional commands
that are executed before (resp. after)
the listening sockets/FIFOs are closed
- and removed. If specified more than
- once, all commands are executed one
- after the other, fully serialized. The use of
- these settings is optional.</para></listitem>
+ and removed. Multiple command lines
+ may be specified following the same
+ scheme as used for
+ <varname>ExecStartPre=</varname> of
+ service unit files.</para></listitem>
</varlistentry>
<varlistentry>
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>
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>
<citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
for details.</para></listitem>
</varlistentry>
+
+ <varlistentry>
+ <term><varname>KillSignal=</varname></term>
+ <listitem><para>Specifies which signal
+ to use when killing a process of this
+ socket. Defaults to SIGTERM.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>SendSIGKILL=</varname></term>
+ <listitem><para>Specifies whether to
+ send SIGKILL to remaining processes
+ after a timeout, if the normal
+ shutdown procedure left processes of
+ the socket around. Takes a boolean
+ value. Defaults to "yes".
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <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>
</refsect1>