Add sabridge for socket activation of traditional daemons

1 files changed, 254 insertions, 0 deletions

diff --git a/man/systemd-sabridge.xml b/man/systemd-sabridge.xml
new file mode 100644
index 000000000..abeb1a5a4
--- /dev/null
+++ b/man/systemd-sabridge.xml
@@ -0,0 +1,254 @@
+<?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-sabridge">
+        <refentryinfo>
+                <title>systemd-sabridge</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-sabridge</refentrytitle>
+                <manvolnum>1</manvolnum>
+        </refmeta>
+        <refnamediv>
+                <refname>systemd-sabridge</refname>
+                <refpurpose>Inherit a socket. Bidirectionally
+                proxy.</refpurpose>
+        </refnamediv>
+        <refsynopsisdiv>
+                <cmdsynopsis>
+                        <command>systemd-sabridge</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-sabridge</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-sabridge</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-sabridge</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-sabridge</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="bridge socket unit">
+                                <title>/etc/systemd/system/bridge-to-nginx.socket</title>
+                                <programlisting>
+<![CDATA[[Socket]
+ListenStream=80
+
+[Install]
+WantedBy=socket.target]]>
+</programlisting>
+                        </example>
+                        <example label="bridge service unit">
+                                <title>/etc/systemd/system/bridge-to-nginx.service</title>
+                                <programlisting>
+<![CDATA[[Unit]
+After=nginx.service
+Requires=nginx.service
+
+[Service]
+ExecStart=/usr/bin/systemd-sabridge /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 bridge-to-nginx.socket
+$ sudo systemctl enable bridge-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 bridge 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 bridge and nginx socket unit">
+
+                                <title>
+                                /etc/systemd/system/bridge-with-nginx.socket</title>
+                                <programlisting>
+<![CDATA[[Socket]
+ListenStream=80
+
+[Install]
+WantedBy=socket.target]]>
+</programlisting>
+                        </example>
+                        <example label="combined bridge and nginx service unit">
+
+                                <title>
+                                /etc/systemd/system/bridge-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/sabridge-nginx.sh
+PrivateTmp=true
+PrivateNetwork=true]]>
+</programlisting>
+                        </example>
+                        <example label="shell script">
+                                <title>
+                                /usr/bin/sabridge-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-sabridge --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 bridge-with-nginx.socket
+$ sudo systemctl enable bridge-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>