summaryrefslogtreecommitdiffstats
path: root/man/systemd-socket-proxyd.xml
diff options
context:
space:
mode:
Diffstat (limited to 'man/systemd-socket-proxyd.xml')
-rw-r--r--man/systemd-socket-proxyd.xml190
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>