X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=man%2Fsystemd.socket.xml;h=352825f5802847ce21e389483516aa5d0ce0e05a;hp=1c78562e8ad4cf8ceb733f2a86341d4458817d98;hb=4427c3f43a87c2e0c784fda6be1b9715be820733;hpb=1f19a534ea84458670ec011f6d1ba96f76e3f783 diff --git a/man/systemd.socket.xml b/man/systemd.socket.xml index 1c78562e8..352825f58 100644 --- a/man/systemd.socket.xml +++ b/man/systemd.socket.xml @@ -84,22 +84,27 @@ which configure resource control settings for the processes of the socket. - For each socket file a matching service file - (see + 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 @@ -116,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 @@ -127,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). @@ -171,7 +188,7 @@ replaced with a NUL character before binding. For details, see - unix7. + unix7. If the address string is a single number, it is read as port @@ -213,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 @@ -221,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. @@ -344,16 +372,21 @@ - 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. + 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. @@ -367,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 @@ -441,6 +487,17 @@ . + + 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 @@ -456,12 +513,15 @@ ReceiveBuffer= SendBuffer= Takes an integer - argument controlling the receive - or send buffer sizes of this - socket, respectively. This controls the SO_RCVBUF - and 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. @@ -540,12 +600,14 @@ 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 fcntl2 - for details. + for details. The usual suffixes K, M, + G are supported and are understood to + the base of 1024. @@ -671,27 +733,69 @@ 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 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 TimeoutStartSec= in - manager configuration file. + 20s". Pass 0 to disable the timeout + logic. Defaults to DefaultTimeoutStartSec= from the + manager configuration file + (see systemd-systemd.conf5). + 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. + + + + 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.