X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=man%2Fsystemd.socket.xml;h=57f769f23a177b66a87be63d8623ee807a2ba276;hb=dd4105b0a90c3c146a01e5a7734ee76c3a9aa1cd;hp=53502667e5e61e62f2b147d39a5c5a2b6fdb0be7;hpb=6b6d2deecc246cf9780d31e1cd03a52aa5bfd9d2;p=elogind.git
diff --git a/man/systemd.socket.xml b/man/systemd.socket.xml
index 53502667e..57f769f23 100644
--- a/man/systemd.socket.xml
+++ b/man/systemd.socket.xml
@@ -9,16 +9,16 @@
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 .
-->
@@ -44,18 +44,18 @@
systemd.socket
- systemd socket configuration files
+ Socket unit configuration
- systemd.socket
+ socket.socketDescriptionA unit configuration file whose name ends in
- .socket encodes information about
+ .socket encodes information about
an IPC or network socket or a file system FIFO
controlled and supervised by systemd, for socket-based
activation.
@@ -75,25 +75,36 @@
,
,
and
- commands are executed
- in.
-
- For each socket file a matching service file
- (see
+ commands are executed
+ in, and in
+ systemd.kill5,
+ which define the way the processes are terminated, and
+ in
+ systemd.resource-control5,
+ which configure resource control settings for the
+ processes of the socket.
+
+ For each socket file, a matching service file
+ must exist, describing the service to start on
+ incoming traffic on the socket (see
systemd.service5
- for details) must exist, describing the service to
- start on incoming traffic on the socket. Depending on
- the setting of (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
+ for more information about .service files). The name
+ of the .service unit is by default the same as the
+ name of the .socket unit, but can be altered with the
+ option described below.
+ Depending on the setting of the
+ option described below, this .service unit must either
+ be named like the .socket unit, but with the suffix
+ replaced, unless overridden with
+ ; or it must be a template
+ unit named the same way. Example: a socket file
foo.socket needs a matching
service foo.service if
is set. If
- is set a service template
- file foo@.service must exist from
- which services are instantiated for each incoming
- connection.
+ is set, a service
+ template file foo@.service must
+ exist from which services are instantiated for each
+ incoming connection.
Unless DefaultDependencies=
is set to , socket units will
@@ -110,9 +121,21 @@
boot or late system shutdown should disable this
option.
+ Socket units will have a
+ Before= dependency on the service
+ which they trigger added implicitly. No implicit
+ WantedBy= or
+ RequiredBy= dependency from the
+ socket to the service is added. This means that the
+ service may be started without the socket, in which
+ case it must be able to open sockets by itself. To
+ prevent this, an explicit Requires=
+ dependency may be added.
+
Socket units may be used to implement on-demand
starting of services, as well as parallelized starting
- of services.
+ of services. See the blog stories linked at the end
+ for an introduction.
Note that the daemon software configured for
socket activation with socket units needs to be able
@@ -121,8 +144,8 @@
sd_listen_fds3
for details) or via the traditional
inetd8-style
- socket passing (i.e. sockets passed in via STDIN and
- STDOUT, using StandardInput=socket
+ socket passing (i.e. sockets passed in via standard input and
+ output, using StandardInput=socket
in the service file).
@@ -134,75 +157,105 @@
supervises. A number of options that may be used in
this section are shared with other unit types. These
options are documented in
- systemd.exec5. The
+ systemd.exec5
+ and
+ systemd.kill5. The
options specific to the [Socket] section of socket
units are the following:
-
+ ListenStream=ListenDatagram=ListenSequentialPacket=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:If the address starts with a
- slash (/), it is read as file system
- socket in the AF_UNIX socket
+ slash (/), it is read as file system
+ socket in the AF_UNIX socket
family.
- 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
- unix7.
+ If the address starts with an 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, see
+ unix7.If the address string is a
- single number it is read as port
- number to listen on for both IPv4 and
- IPv6.
+ single number, it is read as port
+ number to listen on via
+ IPv6. Depending on the value of
+ BindIPv6Only= (see below) this
+ might result in the service being
+ available via both IPv6 and IPv4 (default) or
+ just via IPv6.
+
If the address string is a
- string in the format v.w.x.y:z it is
+ 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.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 SOCK_SEQPACKET
+ 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 BindIPv6Only=
+ setting (see below).
+
+
+ Note that SOCK_SEQPACKET
(i.e. ListenSequentialPacket=)
- is only available for AF_UNIX
- sockets. SOCK_STREAM
+ is only available for AF_UNIX
+ sockets. SOCK_STREAM
(i.e. ListenStream=)
when used for IP sockets refers to TCP
- sockets, SOCK_DGRAM
+ sockets, SOCK_DGRAM
(i.e. ListenDatagram=)
to UDP.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 an IP address is used here, it
- is often desirable to listen on it
+ traffic on any of the sockets will
+ trigger service activation, and all
+ listed sockets will be passed to the
+ service, regardless of 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.
+
+ It is also possible to have more
+ than one socket unit for the same
+ service when using
+ Service=, and the
+ service will receive all the sockets
+ configured in all the socket units.
+ Sockets configured in one unit are
+ passed in the order of configuration,
+ but no ordering between socket units
+ is specified.
+
+ 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
+ regardless of whether it will be up and
+ running at any point. To deal with this,
+ it is recommended to set the
FreeBind= option
described below.
@@ -212,7 +265,7 @@
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
ListenDatagram=
directive above.
@@ -223,7 +276,7 @@
Specifies a special
file in the file system to listen
on. This expects an absolute file
- system path as argument. Behaviour
+ system path as argument. Behavior
otherwise is very similar to the
ListenFIFO=
directive above. Use this to open
@@ -238,12 +291,12 @@
Specifies a Netlink
family to create a socket for to
listen on. This expects a short string
- referring to the AF_NETLINK family
+ referring to the AF_NETLINK family
name (such as audit
or kobject-uevent)
as argument, optionally suffixed by a
whitespace followed by a multicast
- group integer. Behaviour otherwise is
+ group integer. Behavior otherwise is
very similar to the
ListenDatagram=
directive above.
@@ -254,7 +307,7 @@
Specifies a POSIX
message queue name to listen on. This
expects a valid message queue name
- (i.e. beginning with /). Behaviour
+ (i.e. beginning with /). Behavior
otherwise is very similar to the
ListenFIFO=
directive above. On Linux message
@@ -278,10 +331,13 @@
, they will
be accessible via IPv6 only. If
(which is the
- default, surprise!) the system wide
+ default, surprise!), the system wide
default setting is used, as controlled
by
- /proc/sys/net/ipv6/bindv6only.
+ /proc/sys/net/ipv6/bindv6only,
+ which in turn defaults to the
+ equivalent of
+ .
@@ -302,7 +358,7 @@
BindToDevice=Specifies a network
interface name to bind this socket
- to. If set traffic will only be
+ to. If set, traffic will only be
accepted from the specified network
interfaces. This controls the
SO_BINDTODEVICE socket option (see
@@ -316,22 +372,27 @@
- DirectoryMode=
- 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.
+ SocketUser=
+ SocketGroup=
+
+ Takes a UNIX
+ user/group name. When specified,
+ all AF_UNIX sockets and FIFO nodes in
+ the file system are owned by the
+ specified user and group. If unset
+ (the default), the nodes are owned by
+ the root user/group (if run in system
+ context) or the invoking user/group
+ (if run in user context). If only a
+ user is specified but no group, then
+ the group is derived from the user's
+ default group.SocketMode=If listening on a file
- system socket of FIFO, this option
+ system socket or FIFO, this option
specifies the file system access mode
used when creating the file
node. Takes an access mode in octal
@@ -339,6 +400,19 @@
0666.
+
+ DirectoryMode=
+ 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.
+
+
Accept=Takes a boolean
@@ -351,17 +425,30 @@
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
+ datagram sockets and FIFOs where a
+ single service unit unconditionally
handles all incoming traffic. Defaults
to . For
performance reasons, it is recommended
to write new daemons only in a way
that is suitable for
- . This
- option is mostly useful to allow
- daemons designed for usage with
- inetd8,
+ . A
+ daemon listening on an AF_UNIX socket
+ may, but does not need to, call
+ close2
+ on the received socket before
+ exiting. However, it must not unlink
+ the socket from a file system. It
+ should not invoke
+ shutdown2
+ on sockets it got with
+ Accept=false, but
+ it may do so for sockets it got with
+ Accept=true set.
+ Setting Accept=true
+ is mostly useful to allow daemons
+ designed for usage with
+ inetd8
to work unmodified with systemd socket
activation.
@@ -376,8 +463,8 @@
are coming in, they will be refused
until at least one existing connection
is terminated. This setting has no
- effect for sockets configured with
- or datagram
+ effect on sockets configured with
+ or datagram
sockets. Defaults to
64.
@@ -400,6 +487,53 @@
.
+
+ KeepAliveTimeSec=
+ Takes time (in seconds) as argument . The connection needs to remain
+ idle before TCP starts sending keepalive probes. This controls the TCP_KEEPIDLE
+ socket option (see
+ socket7
+ and the TCP
+ Keepalive HOWTO for details.)
+ Defaults value is 7200 seconds (2 hours).
+
+
+
+ KeepAliveIntervalSec=
+ Takes time (in seconds) as argument between individual keepalive probes,
+ if the socket option SO_KEEPALIVE has been set on this socket seconds as argument.
+ This controls the TCP_KEEPINTVL socket option (see
+ socket7
+ and the TCP
+ Keepalive HOWTO for details.)
+ Defaults value is 75 seconds.
+
+
+
+ KeepAliveProbes=
+ Takes integer as argument. It's the number of unacknowledged probes to
+ send before considering the connection dead and notifying the application layer.
+ This controls the TCP_KEEPCNT socket option (see
+ socket7
+ and the TCP
+ Keepalive HOWTO for details.)
+ Defaults value is 9.
+
+
+
+ NoDelay=
+ Takes a boolean
+ argument. TCP Nagle's algorithm works by combining a number of
+ small outgoing messages, and sending them all at once.
+ This controls the TCP_NODELAY socket option (see
+ tcp7
+ Defaults to
+ .
+
+
Priority=Takes an integer
@@ -411,16 +545,60 @@
for details.).
+
+ DeferAcceptSec=
+
+ Takes time (in
+ seconds) as argument. If set, the
+ listening process will be awakened
+ only when data arrives on the socket,
+ and not immediately when connection is
+ established. When this option is set,
+ the
+ TCP_DEFER_ACCEPT
+ socket option will be used (see
+ tcp7),
+ and the kernel will ignore initial ACK
+ packets without any data. The argument
+ specifies the approximate amount of
+ time the kernel should wait for
+ incoming data before falling back to
+ the normal behaviour of honouring
+ empty ACK packets. This option is
+ beneficial for protocols where the
+ client sends the data first (e.g.
+ HTTP, in contrast to SMTP), because
+ the server process will not be woken
+ up unnecessarily before it can take
+ any action.
+
+
+ If the client also uses the
+ TCP_DEFER_ACCEPT
+ option, the latency of the initial
+ connection may be reduced, because the
+ kernel will send data in the final
+ packet establishing the connection
+ (the third packet in the "three-way
+ handshake").
+
+ Disabled by default.
+
+
+
ReceiveBuffer=SendBuffer=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
+ argument controlling the receive or
+ send buffer sizes of this socket,
+ respectively. This controls the
+ SO_RCVBUF and SO_SNDBUF socket options
+ (see
socket7
- for details.).
+ for details.). The usual suffixes K,
+ M, G are supported and are understood
+ to the base of 1024.
@@ -466,14 +644,73 @@
for details.
+
+ ReusePort=
+ Takes a boolean
+ value. If true, allows multiple bind2s
+ to this TCP or UDP port. This
+ controls the SO_REUSEPORT socket
+ option. See
+ socket7
+ for details.
+
+
+
+ SmackLabel=
+ SmackLabelIPIn=
+ SmackLabelIPOut=
+ Takes a string
+ value. Controls the extended
+ attributes
+ security.SMACK64,
+ security.SMACK64IPIN
+ and
+ security.SMACK64IPOUT,
+ respectively, i.e. the security label
+ of the FIFO, or the security label for
+ the incoming or outgoing connections
+ of the socket, respectively. See
+ Smack.txt
+ for details.
+
+
+
+ SELinuxContextFromNet=
+ Takes a boolean
+ argument. When true, systemd will attempt
+ to figure out the SELinux label used
+ for the instantiated service from the
+ information handed by the peer over the
+ network. Note that only the security
+ level is used from the information
+ provided by the peer. Other parts of
+ the resulting SELinux context originate
+ from either the target binary that is
+ effectively triggered by socket unit
+ or from the value of the
+ SELinuxContext=
+ option. This configuration option only
+ affects sockets with
+ Accept= mode set to
+ true. Also note that
+ this option is useful only when
+ MLS/MCS SELinux policy is
+ deployed. Defaults to
+ false.
+
+
+
PipeSize=
- Takes an integer
- value. Controls the pipe buffer size
+ Takes a size in
+ bytes. Controls the pipe buffer size
of FIFOs configured in this socket
- unit. See
+ unit. See
fcntl2
- for details.
+ for details. The usual suffixes K, M,
+ G are supported and are understood to
+ the base of 1024.
@@ -481,7 +718,7 @@
MessageQueueMessageSize=These two settings
take integer values and control the
- mq_maxmsg resp. mq_msgsize field when
+ 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
@@ -510,7 +747,39 @@
Transparent=Takes a boolean
value. Controls the IP_TRANSPARENT
- option. Defaults to
+ socket option. Defaults to
+ .
+
+
+
+ Broadcast=
+ Takes a boolean
+ value. This controls the SO_BROADCAST
+ socket option, which allows broadcast
+ datagrams to be sent from this
+ socket. Defaults to
+ .
+
+
+
+ PassCredentials=
+ 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
+ .
+
+
+
+ PassSecurity=
+ 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
.
@@ -531,10 +800,10 @@
ExecStartPost=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
- line must be an absolute file name,
+ 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
@@ -547,9 +816,9 @@
ExecStopPre=ExecStopPost=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
ExecStartPre= of
@@ -567,75 +836,100 @@
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,
+ down again. All commands still running
will be terminated forcibly via
- SIGTERM, and after another delay of
- this time with SIGKILL. (See
- below.)
+ SIGTERM, and after another delay of
+ this time with SIGKILL. (See
+ in systemd.kill5.)
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.
-
-
-
- KillMode=
- Specifies how
- processes of this socket unit shall be
- killed. One of
- ,
- ,
- .
-
- This option is mostly equivalent
- to the
- option of service files. See
- systemd.service5
- for details.
+ 20s". Pass 0 to disable the timeout
+ logic. Defaults to DefaultTimeoutStartSec= from the
+ manager configuration file
+ (see systemd-system.conf5).
+
- KillSignal=
- Specifies which signal
- to use when killing a process of this
- socket. Defaults to SIGTERM.
-
+ Service=
+ Specifies the service
+ unit name to activate on incoming
+ traffic. This setting is only allowed
+ for sockets with
+ Accept=no. It
+ defaults to the service that bears the
+ same name as the socket (with the
+ suffix replaced). In most cases, it
+ should not be necessary to use this
+ option.
- SendSIGKILL=
- 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".
-
+ RemoveOnStop=
+ Takes a boolean
+ argument. If enabled, any file nodes
+ created by this socket unit are
+ removed when it is stopped. This
+ applies to AF_UNIX sockets in the file
+ system, POSIX message queues, FIFOs,
+ as well as any symlinks to
+ them configured with
+ Symlinks=. Normally,
+ it should not be necessary to use this
+ option, and is not recommended as
+ services might continue to run after
+ the socket unit has been terminated
+ and it should still be possible to
+ communicate with them via their file
+ system node. Defaults to
+ off.
- Service=
- 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.
+ Symlinks=
+ Takes a list of file
+ system paths. The specified paths will
+ be created as symlinks to the AF_UNIX
+ socket path or FIFO path of this
+ socket unit. If this setting is used,
+ only one AF_UNIX socket in the file
+ system or one FIFO may be configured
+ for the socket unit. Use this option
+ to manage one or more symlinked alias
+ names for a socket, binding their
+ lifecycle together. Defaults to the
+ empty list.
+
+ Check
+ systemd.exec5
+ and
+ systemd.kill5
+ for more settings.
+
See Alsosystemd1,
- systemctl8,
+ systemctl1,
systemd.unit5,
systemd.exec5,
- systemd.service5
+ systemd.kill5,
+ systemd.resource-control5,
+ systemd.service5,
+ systemd.directives7
+
+
+
+ For more extensive descriptions see the "systemd for Developers" series:
+ Socket Activation,
+ Socket Activation, part II,
+ Converting inetd Services,
+ Socket Activated Internet Services and OS Containers.