<?xml version='1.0'?> <!--*-nxml-*-->

<?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?>

<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"

"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<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>

<refentrytitle>systemd.socket</refentrytitle>

<manvolnum>5</manvolnum>

</refmeta>

<refnamediv>

<refname>systemd.socket</refname>

<refpurpose>Socket unit configuration</refpurpose>

</refnamediv>

<refsynopsisdiv>

<para><filename><replaceable>socket</replaceable>.socket</filename></para>

</refsynopsisdiv>

<refsect1>

<title>Description</title>

<para>A unit configuration file whose name ends in

<filename>.socket</filename> encodes information about

an IPC or network socket or a file system FIFO

controlled and supervised by systemd, for socket-based

activation.</para>

<para>This man page lists the configuration options

specific to 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>

<para>Additional options are listed in

<citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,

which define the execution environment the

<option>ExecStartPre=</option>,

<option>ExecStartPost=</option>,

<option>ExecStopPre=</option> and

<option>ExecStopPost=</option> commands are executed

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

<citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>

for details) must exist, describing the service to

start on incoming traffic on the socket. Depending on

the setting of <option>Accept=</option> (see below),

this must either be named like the socket unit, but

with the suffix replaced; or it must be a template

file 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 <filename>foo@.service</filename> must exist from

which services are instantiated for each incoming

connection.</para>

<para>Unless <varname>DefaultDependencies=</varname>

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 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>

<title>Options</title>

<para>Socket files must include a [Socket] section,

which carries information about the socket or FIFO it

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>

and

<citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>. The

options specific to the [Socket] section of socket

units are the following:</para>

<variablelist class='unit-directives'>

<varlistentry>

<term><varname>ListenStream=</varname></term>

<term><varname>ListenDatagram=</varname></term>

<term><varname>ListenSequentialPacket=</varname></term>

<listitem><para>Specifies an address

to listen on for a stream

(<constant>SOCK_STREAM</constant>), datagram (<constant>SOCK_DGRAM</constant>),

or sequential packet

(<constant>SOCK_SEQPACKET</constant>) socket, respectively. The address

can be written in various formats:</para>

<para>If the address starts with a

slash (<literal>/</literal>), it is read as file system

socket in the <constant>AF_UNIX</constant> socket

family.</para>

<para>If the address starts with an at

symbol (<literal>@</literal>) it is read as abstract

namespace socket in the

<constant>AF_UNIX</constant>

family. The <literal>@</literal> is

replaced with a

<constant>NUL</constant> character

before binding. For details see

<citerefentry><refentrytitle>unix</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>

<para>If the address string is a

single number it is read as port

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

read as IPv4 specifier for listening

on an address v.w.x.y on a port

z.</para>

<para>If the address string is a

string in the format [x]:y it is read

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 <constant>SOCK_SEQPACKET</constant>

(i.e. <varname>ListenSequentialPacket=</varname>)

is only available for <constant>AF_UNIX</constant>

sockets. <constant>SOCK_STREAM</constant>

(i.e. <varname>ListenStream=</varname>)

when used for IP sockets refers to TCP

sockets, <constant>SOCK_DGRAM</constant>

(i.e. <varname>ListenDatagram=</varname>)

to UDP.</para>

<para>These options may be specified

more than once in which case incoming

traffic on any of the sockets will

trigger service activation, and all

listed sockets will be passed to the

service, regardless whether there is

incoming traffic on them or not. If

the empty string is assigned to any of

these options, the list of addresses

to listen on is reset, all prior uses

of any of these options will have no

effect.</para>

<para>If an IP address is used here,

it is often desirable to listen on it

before the interface it is configured

on is up and running, and even

regardless whether it will be up and

running ever at all. To deal with this

it is recommended to set the

<varname>FreeBind=</varname> option

described below.</para></listitem>

</varlistentry>

<varlistentry>

<term><varname>ListenFIFO=</varname></term>

<listitem><para>Specifies a file

system FIFO to listen on. This expects

an absolute file system path as

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 <constant>AF_NETLINK</constant> 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

<option>default</option>,

<option>both</option> or

<option>ipv6-only</option>. Controls

the IPV6_V6ONLY socket option (see

<citerefentry><refentrytitle>ipv6</refentrytitle><manvolnum>7</manvolnum></citerefentry>

for details). If

<option>both</option>, IPv6 sockets

bound will be accessible via both IPv4

and IPv6. If

<option>ipv6-only</option>, they will

be accessible via IPv6 only. If

<option>default</option> (which is the

default, surprise!) the system wide

default setting is used, as controlled

by

<filename>/proc/sys/net/ipv6/bindv6only</filename>,

which in turn defaults to the

equivalent of

<option>both</option>.</para>

</listitem>

</varlistentry>

<varlistentry>

<term><varname>Backlog=</varname></term>

<listitem><para>Takes an unsigned

integer argument. Specifies the number

of connections to queue that have not

been accepted yet. This setting

matters only for stream and sequential

packet sockets. See

<citerefentry><refentrytitle>listen</refentrytitle><manvolnum>2</manvolnum></citerefentry>

for details. Defaults to SOMAXCONN

(128).</para></listitem>

</varlistentry>

