X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=man%2Fsystemd-socket-proxyd.xml;h=ab80a2b4ba17de823b538d037260907fc419d52d;hp=fcf4aafd60d2d5df9081a5bdffb753c3df581404;hb=93ae25e6fd62b2f87c3dd9ad3e81934eecc48057;hpb=8569a77629949b7818d00eba8eea1d05e2d1fc32

diff --git a/man/systemd-socket-proxyd.xml b/man/systemd-socket-proxyd.xml
index fcf4aafd6..ab80a2b4b 100644
--- a/man/systemd-socket-proxyd.xml
+++ b/man/systemd-socket-proxyd.xml
@@ -20,7 +20,9 @@
   You should have received a copy of the GNU Lesser General Public License
   along with systemd; If not, see <http://www.gnu.org/licenses/>.
 -->
-<refentry id="systemd-socket-proxyd">
+<refentry id="systemd-socket-proxyd"
+          xmlns:xi="http://www.w3.org/2001/XInclude">
+
         <refentryinfo>
                 <title>systemd-socket-proxyd</title>
                 <productname>systemd</productname>
@@ -35,7 +37,7 @@
         </refentryinfo>
         <refmeta>
                 <refentrytitle>systemd-socket-proxyd</refentrytitle>
-                <manvolnum>1</manvolnum>
+                <manvolnum>8</manvolnum>
         </refmeta>
         <refnamediv>
                 <refname>systemd-socket-proxyd</refname>
@@ -59,12 +61,12 @@
                 <para>
                 <command>systemd-socket-proxyd</command> is a generic
                 socket-activated network socket forwarder proxy daemon
-                for IPV4, IPv6 and UNIX stream sockets. It may be used
+                for IPv4, IPv6 and UNIX stream sockets. It may be used
                 to bi-directionally forward traffic from a local listening socket to a
                 local or remote destination socket.</para>
 
                 <para>One use of this tool is to provide
-                socket-activation support for services that do not
+                socket activation support for services that do not
                 natively support socket activation. On behalf of the
                 service to activate, the proxy inherits the socket
                 from systemd, accepts each client connection, opens a
@@ -83,21 +85,8 @@
                 <title>Options</title>
                 <para>The following options are understood:</para>
                 <variablelist>
-                        <varlistentry>
-                                <term><option>-h</option></term>
-                                <term><option>--help</option></term>
-                                <listitem>
-                                        <para>Prints a short help
-                                        text and exits.</para>
-                                </listitem>
-                        </varlistentry>
-                        <varlistentry>
-                                <term><option>--version</option></term>
-                                <listitem>
-                                        <para>Prints a version
-                                        string and exits.</para>
-                                </listitem>
-                        </varlistentry>
+                        <xi:include href="standard-options.xml" xpointer="help" />
+                        <xi:include href="standard-options.xml" xpointer="version" />
                 </variablelist>
         </refsect1>
         <refsect1>
@@ -108,34 +97,30 @@
         <refsect1>
                 <title>Examples</title>
                 <refsect2>
-                        <title>Direct-Use Example</title>
+                        <title>Simple Example</title>
                         <para>Use two services with a dependency
                         and no namespace isolation.</para>
-                        <example label="proxy socket unit">
-                                <title>/etc/systemd/system/proxy-to-nginx.socket</title>
-                                <programlisting>
-<![CDATA[[Socket]
+                        <example>
+                                <title>proxy-to-nginx.socket</title>
+                                <programlisting><![CDATA[[Socket]
 ListenStream=80
 
 [Install]
-WantedBy=sockets.target]]>
-</programlisting>
+WantedBy=sockets.target]]></programlisting>
                         </example>
-                        <example label="proxy service unit">
-                                <title>/etc/systemd/system/proxy-to-nginx.service</title>
-                                <programlisting>
-<![CDATA[[Unit]
-After=nginx.service
+                        <example>
+                                <title>proxy-to-nginx.service</title>
+                                <programlisting><![CDATA[[Unit]
 Requires=nginx.service
+After=nginx.service
 
 [Service]
-ExecStart=/usr/bin/systemd-socket-proxyd /tmp/nginx.sock
-PrivateTmp=true
-PrivateNetwork=true]]>
-</programlisting>
+ExecStart=/usr/lib/systemd/systemd-socket-proxyd /tmp/nginx.sock
+PrivateTmp=yes
+PrivateNetwork=yes]]></programlisting>
                         </example>
