man: wording and grammar updates

[thirdparty/systemd.git] / man / systemd-socket-proxyd.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>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-IPADDR</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 this if
                                        invoked indirectly, for
                                        example, with a shell script
                                        rather than with
                                        <option>ExecStart=/usr/lib/systemd/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=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[$ 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=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=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>