<surname>Strauss</surname>
<email>david@davidstrauss.net</email>
</author>
+ <author>
+ <contrib>Developer</contrib>
+ <firstname>Lennart</firstname>
+ <surname>Poettering</surname>
+ <email>lennart@poettering.net</email>
+ </author>
</authorgroup>
</refentryinfo>
<refmeta>
</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-IPADDR</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>
<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>.
The main differences for <command>systemd-socket-proxyd</command>
<title>Options</title>
<para>The following options are understood:</para>
<variablelist>
+ <varlistentry>
+ <term><option>-l</option></term>
+ <term><option>--listener=</option></term>
+ <listitem>
+ <para>Restricts listening to a
+ single inherited socket, specified
+ as a file descriptor. By default,
+ the proxy listens on all inherited
+ sockets.</para>
+ </listitem>
+ </varlistentry>
<varlistentry>
<term><option>-h</option></term>
<term><option>--help</option></term>
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 this if
- invoked indirectly, for
- example, with a shell script
- rather than with
- <option>ExecStart=/usr/lib/systemd/systemd-socket-proxyd</option>
- </para>
- </listitem>
- </varlistentry>
</variablelist>
</refsect1>
<refsect1>
</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>
/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
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>
+ <para>Make it executable:</para>
+ <programlisting>
+<![CDATA[chmod 755 /usr/bin/socket-proxyd-nginx.sh]]>
+ </programlisting>
</example>
<example label="nginx configuration">
<title>
</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>
+ </refsect2>
+
+ <refsect2>
+ <title>Multiple Listeners with Multiple Destinations</title>
+ <para>When using namespaces, it may be useful to
+ have multiple listeners with each going to a unique
+ destination. systemd always passes sockets into
+ services in the order specified in the socket
+ unit, beginning with file descriptor 3.</para>
+ <para>In this example, port <literal>80</literal>
+ will proxy to <literal>localhost:8080</literal>,
+ and port <literal>443</literal> will proxy to
+ <literal>localhost:8443</literal>.</para>
+ <example label="proxy socket unit">
+ <title>/etc/systemd/system/multi-destination.socket</title>
+ <programlisting>
+<![CDATA[[Socket]
+ListenStream=80
+ListenStream=443
+
+[Install]
+WantedBy=sockets.target]]>
+</programlisting>
+ </example>
+ <example label="proxy service unit">
+ <title>/etc/systemd/system/multi-destination.service</title>
+ <programlisting>
+<![CDATA[[Service]
+ExecStart=/usr/bin/socket-proxyd-multi-destination.sh
+PrivateTmp=true
+PrivateNetwork=true]]>
+</programlisting>
+ </example>
+
+ <example label="shell script">
+ <title>
+ /usr/bin/socket-proxyd-multi-destination.sh</title>
+ <programlisting>
+<![CDATA[#!/bin/sh
+/usr/bin/systemd-socket-proxyd --listener=3 localhost:8080 &
+/usr/bin/systemd-socket-proxyd --listener=4 localhost:8443 &
+wait]]>
+</programlisting>
+ <para>Make it executable:</para>
+ <programlisting>
+<![CDATA[chmod 755 /usr/bin/socket-proxyd-multi-destination.sh]]>
+ </programlisting>
+ </example>
+
+ <example label="commands">
+ <programlisting>
+<![CDATA[# systemctl enable multi-destination.socket
+# systemctl start multi-destination.socket
+$ curl http://localhost/
+$ curl https://localhost/]]>
</programlisting>
</example>
</refsect2>
<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>