From 1f812feafb4b98d5cfa2934886bbdd43325780bb Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Thu, 1 Jul 2010 23:49:50 +0200 Subject: [PATCH] man: document socket units --- Makefile.am | 1 + man/systemd.service.xml | 8 +- man/systemd.socket.xml | 498 ++++++++++++++++++++++++++++++++++++++++ man/systemd.unit.xml | 38 +++ src/socket.c | 5 - 5 files changed, 541 insertions(+), 9 deletions(-) create mode 100644 man/systemd.socket.xml diff --git a/Makefile.am b/Makefile.am index 3a4c8f07..1beeb341 100644 --- a/Makefile.am +++ b/Makefile.am @@ -317,6 +317,7 @@ MANPAGES = \ man/sd_is_fifo.3 \ man/systemd.unit.5 \ man/systemd.service.5 \ + man/systemd.socket.5 \ man/daemon.7 \ man/sd-daemon.7 \ man/runlevel.8 \ diff --git a/man/systemd.service.xml b/man/systemd.service.xml index 449fe656..c6fdc0d5 100644 --- a/man/systemd.service.xml +++ b/man/systemd.service.xml @@ -54,9 +54,9 @@ Description - A configuration file ending in .service encodes - information about a process controlled and supervised - by systemd. + A unit configuration file whose name ends in + .service encodes information about a process + controlled and supervised by systemd. This man page lists the configuration options specific to this unit type. See @@ -308,7 +308,7 @@ forcibly via SIGTERM, and after another delay of this time with SIGKILL. (See - + below.) Takes a unit-less value in seconds, or a time span value such as "5min 20s". Pass 0 to disable the timeout diff --git a/man/systemd.socket.xml b/man/systemd.socket.xml new file mode 100644 index 00000000..f187fe3b --- /dev/null +++ b/man/systemd.socket.xml @@ -0,0 +1,498 @@ + + + + + + + + + systemd.socket + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd.socket + 5 + + + + systemd.socket + systemd socket configuration files + + + + systemd.socket + + + + Description + + A unit configuration file whose name ends in .socket + encodes information about an IPC or network socket or + a file system FIFO controlled and supervised by systemd, + for socket-based activation. + + This man page lists the configuration options + specific to this unit type. See + systemd.unit5 + for the common options of all unit configuration + files. The common configuration items are configured + in the generic [Unit] and [Install] sections. The + service specific configuration options are configured + in the [Socket] section. + + Additional options are listed in + systemd.exec5. + + For each socket file a matching service file (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 + 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. + + + + Options + + Socket files must include a [Socket] section, + which carries information about the socket or FIFO it + 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 + options specific to the [Socket] section of service + 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 + 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 + 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 string is a + single number it is read as port + number to listen on for both IPv4 and + IPv6. + + If the address string is a + 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 + (i.e. ListenSequentialPacket=) + is only available for AF_UNIX + sockets. SOCK_STREAM + (i.e. ListenStream=) + when used for IP sockets refers to TCP + 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 + 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 + FreeBind= option + described below. + + + + ListenFIFO= + Specifies a file + system FIFO to listen on. This expects + an absolute file system path as + argument. Behaviour otherwise is very + similar to the + ListenDatagram= + directive above. + + + + BindIPv6Only= + Takes a one of + , + or + . Controls + the IPV6_V6ONLY socket option (see + ipv67 + for details). If + , IPv6 sockets + bound will be accessible via both IPv4 + and IPv6. If + , they will + be accessible via IPv6 only. If + (which is the + default, surprise!) the system wide + default setting is used, as controlled + by + /proc/sys/net/ipv6/bindv6only. + + + + + Backlog= + Takes an unsigned + integer argument. Specifies the number + of connections to queue that have not + been accepted yet. This setting + matters only for stream and sequential + packet sockets. See + listen2 + for details. Defaults to SOMAXCONN + (128). + + + + BindToDevice= + Specifies a network + interface name to bind this socket + to. If set traffic will only be + accepted from the specified network + interfaces. This controls the + SO_BINDTODEVICE socket option (see + socket7 + for details). If this option is used + an automatic dependency from this + socket unit on the network interface + device unit + (systemd.device5 + is created. + + + + 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. + + + + SocketMode= + If listening on a file + system socket of FIFO this option + specifies the file system access mode + used when creating the file + node. Defaults to + 0666. + + + + Accept= + Takes a boolean + argument. If true a service instance + is spawned for each incoming + connection and only the connection + socket is passed to it. If false all + listening sockets themselves are + passed to the started service unit, + and only one service unit is spawned + for all connections (also see + above). This value is ignored for + datagram sockets and FIFOs where + unconditionally a single service unit + 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 + to work unmodified with system socket + activation. + + + + MaxConnections= + The maximum number of + connections to simultaneously run + services instances for, when + is + set. If more concurrent connections + 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 + sockets. Defaults to + 64. + + + + KeepAlive= + Takes a boolean + argument. If true, the TCP/IP stack + will send a keep alive message after + 2h (depending on the configuration of + /proc/sys/net/ipv4/tcp_keepalive_time) + for all TCP streams accepted on this + socket. This controls the SO_KEEPALIVE + socket option (see + socket7 + and the TCP + Keepalive HOWTO for details.) + Defaults to + . + + + + Priority= + Takes an integer + argument controlling the priority for + all traffic sent from this + socket. This controls the SO_PRIORITY + socket option (see + socket7 + for details.). + + + + 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 + socket7 + for details.). + + + + IPTOS= + Takes an integer + argument controlling the IP + Type-Of-Service field for packets + generated from this socket. This + controls the IP_TOS socket option (see + ip7 + for details.). Either a numeric string + or one of , + , + or + may be + specified. + + + + IPTTL= + Takes an integer + argument controlling the IPv4 + Time-To-Live/IPv6 Hop-Count field for + packets generated from this + socket. This sets the + IP_TTL/IPV6_UNICAST_HOPS socket + options (see + ip7 + and + ipv67 + for details.) + + + + Mark= + Takes an integer + value. Controls the firewall mark of + packets generated by this socket. This + can be used in the firewall logic to + filter packets from this socket. This + sets the SO_MARK socket option. See + iptables8 + for details. + + + + PipeSize= + Takes an integer + value. Controls the pipe buffer size + of FIFOs configured in this socket + unit. See + fcntl2 + for details. + + + + FreeBind= + Takes a boolean + value. Controls whether the socket can + be bound to non-local IP + addresses. This is useful to configure + sockets listening on specific IP + addresses before those IP addresses + are successfully configured on a + network interface. This sets the + IP_FREEBIND socket option. For + robustness reasons it is recommended + to use this option whenever you bind a + socket to a specific IP + address. Defaults to . + + + + + ExecStartPre= + ExecStartPost= + Takes a command line + that 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, + then followed by arguments for the + process. If specified more than once, + all commands are executed one after + the other, serially. Use of these + settings is optional. + + + + ExecStopPre= + ExecStopPost= + Additional commands + that are executed before (resp. after) + the listening sockets/FIFOs are closed + and removed. If specified more than + once, all commands are executed one + after the other, serially. Use of + these settings is + optional. + + + + + TimeoutSec= + Configures the time to + wait for the commands specified in + ExecStartPre=, + ExecStartPost=, + ExecStopPre= and + ExecStopPost= to + finish. If a comand does not exit + within the configured time the socket + 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 + below.) + 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. + + + + + KillMode= + Specifies how + processes of this service shall be + killed. One of + , + , + , + . + + This option is mostly equivalent + to the + option of service files. See + systemd.service5 + for details. + + + + + + + + See Also + + systemd8, + systemctl8, + systemd.unit5, + systemd.exec5, + systemd.service5 + + + + diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml index 81634410..da077e20 100644 --- a/man/systemd.unit.xml +++ b/man/systemd.unit.xml @@ -144,6 +144,44 @@ activation which makes dependencies implicit, which both results in a simpler and more flexible system. + + Some unit names reflect paths existing in the + file system name space. Example: a device unit + dev-sda.device refers to a device + with the device node /dev/sda in + the file system namespace. If this applies a special + way to escape the path name is used, so that it is + usable as part of a file name. Basically, given a path, + "/" is replaced by "-", and all unprintable characters + and the "-" are replaced by C-style "\x20" + escapes. This escaping is reversible. + + Optionally, units may be instantiated from a + template file at runtime. This allows creation of + multiple units from a single configuration file. If + systemd looks for a unit configuration file it will + first search for the literal unit name in the + filesystem. If that yields no success and the unit + name contains an @ character, systemd will look for a + unit template that shares the same name but with the + instance string (i.e. the part between the @ character + and the suffix) removed. Example: if a service + getty@tty3.service is requested + and no file by that name is found, systemd will look + for getty@.service and + instantiate a service from that configuration file if + it is found. To refer to the instance string from + within the configuration file you may use the special + %i specifier in many of the + configuration options. Other specifiers that may be + used are %n, %N, + %p, %P and + %I, for the full unit name, the + unescaped unit name, the prefix name, the unescaped + prefix name and the unescaped instance name, + respectively. The prefix name here refers to the + string before the @, i.e. "getty" in the example + above, where "tty3" is the instance name. diff --git a/src/socket.c b/src/socket.c index 00fb568b..8edf0ce5 100644 --- a/src/socket.c +++ b/src/socket.c @@ -66,15 +66,10 @@ static void socket_init(Unit *u) { s->max_connections = 64; - s->keep_alive = false; s->priority = -1; - s->receive_buffer = 0; - s->send_buffer = 0; s->ip_tos = -1; s->ip_ttl = -1; - s->pipe_size = 0; s->mark = -1; - s->free_bind = false; exec_context_init(&s->exec_context); -- 2.39.5