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

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

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

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

06ba4a61654b3763ad65f52283832ebf058fdf1cslive

06ba4a61654b3763ad65f52283832ebf058fdf1cslive

06ba4a61654b3763ad65f52283832ebf058fdf1cslive<refentry id="systemd.socket">

06ba4a61654b3763ad65f52283832ebf058fdf1cslive <refentryinfo>

06ba4a61654b3763ad65f52283832ebf058fdf1cslive <title>systemd.socket</title>

06ba4a61654b3763ad65f52283832ebf058fdf1cslive <productname>systemd</productname>

06ba4a61654b3763ad65f52283832ebf058fdf1cslive

06ba4a61654b3763ad65f52283832ebf058fdf1cslive <authorgroup>

06ba4a61654b3763ad65f52283832ebf058fdf1cslive <author>

06ba4a61654b3763ad65f52283832ebf058fdf1cslive <contrib>Developer</contrib>

06ba4a61654b3763ad65f52283832ebf058fdf1cslive <firstname>Lennart</firstname>

06ba4a61654b3763ad65f52283832ebf058fdf1cslive <surname>Poettering</surname>

06ba4a61654b3763ad65f52283832ebf058fdf1cslive <email>lennart@poettering.net</email>

06ba4a61654b3763ad65f52283832ebf058fdf1cslive </author>

06ba4a61654b3763ad65f52283832ebf058fdf1cslive </authorgroup>

06ba4a61654b3763ad65f52283832ebf058fdf1cslive </refentryinfo>

06ba4a61654b3763ad65f52283832ebf058fdf1cslive

06ba4a61654b3763ad65f52283832ebf058fdf1cslive <refmeta>

06ba4a61654b3763ad65f52283832ebf058fdf1cslive <refentrytitle>systemd.socket</refentrytitle>

06ba4a61654b3763ad65f52283832ebf058fdf1cslive <manvolnum>5</manvolnum>

06ba4a61654b3763ad65f52283832ebf058fdf1cslive </refmeta>

06ba4a61654b3763ad65f52283832ebf058fdf1cslive

06ba4a61654b3763ad65f52283832ebf058fdf1cslive <refnamediv>

06ba4a61654b3763ad65f52283832ebf058fdf1cslive <refname>systemd.socket</refname>

06ba4a61654b3763ad65f52283832ebf058fdf1cslive <refpurpose>systemd socket configuration files</refpurpose>

06ba4a61654b3763ad65f52283832ebf058fdf1cslive </refnamediv>

06ba4a61654b3763ad65f52283832ebf058fdf1cslive

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

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

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>

</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. If specified more than

once, all commands are executed one

after the other, fully serialized. The use of

these settings is optional.</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

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

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