d7cefe8b2b
Without this requirement, if proxy-to-nginx.socket was down, and the sysadmin
were to do:
systemctl start proxy-to-nginx.service
then the service would come up without a configured socket, which doesn't make
sense. Normally this isn't how we expect a socket-activated service to start,
but it's possible for an admin to do this (if the .socket were already running,
the systemd-socket-proxyd process will start effectively idle). But the
.service shouldn't end up in a broken state if the .socket isn't already
listening.
Adding the explicit Requires: should ensure that an admin with this
configuration state can't accidentally break their system.
200 lines
7.2 KiB
XML
200 lines
7.2 KiB
XML
<?xml version="1.0"?>
|
|
<!--*-nxml-*-->
|
|
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
|
|
<!--
|
|
This file is part of systemd.
|
|
|
|
Copyright 2013 David Strauss
|
|
|
|
systemd is free software; you can redistribute it and/or modify it
|
|
under the terms of the GNU Lesser General Public License as published by
|
|
the Free Software Foundation; either version 2.1 of the License, or
|
|
(at your option) any later version.
|
|
|
|
systemd is distributed in the hope that it will be useful, but
|
|
WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
|
Lesser General Public License for more details.
|
|
|
|
You should have received a copy of the GNU Lesser General Public License
|
|
along with systemd; If not, see <http://www.gnu.org/licenses/>.
|
|
-->
|
|
<refentry id="systemd-socket-proxyd"
|
|
xmlns:xi="http://www.w3.org/2001/XInclude">
|
|
|
|
<refentryinfo>
|
|
<title>systemd-socket-proxyd</title>
|
|
<productname>systemd</productname>
|
|
<authorgroup>
|
|
<author>
|
|
<contrib>Developer</contrib>
|
|
<firstname>David</firstname>
|
|
<surname>Strauss</surname>
|
|
<email>david@davidstrauss.net</email>
|
|
</author>
|
|
</authorgroup>
|
|
</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=false</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></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.service
|
|
|
|
[Service]
|
|
ExecStart=/usr/lib/systemd/systemd-socket-proxyd /tmp/nginx.sock
|
|
PrivateTmp=yes
|
|
PrivateNetwork=yes]]></programlisting>
|
|
</example>
|
|
<example>
|
|
<title>nginx.conf</title>
|
|
<programlisting>
|
|
<![CDATA[[…]
|
|
server {
|
|
listen unix:/tmp/nginx.sock;
|
|
[…]]]>
|
|
</programlisting>
|
|
</example>
|
|
<example>
|
|
<title>Enabling the proxy</title>
|
|
<programlisting><![CDATA[# systemctl enable --now proxy-to-nginx.socket
|
|
$ curl http://localhost:80/]]></programlisting>
|
|
</example>
|
|
</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.service
|
|
After=proxy-to-nginx.service
|
|
JoinsNamespaceOf=nginx.service
|
|
|
|
[Service]
|
|
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>
|