mirror of
https://github.com/systemd/systemd
synced 2024-11-05 18:25:39 +00:00
195 lines
7.6 KiB
XML
195 lines
7.6 KiB
XML
<?xml version="1.0"?>
|
|
<!--*-nxml-*-->
|
|
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.5/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>
|
|
|
|
<para>Note that <command>systemd-socket-proxyd</command> will not forward socket side channel
|
|
information, i.e. will not forward <constant>SCM_RIGHTS</constant>, <constant>SCM_CREDENTIALS</constant>,
|
|
<constant>SCM_SECURITY</constant>, <constant>SO_PEERCRED</constant>, <constant>SO_PEERPIDFD</constant>,
|
|
<constant>SO_PEERSEC</constant>, <constant>SO_PEERGROUPS</constant> and similar.</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><simplelist type="inline">
|
|
<member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
|
|
<member><citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
|
|
<member><citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
|
|
<member><citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
|
|
<member><citerefentry project='die-net'><refentrytitle>socat</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
|
|
<member><citerefentry project='die-net'><refentrytitle>nginx</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
|
|
<member><citerefentry project='die-net'><refentrytitle>curl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
|
|
</simplelist></para>
|
|
</refsect1>
|
|
</refentry>
|