summaryrefslogtreecommitdiff
path: root/man/systemd-sabridge.xml
diff options
context:
space:
mode:
authorDavid Strauss <david@davidstrauss.net>2013-10-14 16:41:47 -0700
committerDavid Strauss <david@davidstrauss.net>2013-10-15 16:13:30 -0700
commit912b54ad47e1597c1744ccd936368b0eb1468b16 (patch)
tree9c8f762794e18564ceaf343dd412e46535d8b5d6 /man/systemd-sabridge.xml
parentd7d1c8f983599dca6ee30229375215978657c072 (diff)
Add sabridge for socket activation of traditional daemons
Diffstat (limited to 'man/systemd-sabridge.xml')
-rw-r--r--man/systemd-sabridge.xml254
1 files changed, 254 insertions, 0 deletions
diff --git a/man/systemd-sabridge.xml b/man/systemd-sabridge.xml
new file mode 100644
index 0000000000..abeb1a5a4c
--- /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>