diff options
Diffstat (limited to 'man/systemd.socket.xml')
| -rw-r--r-- | man/systemd.socket.xml | 112 |
1 files changed, 71 insertions, 41 deletions
diff --git a/man/systemd.socket.xml b/man/systemd.socket.xml index 6dc847df3f..8c88d9f8aa 100644 --- a/man/systemd.socket.xml +++ b/man/systemd.socket.xml @@ -55,7 +55,7 @@ <title>Description</title> <para>A unit configuration file whose name ends in - <filename>.socket</filename> encodes information about + <literal>.socket</literal> encodes information about an IPC or network socket or a file system FIFO controlled and supervised by systemd, for socket-based activation.</para> @@ -77,9 +77,12 @@ <option>ExecStopPre=</option> and <option>ExecStopPost=</option> commands are executed in, and in - <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry> - which define the way the processes are - terminated.</para> + <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + which define the way the processes are terminated, and + in + <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + which configure resource control settings for the + processes of the socket.</para> <para>For each socket file a matching service file (see @@ -93,7 +96,7 @@ <filename>foo.socket</filename> needs a matching service <filename>foo.service</filename> if <option>Accept=false</option> is set. If - <option>Accept=true</option> is set a service template + <option>Accept=true</option> is set, a service template file <filename>foo@.service</filename> must exist from which services are instantiated for each incoming connection.</para> @@ -150,26 +153,28 @@ <term><varname>ListenSequentialPacket=</varname></term> <listitem><para>Specifies an address to listen on for a stream - (SOCK_STREAM), datagram (SOCK_DGRAM), + (<constant>SOCK_STREAM</constant>), datagram (<constant>SOCK_DGRAM</constant>), or sequential packet - (SOCK_SEQPACKET) socket, respectively. The address + (<constant>SOCK_SEQPACKET</constant>) socket, respectively. The address can be written in various formats:</para> <para>If the address starts with a - slash (/), it is read as file system - socket in the AF_UNIX socket + slash (<literal>/</literal>), it is read as file system + socket in the <constant>AF_UNIX</constant> socket family.</para> - <para>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 + <para>If the address starts with an at + symbol (<literal>@</literal>), it is read as abstract + namespace socket in the + <constant>AF_UNIX</constant> + family. The <literal>@</literal> is + replaced with a + <constant>NUL</constant> character + before binding. For details, see <citerefentry><refentrytitle>unix</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> <para>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 <varname>BindIPv6Only=</varname> (see below) this @@ -179,13 +184,13 @@ </para> <para>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.</para> <para>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,13 +198,13 @@ setting (see below). </para> - <para>Note that SOCK_SEQPACKET + <para>Note that <constant>SOCK_SEQPACKET</constant> (i.e. <varname>ListenSequentialPacket=</varname>) - is only available for AF_UNIX - sockets. SOCK_STREAM + is only available for <constant>AF_UNIX</constant> + sockets. <constant>SOCK_STREAM</constant> (i.e. <varname>ListenStream=</varname>) when used for IP sockets refers to TCP - sockets, SOCK_DGRAM + sockets, <constant>SOCK_DGRAM</constant> (i.e. <varname>ListenDatagram=</varname>) to UDP.</para> @@ -258,7 +263,7 @@ <listitem><para>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 <constant>AF_NETLINK</constant> family name (such as <varname>audit</varname> or <varname>kobject-uevent</varname>) as argument, optionally suffixed by a @@ -298,7 +303,7 @@ <option>ipv6-only</option>, they will be accessible via IPv6 only. If <option>default</option> (which is the - default, surprise!) the system wide + default, surprise!), the system wide default setting is used, as controlled by <filename>/proc/sys/net/ipv6/bindv6only</filename>, @@ -325,7 +330,7 @@ <term><varname>BindToDevice=</varname></term> <listitem><para>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 @@ -374,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 <option>false</option>. For performance reasons, it is recommended to write new daemons only in a way that is suitable for - <option>Accept=false</option>. This - option is mostly useful to allow - daemons designed for usage with - <citerefentry><refentrytitle>inetd</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <option>Accept=false</option>. A + daemon listening on an <constant>AF_UNIX</constant> socket + may, but does not need to, call + <citerefentry><refentrytitle>close</refentrytitle><manvolnum>2</manvolnum></citerefentry> + on the received socket before + exiting. However, it must not unlink + the socket from a file system. It + should not invoke + <citerefentry><refentrytitle>shutdown</refentrytitle><manvolnum>2</manvolnum></citerefentry> + on sockets it got with + <varname>Accept=false</varname>, but + it may do so for sockets it got with + <varname>Accept=true</varname> set. + Setting <varname>Accept=true</varname> + is mostly useful to allow daemons + designed for usage with + <citerefentry><refentrytitle>inetd</refentrytitle><manvolnum>8</manvolnum></citerefentry> to work unmodified with systemd socket activation.</para></listitem> </varlistentry> @@ -399,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 <option>Accept=false</option> or datagram sockets. Defaults to 64.</para></listitem> @@ -490,6 +508,17 @@ </varlistentry> <varlistentry> + <term><varname>ReusePort=</varname></term> + <listitem><para>Takes a boolean + value. If true, allows multiple <citerefentry><refentrytitle>bind</refentrytitle><manvolnum>2</manvolnum></citerefentry>s + to this TCP or UDP port. This + controls the SO_REUSEPORT socket + option. See + <citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for details.</para></listitem> + </varlistentry> + + <varlistentry> <term><varname>SmackLabel=</varname></term> <term><varname>SmackLabelIPIn=</varname></term> <term><varname>SmackLabelIPOut=</varname></term> @@ -503,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 <ulink url="https://www.kernel.org/doc/Documentation/security/Smack.txt">Smack.txt</ulink> for details.</para></listitem> @@ -514,7 +543,7 @@ <listitem><para>Takes an integer value. Controls the pipe buffer size of FIFOs configured in this socket - unit. See + unit. See <citerefentry><refentrytitle>fcntl</refentrytitle><manvolnum>2</manvolnum></citerefentry> for details.</para></listitem> </varlistentry> @@ -571,7 +600,7 @@ <term><varname>PassCredentials=</varname></term> <listitem><para>Takes a boolean value. This controls the SO_PASSCRED - socket option, which allows AF_UNIX sockets to + socket option, which allows <constant>AF_UNIX</constant> sockets to receive the credentials of the sending process in an ancillary message. Defaults to @@ -582,10 +611,10 @@ <term><varname>PassSecurity=</varname></term> <listitem><para>Takes a boolean value. This controls the SO_PASSSEC - socket option, which allows AF_UNIX + socket option, which allows <constant>AF_UNIX</constant> sockets to receive the security context of the sending process in an - ancillary message. Defaults to + ancillary message. Defaults to <option>false</option>.</para></listitem> </varlistentry> @@ -609,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 @@ -644,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 + <constant>SIGTERM</constant>, and after another delay of + this time with <constant>SIGKILL</constant>. (See <option>KillMode=</option> in <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>.) Takes a unit-less value in seconds, or a time span value such as "5min @@ -683,12 +712,13 @@ <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry> </para> <para> - For more extensive descriptions see the "Systemd for Developers" series: + For more extensive descriptions see the "systemd for Developers" series: <ulink url="http://0pointer.de/blog/projects/socket-activation.html">Socket Activation</ulink>, <ulink url="http://0pointer.de/blog/projects/socket-activation2.html">Socket Activation, part II</ulink>, <ulink url="http://0pointer.de/blog/projects/inetd.html">Converting inetd Services</ulink>, |