Adding upstream version 255.4.upstream/255.4

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 190 insertions, 0 deletions

diff --git a/man/systemd-socket-proxyd.xml b/man/systemd-socket-proxyd.xml
new file mode 100644
index 0000000..57a6827
--- /dev/null
+++ b/man/systemd-socket-proxyd.xml
@@ -0,0 +1,190 @@
+<?xml version="1.0"?>
+<!--*-nxml-*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
+<refentry id="systemd-socket-proxyd"
+    xmlns:xi="http://www.w3.org/2001/XInclude">
+
+  <refentryinfo>
+    <title>systemd-socket-proxyd</title>
+    <productname>systemd</productname>
+  </refentryinfo>
+  <refmeta>
+    <refentrytitle>systemd-socket-proxyd</refentrytitle>
+    <manvolnum>8</manvolnum>
+  </refmeta>
+  <refnamediv>
+    <refname>systemd-socket-proxyd</refname>
+    <refpurpose>Bidirectionally proxy local sockets to another (possibly remote) socket</refpurpose>
+  </refnamediv>
+  <refsynopsisdiv>
+    <cmdsynopsis>
+      <command>systemd-socket-proxyd</command>
+      <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"><replaceable>OPTIONS</replaceable></arg>
+      <arg choice="plain"><replaceable>UNIX-DOMAIN-SOCKET-PATH</replaceable>
+      </arg>
+    </cmdsynopsis>
+  </refsynopsisdiv>
+  <refsect1>
+    <title>Description</title>
+    <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 project='die-net'><refentrytitle>socat</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
+    The main differences for <command>systemd-socket-proxyd</command>
+    are support for socket activation with
+    <literal>Accept=no</literal> and an event-driven
+    design that scales better with the number of
+    connections.</para>
+  </refsect1>
+  <refsect1>
+    <title>Options</title>
+    <para>The following options are understood:</para>
+    <variablelist>
+      <xi:include href="standard-options.xml" xpointer="help" />
+      <xi:include href="standard-options.xml" xpointer="version" />
+      <varlistentry>
+        <term><option>--connections-max=</option></term>
+        <term><option>-c</option></term>
+
+        <listitem><para>Sets the maximum number of simultaneous connections, defaults to 256.
+        If the limit of concurrent connections is reached further connections will be refused.</para>
+
+        <xi:include href="version-info.xml" xpointer="v233"/></listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><option>--exit-idle-time=</option></term>
+
+        <listitem><para>Sets the time before exiting when there are no connections, defaults to
+        <constant>infinity</constant>. Takes a unit-less value in seconds, or a time span value such
+        as <literal>5min 20s</literal>.</para>
+
+        <xi:include href="version-info.xml" xpointer="v246"/></listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+  <refsect1>
+    <title>Exit status</title>
+    <para>On success, 0 is returned, a non-zero failure
+    code otherwise.</para>
+  </refsect1>
+  <refsect1>
+    <title>Examples</title>
+    <refsect2>
+      <title>Simple Example</title>
+      <para>Use two services with a dependency and no namespace
+      isolation.</para>
+      <example>
+        <title>proxy-to-nginx.socket</title>
+        <programlisting><![CDATA[[Socket]
+ListenStream=80
+
+[Install]
+WantedBy=sockets.target]]></programlisting>
+      </example>
+      <example>
+        <title>proxy-to-nginx.service</title>
+        <programlisting><![CDATA[[Unit]
+Requires=nginx.service
+After=nginx.service
+Requires=proxy-to-nginx.socket
+After=proxy-to-nginx.socket
+
+[Service]
+Type=notify
+ExecStart=/usr/lib/systemd/systemd-socket-proxyd /run/nginx/socket
+PrivateTmp=yes
+PrivateNetwork=yes]]></programlisting>
+      </example>
+      <example>
+        <title>nginx.conf</title>
+        <programlisting>
+<![CDATA[[…]
+server {
+    listen       unix:/run/nginx/socket;
+    […]]]>
+</programlisting>
+      </example>
+      <example>
+        <title>Enabling the proxy</title>
+        <programlisting><![CDATA[# systemctl enable --now proxy-to-nginx.socket
+$ curl http://localhost:80/]]></programlisting>
+      </example>
+      <para>If <filename>nginx.service</filename> has <varname>StopWhenUnneeded=</varname> set, then
+      passing <option>--exit-idle-time=</option> to <command>systemd-socket-proxyd</command> allows
+      both services to stop during idle periods.</para>
+    </refsect2>
+    <refsect2>
+      <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>
+      </example>
+      <example>
+        <title>proxy-to-nginx.service</title>
+        <programlisting><![CDATA[[Unit]
+Requires=nginx.service
+After=nginx.service
+Requires=proxy-to-nginx.socket
+After=proxy-to-nginx.socket
+JoinsNamespaceOf=nginx.service
+
+[Service]
+Type=notify
+ExecStart=/usr/lib/systemd/systemd-socket-proxyd 127.0.0.1:8080
+PrivateTmp=yes
+PrivateNetwork=yes]]></programlisting>
+      </example>
+      <example>
+        <title>nginx.conf</title>
+        <programlisting><![CDATA[[…]
+server {
+    listen       8080;
+    […]]]></programlisting>
+      </example>
+      <example>
+        <title>Enabling the proxy</title>
+        <programlisting><![CDATA[# systemctl enable --now proxy-to-nginx.socket
+$ curl http://localhost:80/]]></programlisting>
+      </example>
+    </refsect2>
+  </refsect1>
+  <refsect1>
+    <title>See Also</title>
+    <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 project='die-net'><refentrytitle>socat</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+      <citerefentry project='die-net'><refentrytitle>nginx</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+      <citerefentry project='die-net'><refentrytitle>curl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+    </para>
+  </refsect1>
+</refentry>