--- /dev/null
+<?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>Inherit a socket. Bidirectionally
+ proxy.</refpurpose>
+ </refnamediv>
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>systemd-socket-proxyd</command>
+ <arg choice="opt" rep="repeat">OPTIONS</arg>
+ <arg choice="plain"><replaceable>HOSTNAME-OR-IP</replaceable></arg>
+ <arg choice="plain"><replaceable>PORT-OR-SERVICE</replaceable></arg>
+ </cmdsynopsis>
+ <cmdsynopsis>
+ <command>systemd-socket-proxyd</command>
+ <arg choice="opt" rep="repeat">OPTIONS</arg>
+ <arg choice="plain"><replaceable>UNIX-DOMAIN-SOCKET-PATH</replaceable>
+ </arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+ <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>
+ <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>
+ <varlistentry>
+ <term><option>--ignore-env</option></term>
+ <listitem>
+ <para>Skips verification of
+ the expected PID and file
+ descriptor numbers. Use if
+ invoked indirectly, for
+ example with a shell script
+ rather than with
+ <option>ExecStart=/usr/bin/systemd-socket-proxyd</option>
+ </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=socket.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[$ sudo systemctl --system daemon-reload
+$ sudo systemctl start proxy-to-nginx.socket
+$ sudo systemctl enable 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=socket.target]]>
+</programlisting>
+ </example>
+ <example label="combined proxy and nginx service unit">
+
+ <title>
+ /etc/systemd/system/proxy-with-nginx.service</title>
+ <programlisting>
+<![CDATA[[Unit]
+After=syslog.target 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
+/usr/bin/systemd-socket-proxyd --ignore-env 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[$ sudo systemctl --system daemon-reload
+$ sudo systemctl start proxy-with-nginx.socket
+$ sudo systemctl enable proxy-with-nginx.socket
+$ curl http://localhost:80/]]>
+</programlisting>
+ </example>
+ </refsect2>
+ </refsect1>
+ <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>
+ </refsect1>
+</refentry>
~ianmdlvl / elogind.git / blobdiff