<?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>systemd socket configuration files</refpurpose>

</refnamediv>

<refsynopsisdiv>

<para><filename>systemd.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>ExecStoptPost=</option> commands are executed

in.</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>. The

options specific to the [Socket] section of socket

units are the following:</para>

<variablelist>

<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

(SOCK_STREAM), datagram (SOCK_DGRAM)

resp. sequential packet

(SOCK_SEQPACKET) socket. The address

can be written in various formats:</para>

<para>If the address starts with a

slash (/), it is read as file system

socket in the AF_UNIX socket

family.</para>

<para>If the address starts with an

ampersand (@) it is read as abstract

namespace socket in the AF_UNIX

family. The @ is replaced with a NUL

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 for both IPv4 and

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

<para>Note that SOCK_SEQPACKET

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

is only available for AF_UNIX

sockets. SOCK_STREAM

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

when used for IP sockets refers to TCP

sockets, SOCK_DGRAM

(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.</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. Behaviour 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. 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

<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>.</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 of 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 of 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>. This

option 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 for sockets configured with

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

resp. send buffer sizes of this

socket. This controls the SO_RCVBUF

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

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

option. 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 (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. 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 (resp. after)

the listening sockets/FIFOs are closed

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>

<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

SIGTERM, and after another delay of

this time with SIGKILL. (See

<option>KillMode=</option> below.)

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>KillMode=</varname></term>

<listitem><para>Specifies how

processes of this socket unit shall be

killed. One of

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

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

<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.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>

</para>

</refsect1>

</refentry>