X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=man%2Fsystemd.socket.xml;h=f495fe3666117e137c66139a5f1440b3db6d81d6;hp=0a2d86996be29c9001416b1e861dcee67f68a7a0;hb=73e231abde39f22097df50542c745e01de879836;hpb=05cc726731c5cec952722f1c14acb08e3d4d5e98 diff --git a/man/systemd.socket.xml b/man/systemd.socket.xml index 0a2d86996..f495fe366 100644 --- a/man/systemd.socket.xml +++ b/man/systemd.socket.xml @@ -55,7 +55,7 @@ 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. @@ -77,26 +77,34 @@ and commands are executed in, and in - systemd.kill5 - which define the way the processes are - terminated. - - For each socket file a matching service file - (see + 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 + option described below. + Depending on the setting of + 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 @@ -113,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 introduction. Note that the daemon software configured for socket activation with socket units needs to be able @@ -124,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). @@ -161,17 +181,17 @@ family. If the address starts with an at - symbol (@) it is read as abstract + 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 + 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 @@ -181,13 +201,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 @@ -210,7 +230,7 @@ traffic on any of the sockets will trigger service activation, and all listed sockets will be passed to the - service, regardless whether there is + 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 @@ -218,12 +238,23 @@ 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 + 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. @@ -300,7 +331,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, @@ -327,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 @@ -504,6 +535,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= @@ -665,19 +707,22 @@ 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. + logic. Defaults to TimeoutStartSec= from the + manager configuration file. 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. + 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. @@ -698,6 +743,7 @@ systemd.unit5, systemd.exec5, systemd.kill5, + systemd.resource-control5, systemd.service5, systemd.directives7