man/systemd-socket-proxyd.xml

   1 <?xml version="1.0"?>
   2 <!--*-nxml-*-->
   3 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   4      "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   5 <!--
   6   SPDX-License-Identifier: LGPL-2.1+
   7
   8   This file is part of systemd.
   9
  10   Copyright 2013 David Strauss
  11 -->
  12 <refentry id="systemd-socket-proxyd"
  13     xmlns:xi="http://www.w3.org/2001/XInclude">
  14
  15   <refentryinfo>
  16     <title>systemd-socket-proxyd</title>
  17     <productname>systemd</productname>
  18     <authorgroup>
  19       <author>
  20         <contrib>Developer</contrib>
  21         <firstname>David</firstname>
  22         <surname>Strauss</surname>
  23         <email>david@davidstrauss.net</email>
  24       </author>
  25     </authorgroup>
  26   </refentryinfo>
  27   <refmeta>
  28     <refentrytitle>systemd-socket-proxyd</refentrytitle>
  29     <manvolnum>8</manvolnum>
  30   </refmeta>
  31   <refnamediv>
  32     <refname>systemd-socket-proxyd</refname>
  33     <refpurpose>Bidirectionally proxy local sockets to another (possibly remote) socket.</refpurpose>
  34   </refnamediv>
  35   <refsynopsisdiv>
  36     <cmdsynopsis>
  37       <command>systemd-socket-proxyd</command>
  38       <arg choice="opt" rep="repeat"><replaceable>OPTIONS</replaceable></arg>
  39       <arg choice="plain"><replaceable>HOST</replaceable>:<replaceable>PORT</replaceable></arg>
  40     </cmdsynopsis>
  41     <cmdsynopsis>
  42       <command>systemd-socket-proxyd</command>
  43       <arg choice="opt" rep="repeat"><replaceable>OPTIONS</replaceable></arg>
  44       <arg choice="plain"><replaceable>UNIX-DOMAIN-SOCKET-PATH</replaceable>
  45       </arg>
  46     </cmdsynopsis>
  47   </refsynopsisdiv>
  48   <refsect1>
  49     <title>Description</title>
  50     <para>
  51     <command>systemd-socket-proxyd</command> is a generic
  52     socket-activated network socket forwarder proxy daemon for IPv4,
  53     IPv6 and UNIX stream sockets. It may be used to bi-directionally
  54     forward traffic from a local listening socket to a local or remote
  55     destination socket.</para>
  56
  57     <para>One use of this tool is to provide socket activation support
  58     for services that do not natively support socket activation. On
  59     behalf of the service to activate, the proxy inherits the socket
  60     from systemd, accepts each client connection, opens a connection
  61     to a configured server for each client, and then bidirectionally
  62     forwards data between the two.</para>
  63     <para>This utility's behavior is similar to
  64     <citerefentry project='die-net'><refentrytitle>socat</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
  65     The main differences for <command>systemd-socket-proxyd</command>
  66     are support for socket activation with
  67     <literal>Accept=false</literal> and an event-driven
  68     design that scales better with the number of
  69     connections.</para>
  70   </refsect1>
  71   <refsect1>
  72     <title>Options</title>
  73     <para>The following options are understood:</para>
  74     <variablelist>
  75       <xi:include href="standard-options.xml" xpointer="help" />
  76       <xi:include href="standard-options.xml" xpointer="version" />
  77       <varlistentry>
  78         <term><option>--connections-max=</option></term>
  79         <term><option>-c</option></term>
  80
  81         <listitem><para>Sets the maximum number of simultaneous connections, defaults to 256.
  82         If the limit of concurrent connections is reached further connections will be refused.</para></listitem>
  83       </varlistentry>
  84     </variablelist>
  85   </refsect1>
  86   <refsect1>
  87     <title>Exit status</title>
  88     <para>On success, 0 is returned, a non-zero failure
  89     code otherwise.</para>
  90   </refsect1>
  91   <refsect1>
  92     <title>Examples</title>
  93     <refsect2>
  94       <title>Simple Example</title>
  95       <para>Use two services with a dependency and no namespace
  96       isolation.</para>
  97       <example>
  98         <title>proxy-to-nginx.socket</title>
  99         <programlisting><![CDATA[[Socket]
 100 ListenStream=80
 101
 102 [Install]
 103 WantedBy=sockets.target]]></programlisting>
 104       </example>
 105       <example>
 106         <title>proxy-to-nginx.service</title>
 107         <programlisting><![CDATA[[Unit]
 108 Requires=nginx.service
 109 After=nginx.service
 110 Requires=proxy-to-nginx.socket
 111 After=proxy-to-nginx.socket
 112
 113 [Service]
 114 ExecStart=/usr/lib/systemd/systemd-socket-proxyd /run/nginx/socket
 115 PrivateTmp=yes
 116 PrivateNetwork=yes]]></programlisting>
 117       </example>
 118       <example>
 119         <title>nginx.conf</title>
 120         <programlisting>
 121 <![CDATA[[…]
 122 server {
 123     listen       unix:/run/nginx/socket;
 124     […]]]>
 125 </programlisting>
 126       </example>
 127       <example>
 128         <title>Enabling the proxy</title>
 129         <programlisting><![CDATA[# systemctl enable --now proxy-to-nginx.socket
 130 $ curl http://localhost:80/]]></programlisting>
 131       </example>
 132     </refsect2>
 133     <refsect2>
 134       <title>Namespace Example</title>
 135       <para>Similar as above, but runs the socket proxy and the main
 136       service in the same private namespace, assuming that
 137       <filename>nginx.service</filename> has
 138       <varname>PrivateTmp=</varname> and
 139       <varname>PrivateNetwork=</varname> set, too.</para>
 140       <example>
 141         <title>proxy-to-nginx.socket</title>
 142         <programlisting><![CDATA[[Socket]
 143 ListenStream=80
 144
 145 [Install]
 146 WantedBy=sockets.target]]></programlisting>
 147       </example>
 148       <example>
 149         <title>proxy-to-nginx.service</title>
 150         <programlisting><![CDATA[[Unit]
 151 Requires=nginx.service
 152 After=nginx.service
 153 Requires=proxy-to-nginx.socket
 154 After=proxy-to-nginx.socket
 155 JoinsNamespaceOf=nginx.service
 156
 157 [Service]
 158 ExecStart=/usr/lib/systemd/systemd-socket-proxyd 127.0.0.1:8080
 159 PrivateTmp=yes
 160 PrivateNetwork=yes]]></programlisting>
 161       </example>
 162       <example>
 163         <title>nginx.conf</title>
 164         <programlisting><![CDATA[[…]
 165 server {
 166     listen       8080;
 167     […]]]></programlisting>
 168       </example>
 169       <example>
 170         <title>Enabling the proxy</title>
 171         <programlisting><![CDATA[# systemctl enable --now proxy-to-nginx.socket
 172 $ curl http://localhost:80/]]></programlisting>
 173       </example>
 174     </refsect2>
 175   </refsect1>
 176   <refsect1>
 177     <title>See Also</title>
 178     <para>
 179       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 180       <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 181       <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 182       <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 183       <citerefentry project='die-net'><refentrytitle>socat</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 184       <citerefentry project='die-net'><refentrytitle>nginx</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 185       <citerefentry project='die-net'><refentrytitle>curl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 186     </para>
 187   </refsect1>
 188 </refentry>