X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=man%2Fsystemd-socket-proxyd.xml;h=4eb13e4d2526577ac2547ebd689d2fe4359e99eb;hp=90b3b1c3a4f087a2ed36049640c1a3af72e92d93;hb=8cf030b349cbcb0901d880c9165d785dfc9cd569;hpb=96c374d0a536286e18cad64d1b5ebb8f07c90334

diff --git a/man/systemd-socket-proxyd.xml b/man/systemd-socket-proxyd.xml
index 90b3b1c3a..4eb13e4d2 100644
--- a/man/systemd-socket-proxyd.xml
+++ b/man/systemd-socket-proxyd.xml
@@ -39,19 +39,17 @@
         </refmeta>
         <refnamediv>
                 <refname>systemd-socket-proxyd</refname>
-                <refpurpose>Inherit a socket. Bidirectionally
-                proxy.</refpurpose>
+                <refpurpose>Bidirectionally proxy local sockets to another (possibly remote) socket.</refpurpose>
         </refnamediv>
         <refsynopsisdiv>
                 <cmdsynopsis>
                         <command>systemd-socket-proxyd</command>
-                        <arg choice="opt" rep="repeat">OPTIONS</arg>
-                        <arg choice="plain"><replaceable>HOSTNAME-OR-IP</replaceable></arg>
-                        <arg choice="plain"><replaceable>PORT-OR-SERVICE</replaceable></arg>
+                        <arg choice="opt" rep="repeat"><replaceable>OPTIONS</replaceable></arg>
+                        <arg choice="plain"><replaceable>HOST</replaceable>:<replaceable>PORT</replaceable></arg>
                 </cmdsynopsis>
                 <cmdsynopsis>
                         <command>systemd-socket-proxyd</command>
-                        <arg choice="opt" rep="repeat">OPTIONS</arg>
+                        <arg choice="opt" rep="repeat"><replaceable>OPTIONS</replaceable></arg>
                         <arg choice="plain"><replaceable>UNIX-DOMAIN-SOCKET-PATH</replaceable>
                         </arg>
                 </cmdsynopsis>
@@ -59,15 +57,22 @@
         <refsect1>
                 <title>Description</title>
                 <para>
-                <command>systemd-socket-proxyd</command> provides a proxy
-                to socket-activate services that do not yet support
-                native socket activation. On behalf of the daemon,
-                the proxy inherits the socket from systemd, accepts
-                each client connection, opens a connection to the server
-                for each client, and then bidirectionally forwards
-                data between the two.</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
+                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
+                natively support socket activation. On behalf of the
+                service to activate, the proxy inherits the socket
+                from systemd, accepts each client connection, opens a
+                connection to a configured server for each client, and
+                then bidirectionally forwards data between the
+                two.</para>
                 <para>This utility's behavior is similar to
-                <citerefentry><refentrytitle>socat</refentrytitle><manvolnum>1</manvolnum> </citerefentry>.
+                <citerefentry><refentrytitle>socat</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
                 The main differences for <command>systemd-socket-proxyd</command>
                 are support for socket activation with
                 <literal>Accept=false</literal> and an event-driven
@@ -93,24 +98,11 @@
                                         string and exits.</para>
                                 </listitem>
                         </varlistentry>
-                        <varlistentry>
-                                <term><option>--ignore-env</option></term>
-                                <listitem>
-                                        <para>Skips verification of
-                                        the expected PID and file
-                                        descriptor numbers. Use if
-                                        invoked indirectly, for
-                                        example with a shell script
-                                        rather than with
-                                        <option>ExecStart=/usr/bin/systemd-socket-proxyd</option>
-                                        </para>
-                                </listitem>
-                        </varlistentry>
                 </variablelist>
         </refsect1>
         <refsect1>
                 <title>Exit status</title>
-                <para>On success 0 is returned, a non-zero failure
+                <para>On success, 0 is returned, a non-zero failure
                 code otherwise.</para>
         </refsect1>
         <refsect1>
@@ -126,7 +118,7 @@
 ListenStream=80
 
 [Install]
-WantedBy=socket.target]]>
+WantedBy=sockets.target]]>
 </programlisting>
                         </example>
                         <example label="proxy service unit">
@@ -153,9 +145,8 @@ server {
                         </example>
                         <example label="commands">
                                 <programlisting>
-<![CDATA[$ sudo systemctl --system daemon-reload
-$ sudo systemctl start proxy-to-nginx.socket
-$ sudo systemctl enable proxy-to-nginx.socket
+<![CDATA[# systemctl enable proxy-to-nginx.socket
+# systemctl start proxy-to-nginx.socket
 $ curl http://localhost:80/]]>
 </programlisting>
                         </example>
@@ -177,7 +168,7 @@ $ curl http://localhost:80/]]>
 ListenStream=80
 
 [Install]
-WantedBy=socket.target]]>
+WantedBy=sockets.target]]>
 </programlisting>
                         </example>
                         <example label="combined proxy and nginx service unit">
@@ -186,7 +177,7 @@ WantedBy=socket.target]]>
                                 /etc/systemd/system/proxy-with-nginx.service</title>
                                 <programlisting>
 <![CDATA[[Unit]
-After=syslog.target remote-fs.target nss-lookup.target
+After=remote-fs.target nss-lookup.target
 
 [Service]
 ExecStartPre=/usr/sbin/nginx -t
@@ -205,7 +196,7 @@ while [ ! -f /tmp/nginx.pid ]
   do
      /usr/bin/inotifywait /tmp/nginx.pid
   done
-/usr/bin/systemd-socket-proxyd --ignore-env localhost 8080]]>
+exec /usr/bin/systemd-socket-proxyd localhost 8080]]>
 </programlisting>
                         </example>
                         <example label="nginx configuration">
@@ -221,9 +212,8 @@ server {
                         </example>
                         <example label="commands">
                                 <programlisting>
-<![CDATA[$ sudo systemctl --system daemon-reload
-$ sudo systemctl start proxy-with-nginx.socket
-$ sudo systemctl enable proxy-with-nginx.socket
+<![CDATA[# systemctl enable proxy-with-nginx.socket
+# systemctl start proxy-with-nginx.socket
 $ curl http://localhost:80/]]>
 </programlisting>
                         </example>
@@ -232,23 +222,11 @@ $ curl http://localhost:80/]]>
         <refsect1>
                 <title>See Also</title>
                 <para>
-                <citerefentry>
-                        <refentrytitle>
-                        systemd.service</refentrytitle>
-                        <manvolnum>5</manvolnum>
-                </citerefentry>,
-                <citerefentry>
-                        <refentrytitle>
-                        systemd.socket</refentrytitle>
-                        <manvolnum>5</manvolnum>
-                </citerefentry>,
-                <citerefentry>
-                        <refentrytitle>systemctl</refentrytitle>
-                        <manvolnum>1</manvolnum>
-                </citerefentry>,
-                <citerefentry>
-                        <refentrytitle>socat</refentrytitle>
-                        <manvolnum>1</manvolnum>
-                </citerefentry></para>
+                        <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+                        <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>
+                </para>
         </refsect1>
 </refentry>