+++ /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-saproxy">
- <refentryinfo>
- <title>systemd-saproxy</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-saproxy</refentrytitle>
- <manvolnum>1</manvolnum>
- </refmeta>
- <refnamediv>
- <refname>systemd-saproxy</refname>
- <refpurpose>Inherit a socket. Bidirectionally
- proxy.</refpurpose>
- </refnamediv>
- <refsynopsisdiv>
- <cmdsynopsis>
- <command>systemd-saproxy</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-saproxy</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-saproxy</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-saproxy</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-saproxy</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-saproxy /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/saproxy-nginx.sh
-PrivateTmp=true
-PrivateNetwork=true]]>
-</programlisting>
- </example>
- <example label="shell script">
- <title>
- /usr/bin/saproxy-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-saproxy --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