233 lines
9.7 KiB
XML
233 lines
9.7 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">
|
|
<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>1</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><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>
|
|
<varlistentry>
|
|
<term><option>-h</option></term>
|
|
<term><option>--help</option></term>
|
|
<listitem>
|
|
<para>Prints a short help
|
|
text and exits.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>--version</option></term>
|
|
<listitem>
|
|
<para>Prints a version
|
|
string and exits.</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>Direct-Use Example</title>
|
|
<para>Use two services with a dependency
|
|
and no namespace isolation.</para>
|
|
<example label="proxy socket unit">
|
|
<title>/etc/systemd/system/proxy-to-nginx.socket</title>
|
|
<programlisting>
|
|
<![CDATA[[Socket]
|
|
ListenStream=80
|
|
|
|
[Install]
|
|
WantedBy=sockets.target]]>
|
|
</programlisting>
|
|
</example>
|
|
<example label="proxy service unit">
|
|
<title>/etc/systemd/system/proxy-to-nginx.service</title>
|
|
<programlisting>
|
|
<![CDATA[[Unit]
|
|
After=nginx.service
|
|
Requires=nginx.service
|
|
|
|
[Service]
|
|
ExecStart=/usr/bin/systemd-socket-proxyd /tmp/nginx.sock
|
|
PrivateTmp=true
|
|
PrivateNetwork=true]]>
|
|
</programlisting>
|
|
</example>
|
|
<example label="nginx configuration">
|
|
<title>/etc/nginx/nginx.conf</title>
|
|
<programlisting>
|
|
<![CDATA[[...]
|
|
server {
|
|
listen unix:/tmp/nginx.sock;
|
|
[...]]]>
|
|
</programlisting>
|
|
</example>
|
|
<example label="commands">
|
|
<programlisting>
|
|
<![CDATA[# systemctl enable proxy-to-nginx.socket
|
|
# systemctl start proxy-to-nginx.socket
|
|
$ curl http://localhost:80/]]>
|
|
</programlisting>
|
|
</example>
|
|
</refsect2>
|
|
<refsect2>
|
|
<title>Indirect-Use Example</title>
|
|
<para>Use a shell script to isolate the
|
|
service and proxy into the same namespace.
|
|
This is particularly useful for running
|
|
TCP-only daemons without the daemon
|
|
affecting ports on regular
|
|
interfaces.</para>
|
|
<example label="combined proxy and nginx socket unit">
|
|
|
|
<title>
|
|
/etc/systemd/system/proxy-with-nginx.socket</title>
|
|
<programlisting>
|
|
<![CDATA[[Socket]
|
|
ListenStream=80
|
|
|
|
[Install]
|
|
WantedBy=sockets.target]]>
|
|
</programlisting>
|
|
</example>
|
|
<example label="combined proxy and nginx service unit">
|
|
|
|
<title>
|
|
/etc/systemd/system/proxy-with-nginx.service</title>
|
|
<programlisting>
|
|
<![CDATA[[Unit]
|
|
After=remote-fs.target nss-lookup.target
|
|
|
|
[Service]
|
|
ExecStartPre=/usr/sbin/nginx -t
|
|
ExecStart=/usr/bin/socket-proxyd-nginx.sh
|
|
PrivateTmp=true
|
|
PrivateNetwork=true]]>
|
|
</programlisting>
|
|
</example>
|
|
<example label="shell script">
|
|
<title>
|
|
/usr/bin/socket-proxyd-nginx.sh</title>
|
|
<programlisting>
|
|
<![CDATA[#!/bin/sh
|
|
/usr/sbin/nginx
|
|
while [ ! -f /tmp/nginx.pid ]
|
|
do
|
|
/usr/bin/inotifywait /tmp/nginx.pid
|
|
done
|
|
exec /usr/bin/systemd-socket-proxyd localhost 8080]]>
|
|
</programlisting>
|
|
</example>
|
|
<example label="nginx configuration">
|
|
<title>
|
|
/etc/nginx/nginx.conf</title>
|
|
<programlisting>
|
|
<![CDATA[[...]
|
|
server {
|
|
listen 8080;
|
|
listen unix:/tmp/nginx.sock;
|
|
[...]]]>
|
|
</programlisting>
|
|
</example>
|
|
<example label="commands">
|
|
<programlisting>
|
|
<![CDATA[# systemctl enable proxy-with-nginx.socket
|
|
# systemctl start proxy-with-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><refentrytitle>socat</refentrytitle><manvolnum>1</manvolnum></citerefentry>
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|