From 204a710b647527c35cee26962bbd324e6cebc822 Mon Sep 17 00:00:00 2001

From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= <zbyszek@in.waw.pl>

Date: Mon, 30 Dec 2013 00:11:30 -0500

Subject: [PATCH] man: expand on some more subtle points in systemd.socket(5)

http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=727708#1694

---

 man/systemd.socket.xml | 67 ++++++++++++++++++++++++++++++++++++--------------

 1 file changed, 49 insertions(+), 18 deletions(-)

diff --git a/man/systemd.socket.xml b/man/systemd.socket.xml

index ac3127d..570a6fb 100644

--- a/man/systemd.socket.xml

+++ b/man/systemd.socket.xml

@@ -85,21 +85,26 @@

                 processes of the socket.</para>

                 <para>For each socket file a matching service file

-                (see

+                must exist, describing the service to start on

+                incoming traffic on the socket (see

                 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>

-                for details) must exist, describing the service to

-                start on incoming traffic on the socket. Depending on

-                the setting of <option>Accept=</option> (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>Service=</option> option described below.

+                Depending on the setting of <option>Accept=</option>

+                option described below, this .service unit must either

+                be named like the .socket unit, but with the suffix

+                replaced, unless overridden with

+                <option>Service=</option>; or it must be a template

+                unit named the same way. Example: a socket file

                 <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

-                file <filename>foo@.service</filename> must exist from

-                which services are instantiated for each incoming

-                connection.</para>

+                <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>

                 <para>Unless <varname>DefaultDependencies=</varname>

                 is set to <option>false</option>, socket units will

@@ -116,9 +121,21 @@

                 boot or late system shutdown should disable this

                 option.</para>

+		<para>Socket units will have a

+		<varname>Before=</varname> dependency on the service

+		which they trigger added implicitly. No implicit

+		<varname>WantedBy=</varname> or

+		<varname>RequiredBy=</varname> 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 <varname>Requires=</varname>

+		dependency may be added.</para>

+

                 <para>Socket units may be used to implement on-demand

                 starting of services, as well as parallelized starting

-                of services.</para>

+                of services. See the blog stories linked at the end

+                for introduction.</para>

                 <para>Note that the daemon software configured for

                 socket activation with socket units needs to be able

@@ -221,12 +238,23 @@

                                 of any of these options will have no

                                 effect.</para>

+                                <para>It is also possible to have more

+                                than one socket unit for the same

+                                service when using

+                                <varname>Service=</varname>, 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.</para>

+

                                 <para>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 of whether it will be up and

-                                running ever at all. To deal with this

+                                running at any point. To deal with this

                                 it is recommended to set the

                                 <varname>FreeBind=</varname> option

                                 described below.</para></listitem>

@@ -687,11 +715,14 @@

                                 <term><varname>Service=</varname></term>

                                 <listitem><para>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.</para></listitem>

+                                traffic. This setting is only allowed

+                                for sockets 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>

                         </varlistentry>

                 </variablelist>