diff options
Diffstat (limited to 'man/systemd.socket.xml')
| -rw-r--r-- | man/systemd.socket.xml | 96 |
1 files changed, 80 insertions, 16 deletions
diff --git a/man/systemd.socket.xml b/man/systemd.socket.xml index 212764075d..43841c2399 100644 --- a/man/systemd.socket.xml +++ b/man/systemd.socket.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*-nxml-*--> +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -134,6 +134,40 @@ </refsect1> <refsect1> + <title>Automatic Dependencies</title> + + <para>Socket units automatically gain a <varname>Before=</varname> + dependency on the service units they activate.</para> + + <para>Socket units referring to file system paths (such as AF_UNIX + sockets or FIFOs) implicitly gain <varname>Requires=</varname> and + <varname>After=</varname> dependencies on all mount units + necessary to access those paths.</para> + + <para>Socket units using the <varname>BindToDevice=</varname> + setting automatically gain a <varname>BindsTo=</varname> and + <varname>After=</varname> dependency on the device unit + encapsulating the specified network interface.</para> + + <para>If <varname>DefaultDependencies=yes</varname> is set (the + default), socket units automatically gain a + <varname>Before=</varname> dependency on + <filename>sockets.target</filename>. They also gain a pair of + <varname>After=</varname> and <varname>Requires=</varname> + dependency on <filename>sysinit.target</filename>, and a pair of + <varname>Before=</varname> and <varname>Conflicts=</varname> + dependencies on <filename>shutdown.target</filename>. These + dependencies ensure that the socket unit is started before normal + services at boot, and is stopped on shutdown.</para> + + <para>Additional implicit dependencies may be added as result of + execution and resource control parameters as documented in + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + </refsect1> + + <refsect1> <title>Options</title> <para>Socket files must include a [Socket] section, which carries @@ -194,7 +228,7 @@ refers to TCP sockets, <constant>SOCK_DGRAM</constant> (i.e. <varname>ListenDatagram=</varname>) to UDP.</para> - <para>These options may be specified more than once in which + <para>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 of whether there is incoming traffic @@ -268,7 +302,7 @@ implementation of USB gadget functions. This expects an absolute file system path as the argument. Behavior otherwise is very similar to the <varname>ListenFIFO=</varname> - directive above. Use this to open FunctionFS endpoint + directive above. Use this to open the FunctionFS endpoint <filename>ep0</filename>. When using this option, the activated service has to have the <varname>USBFunctionDescriptors=</varname> and @@ -277,6 +311,15 @@ </varlistentry> <varlistentry> + <term><varname>SocketProtocol=</varname></term> + <listitem><para>Takes a one of <option>udplite</option> + or <option>sctp</option>. Specifies a socket protocol + (<constant>IPPROTO_UDPLITE</constant>) UDP-Lite + (<constant>IPPROTO_SCTP</constant>) SCTP socket respectively. </para> + </listitem> + </varlistentry> + + <varlistentry> <term><varname>BindIPv6Only=</varname></term> <listitem><para>Takes a one of <option>default</option>, <option>both</option> or <option>ipv6-only</option>. Controls @@ -309,12 +352,14 @@ <listitem><para>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 - <citerefentry project='man-pages'><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry> + SO_BINDTODEVICE socket option (see <citerefentry + project='man-pages'><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry> for details). If this option is used, an automatic dependency from this socket unit on the network interface device unit (<citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry> - is created.</para></listitem> + is created. Note that setting this parameter might result in + additional dependencies to be added to the unit (see + above).</para></listitem> </varlistentry> <varlistentry> @@ -375,10 +420,10 @@ to work unmodified with systemd socket activation.</para> - <para>For IPv4 and IPv6 connections the <varname>REMOTE_ADDR</varname> - environment variable will contain the remote IP, and <varname>REMOTE_PORT</varname> + <para>For IPv4 and IPv6 connections, the <varname>REMOTE_ADDR</varname> + environment variable will contain the remote IP address, and <varname>REMOTE_PORT</varname> will contain the remote port. This is the same as the format used by CGI. - For SOCK_RAW the port is the IP protocol.</para></listitem> + For SOCK_RAW, the port is the IP protocol.</para></listitem> </varlistentry> <varlistentry> @@ -386,7 +431,7 @@ <listitem><para>Takes a boolean argument. May only be used in conjunction with <varname>ListenSpecial=</varname>. If true, the specified special file is opened in read-write mode, if - false in read-only mode. Defaults to false.</para></listitem> + false, in read-only mode. Defaults to false.</para></listitem> </varlistentry> <varlistentry> @@ -418,7 +463,7 @@ <varlistentry> <term><varname>KeepAliveTimeSec=</varname></term> - <listitem><para>Takes time (in seconds) as argument . The connection needs to remain + <listitem><para>Takes time (in seconds) as argument. The connection needs to remain idle before TCP starts sending keepalive probes. This controls the TCP_KEEPIDLE socket option (see <citerefentry project='man-pages'><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry> @@ -432,7 +477,7 @@ <term><varname>KeepAliveIntervalSec=</varname></term> <listitem><para>Takes time (in seconds) as argument between individual keepalive probes, if the socket option SO_KEEPALIVE - has been set on this socket seconds as argument. This controls + has been set on this socket. This controls the TCP_KEEPINTVL socket option (see <citerefentry project='man-pages'><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry> and the <ulink @@ -443,7 +488,7 @@ <varlistentry> <term><varname>KeepAliveProbes=</varname></term> - <listitem><para>Takes integer as argument. It's the number of + <listitem><para>Takes an integer as argument. It is the number of unacknowledged probes to send before considering the connection dead and notifying the application layer. This controls the TCP_KEEPCNT socket option (see @@ -719,7 +764,9 @@ with <varname>Accept=no</varname>. 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.</para></listitem> + this option. Note that setting this parameter might result in + additional dependencies to be added to the unit (see + above).</para></listitem> </varlistentry> <varlistentry> @@ -748,6 +795,22 @@ list.</para></listitem> </varlistentry> + <varlistentry> + <term><varname>FileDescriptorName=</varname></term> + <listitem><para>Assigns a name to all file descriptors this + socket unit encapsulates. This is useful to help activated + services identify specific file descriptors, if multiple fds + are passed. Services may use the + <citerefentry><refentrytitle>sd_listen_fds_with_names</refentrytitle><manvolnum>3</manvolnum></citerefentry> + call to acquire the names configured for the received file + descriptors. Names may contain any ASCII character, but must + exclude control characters and <literal>:</literal>, and must + be at most 255 characters in length. If this setting is not + used, the file descriptor name defaults to the name of the + socket unit, including its <filename>.socket</filename> + suffix.</para></listitem> + </varlistentry> + </variablelist> <para>Check @@ -768,9 +831,10 @@ <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> + <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_listen_fds_with_names</refentrytitle><manvolnum>3</manvolnum></citerefentry> </para> - <para> For more extensive descriptions see the "systemd for Developers" series: <ulink url="http://0pointer.de/blog/projects/socket-activation.html">Socket Activation</ulink>, |