X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=man%2Fsystemd.socket.xml;h=419a38caa71a8f5dab2ce3240a0d41a7b1c0c830;hp=4b1fcc8b0cf725d5b85f7472e17e7d4bfb7328b7;hb=79640424059328268b9fb6c5fa8eb777b27a177e;hpb=7277f5a9d91ea6cdbcc558f3dc372943cbca464e diff --git a/man/systemd.socket.xml b/man/systemd.socket.xml index 4b1fcc8b0..419a38caa 100644 --- a/man/systemd.socket.xml +++ b/man/systemd.socket.xml @@ -48,14 +48,14 @@ - 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,11 +75,14 @@ , , and - commands are executed + commands are executed in, and in - systemd.kill5 + systemd.kill5, which define the way the processes are - terminated. + terminated, and in + systemd.cgroup5, + which configure control group settings for the + processes of the service. For each socket file a matching service file (see @@ -93,7 +96,7 @@ foo.socket needs a matching service foo.service if is set. If - is set a service template + is set, a service template file foo@.service must exist from which services are instantiated for each incoming connection. @@ -143,33 +146,35 @@ 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), + (SOCK_STREAM), datagram (SOCK_DGRAM), or sequential packet - (SOCK_SEQPACKET) socket, respectively. The address + (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 - 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 + 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 + single number, it is read as port number to listen on via IPv6. Depending on the value of BindIPv6Only= (see below) this @@ -179,13 +184,13 @@ 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 + 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 @@ -193,31 +198,36 @@ setting (see below). - Note that SOCK_SEQPACKET + 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 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. + + 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 + running ever at all. To deal with this + it is recommended to set the FreeBind= option described below. @@ -253,7 +263,7 @@ 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 @@ -293,7 +303,7 @@ , 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, @@ -320,7 +330,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 @@ -369,17 +379,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. @@ -394,7 +417,7 @@ are coming in, they will be refused until at least one existing connection is terminated. This setting has no - effect for sockets configured with + effect on sockets configured with or datagram sockets. Defaults to 64. @@ -484,6 +507,17 @@ 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= @@ -498,7 +532,7 @@ respectively, i.e. the security label of the FIFO, or the security label for the incoming or outgoing connections - of the socket, respectively. See + of the socket, respectively. See Smack.txt for details. @@ -509,7 +543,7 @@ Takes an integer value. Controls the pipe buffer size of FIFOs configured in this socket - unit. See + unit. See fcntl2 for details. @@ -566,7 +600,7 @@ PassCredentials= Takes a boolean value. This controls the SO_PASSCRED - socket option, which allows AF_UNIX sockets to + socket option, which allows AF_UNIX sockets to receive the credentials of the sending process in an ancillary message. Defaults to @@ -577,10 +611,10 @@ PassSecurity= Takes a boolean value. This controls the SO_PASSSEC - socket option, which allows AF_UNIX + socket option, which allows AF_UNIX sockets to receive the security context of the sending process in an - ancillary message. Defaults to + ancillary message. Defaults to . @@ -604,7 +638,7 @@ before or after the listening sockets/FIFOs are created and bound, respectively. The first token of the command - line must be an absolute file name, + line must be an absolute filename, then followed by arguments for the process. Multiple command lines may be specified following the same scheme as @@ -639,8 +673,8 @@ 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 + 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 @@ -678,7 +712,17 @@ systemd.unit5, systemd.exec5, systemd.kill5, - systemd.service5 + systemd.cgroup5, + 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.