X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=man%2Fsystemd.socket.xml;h=57f769f23a177b66a87be63d8623ee807a2ba276;hp=81f9deab365bf936e11e7f82b8cd63be8553290b;hb=92ff080be100aff15f292e2631921131c610afe7;hpb=ba60f9054e7aee0b817cfef4f715b0022818bbb3 diff --git a/man/systemd.socket.xml b/man/systemd.socket.xml index 81f9deab3..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.socket Description A 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,29 +75,78 @@ , , 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 + implicitly have dependencies of type + Requires= and + After= on + sysinit.target as well as + dependencies of type Conflicts= and + Before= on + shutdown.target. 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. + + 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 + to accept sockets from systemd, either via systemd's + native socket passing interface (see + sd_listen_fds3 + for details) or via the traditional + inetd8-style + socket passing (i.e. sockets passed in via standard input and + output, using StandardInput=socket + in the service file). @@ -108,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. @@ -186,12 +265,57 @@ 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. + + ListenSpecial= + 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 + ListenFIFO= + directive above. Use this to open + character device nodes as well as + special files in + /proc and + /sys. + + + + ListenNetlink= + 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 audit + or kobject-uevent) + as argument, optionally suffixed by a + whitespace followed by a multicast + group integer. Behavior otherwise is + very similar to the + ListenDatagram= + directive above. + + + + ListenMessageQueue= + 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 + ListenFIFO= + directive above. On Linux message + queue descriptors are actually file + descriptors and can be inherited + between processes. + + BindIPv6Only= Takes a one of @@ -207,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 + . @@ -231,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 @@ -245,26 +372,47 @@ - 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. 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. Defaults to + node. Takes an access mode in octal + notation. Defaults to 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 @@ -277,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. @@ -302,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. @@ -326,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 @@ -337,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. @@ -392,13 +644,85 @@ 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. The usual suffixes K, M, + G are supported and are understood to + the base of 1024. + + + + MessageQueueMaxMessages=, + MessageQueueMessageSize= + 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 + mq_setattr3 for details. @@ -419,31 +743,86 @@ address. Defaults to . + + Transparent= + Takes a boolean + value. Controls the IP_TRANSPARENT + 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 + . + + + + TCPCongestion= + 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. + + ExecStartPre= ExecStartPost= - 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, + 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. If specified more than once, - all commands are executed one after - the other, fully serialized. The use of - these settings is optional. + process. Multiple command lines may be + specified following the same scheme as + used for + ExecStartPre= of + service unit files. ExecStopPre= ExecStopPost= Additional commands - that are executed before (resp. after) + that are executed before or 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. + and removed, respectively. Multiple command lines + may be specified following the same + scheme as used for + ExecStartPre= of + service unit files. @@ -457,45 +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 - 60s. + 20s". Pass 0 to disable the timeout + logic. Defaults to DefaultTimeoutStartSec= from the + manager configuration file + (see systemd-system.conf5). + - KillMode= - Specifies how - processes of this socket unit shall be - killed. One of - , - , - , - . + 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. + - This option is mostly equivalent - to the - option of service files. See - systemd.service5 - for details. + + 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. + + + + 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 Also - systemd8, - systemctl8, + systemd1, + 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.