<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><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>

for details). If this option is used,

an automatic dependency from this

socket unit on the network interface

device unit

(<citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>

is created.</para></listitem>

</varlistentry>

<varlistentry>

<term><varname>DirectoryMode=</varname></term>

<listitem><para>If listening on a file

system socket or FIFO, the parent

directories are automatically created

if needed. This option specifies the

file system access mode used when

creating these directories. Takes an

access mode in octal

notation. Defaults to

0755.</para></listitem>

</varlistentry>

<varlistentry>

<term><varname>SocketMode=</varname></term>

<listitem><para>If listening on a file

system socket or FIFO, this option

specifies the file system access mode

used when creating the file

node. Takes an access mode in octal

notation. Defaults to

0666.</para></listitem>

</varlistentry>

<varlistentry>

<term><varname>Accept=</varname></term>

<listitem><para>Takes a boolean

argument. If true, a service instance

is spawned for each incoming

connection and only the connection

socket is passed to it. If false, all

listening sockets themselves are

passed to the started service unit,

and only one service unit is spawned

for all connections (also see

above). This value is ignored for

datagram sockets and FIFOs where a

single service unit unconditionally

handles all 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 <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 may do so for sockets it got with

<varname>Accept=true</varname> set.

Setting <varname>Accept=true</varname>

is mostly useful to allow daemons

designed for usage with

<citerefentry><refentrytitle>inetd</refentrytitle><manvolnum>8</manvolnum></citerefentry>

to work unmodified with systemd socket

activation.</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 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

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><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>

<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><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>

for details.).</para></listitem>

</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><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>

for details.).</para></listitem>

</varlistentry>

<varlistentry>

<term><varname>IPTOS=</varname></term>

<listitem><para>Takes an integer

argument controlling the IP

Type-Of-Service field for packets

generated from this socket. This

controls the IP_TOS socket option (see

<citerefentry><refentrytitle>ip</refentrytitle><manvolnum>7</manvolnum></citerefentry>

for details.). Either a numeric string

or one of <option>low-delay</option>,

<option>throughput</option>,

<option>reliability</option> or

<option>low-cost</option> may be

specified.</para></listitem>

</varlistentry>

<varlistentry>

<term><varname>IPTTL=</varname></term>

<listitem><para>Takes an integer

argument controlling the IPv4

Time-To-Live/IPv6 Hop-Count field for

packets generated from this

socket. This sets the

IP_TTL/IPV6_UNICAST_HOPS socket

options (see

<citerefentry><refentrytitle>ip</refentrytitle><manvolnum>7</manvolnum></citerefentry>

and

<citerefentry><refentrytitle>ipv6</refentrytitle><manvolnum>7</manvolnum></citerefentry>

for details.)</para></listitem>

</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><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 bind()s

to this TCP or UDP port. This

controls the SO_REUSEPORT socket

option. See

<citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>

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

value. Controls the pipe buffer size

of FIFOs configured in this socket

unit. See

<citerefentry><refentrytitle>fcntl</refentrytitle><manvolnum>2</manvolnum></citerefentry>

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

value. Controls whether the socket can

be bound to non-local IP

addresses. This is useful to configure

sockets listening on specific IP

addresses before those IP addresses

are successfully configured on a

network interface. This sets the

IP_FREEBIND socket option. For

robustness reasons it is recommended

to use this option whenever you bind a

socket to a specific IP

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 <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. 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 one or more

command lines, which are executed

before or after the listening

sockets/FIFOs are created and

bound, respectively. The first token of the command

line must be an absolute filename,

then followed by arguments for the

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>

<term><varname>ExecStopPre=</varname></term>

<term><varname>ExecStopPost=</varname></term>

<listitem><para>Additional commands

that are executed before or after

the listening sockets/FIFOs are closed

and removed, respectively. Multiple command lines

may be specified following the same

scheme as used for

<varname>ExecStartPre=</varname> of

service unit files.</para></listitem>

</varlistentry>

<varlistentry>

<term><varname>TimeoutSec=</varname></term>

<listitem><para>Configures the time to

wait for the commands specified in

<varname>ExecStartPre=</varname>,

<varname>ExecStartPost=</varname>,

<varname>ExecStopPre=</varname> and

<varname>ExecStopPost=</varname> to

finish. If a command does not exit

within the configured time, the socket

will be considered failed and be shut

down again. All commands still running,

will be terminated forcibly via

<constant>SIGTERM</constant>, and after another delay of

this time with <constant>SIGKILL</constant>. (See

<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

90s.</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>

<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>

<title>See Also</title>

<para>

<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,

<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>,

<citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>

</para>

<para>

For more extensive descriptions see the "systemd for Developers" series:

<ulink url="http://0pointer.de/blog/projects/socket-activation.html">Socket Activation</ulink>,

<ulink url="http://0pointer.de/blog/projects/socket-activation2.html">Socket Activation, part II</ulink>,

<ulink url="http://0pointer.de/blog/projects/inetd.html">Converting inetd Services</ulink>,

<ulink url="http://0pointer.de/blog/projects/socket-activated-containers.html">Socket Activated Internet Services and OS Containers</ulink>.

</para>

</refsect1>

</refentry>