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