-                        <example label="nginx configuration">
-                                <title>/etc/nginx/nginx.conf</title>
+                        <example>
+                                <title>nginx.conf</title>
                                 <programlisting>
 <![CDATA[[...]
 server {
@@ -143,81 +128,55 @@ server {
     [...]]]>
 </programlisting>
                         </example>
-                        <example label="commands">
-                                <programlisting>
-<![CDATA[# systemctl --system daemon-reload
+                        <example>
+                                <title>Enabling the proxy</title>
+                                <programlisting><![CDATA[# systemctl enable proxy-to-nginx.socket
 # systemctl start proxy-to-nginx.socket
-# systemctl enable proxy-to-nginx.socket
-$ curl http://localhost:80/]]>
-</programlisting>
+$ curl http://localhost:80/]]></programlisting>
                         </example>
                 </refsect2>
                 <refsect2>
-                        <title>Indirect-Use Example</title>
-                        <para>Use a shell script to isolate the
-                        service and proxy into the same namespace.
-                        This is particularly useful for running
-                        TCP-only daemons without the daemon
-                        affecting ports on regular
-                        interfaces.</para>
-                        <example label="combined proxy and nginx socket unit">
-
-                                <title>
-                                /etc/systemd/system/proxy-with-nginx.socket</title>
-                                <programlisting>
-<![CDATA[[Socket]
+                        <title>Namespace Example</title>
+                        <para>Similar as above, but runs the socket
+                        proxy and the main service in the same private
+                        namespace, assuming that
+                        <filename>nginx.service</filename> has
+                        <varname>PrivateTmp=</varname> and
+                        <varname>PrivateNetwork=</varname> set,
+                        too.</para>
+                        <example>
+                                <title>proxy-to-nginx.socket</title>
+                                <programlisting><![CDATA[[Socket]
 ListenStream=80
 
 [Install]
-WantedBy=sockets.target]]>
-</programlisting>
+WantedBy=sockets.target]]></programlisting>
                         </example>
-                        <example label="combined proxy and nginx service unit">
-
-                                <title>
-                                /etc/systemd/system/proxy-with-nginx.service</title>
-                                <programlisting>
-<![CDATA[[Unit]
-After=syslog.target remote-fs.target nss-lookup.target
+                        <example>
+                                <title>proxy-to-nginx.service</title>
+                                <programlisting><![CDATA[[Unit]
+Requires=nginx.service
+After=nginx.service
+JoinsNamespaceOf=nginx.service
 
 [Service]
-ExecStartPre=/usr/sbin/nginx -t
-ExecStart=/usr/bin/socket-proxyd-nginx.sh
-PrivateTmp=true
-PrivateNetwork=true]]>
-</programlisting>
+ExecStart=/usr/lib/systemd/systemd-socket-proxyd 127.0.0.1:8080
+PrivateTmp=yes
+PrivateNetwork=yes]]></programlisting>
                         </example>
-                        <example label="shell script">
-                                <title>
-                                /usr/bin/socket-proxyd-nginx.sh</title>
-                                <programlisting>
-<![CDATA[#!/bin/sh
-/usr/sbin/nginx
-while [ ! -f /tmp/nginx.pid ]
-  do
-     /usr/bin/inotifywait /tmp/nginx.pid
-  done
-exec /usr/bin/systemd-socket-proxyd localhost 8080]]>
-</programlisting>
-                        </example>
-                        <example label="nginx configuration">
-                                <title>
-                                /etc/nginx/nginx.conf</title>
-                                <programlisting>
-<![CDATA[[...]
+                        <example>
+                                <title>nginx.conf</title>
+                                <programlisting><![CDATA[[...]
 server {
     listen       8080;
     listen       unix:/tmp/nginx.sock;
-    [...]]]>
-</programlisting>
+    [...]]]></programlisting>
                         </example>
-                        <example label="commands">
-                                <programlisting>
-<![CDATA[# systemctl --system daemon-reload
-# systemctl start proxy-with-nginx.socket
-# systemctl enable proxy-with-nginx.socket
-$ curl http://localhost:80/]]>
-</programlisting>
+                        <example>
+                                <title>Enabling the proxy</title>
+                                <programlisting><![CDATA[# systemctl enable proxy-to-nginx.socket
+# systemctl start proxy-to-nginx.socket
+$ curl http://localhost:80/]]></programlisting>
                         </example>
                 </refsect2>
         </refsect1>
@@ -228,7 +187,9 @@ $ curl http://localhost:80/]]>
                         <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
-                        <citerefentry><refentrytitle>socat</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+                        <citerefentry><refentrytitle>socat</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+                        <citerefentry><refentrytitle>nginx</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+                        <citerefentry><refentrytitle>curl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
                 </para>
         </refsect1>
 </refentry>