3 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
4 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
6 This file is part of systemd.
8 Copyright 2013 David Strauss
10 systemd is free software; you can redistribute it and/or modify it
11 under the terms of the GNU Lesser General Public License as published by
12 the Free Software Foundation; either version 2.1 of the License, or
13 (at your option) any later version.
15 systemd is distributed in the hope that it will be useful, but
16 WITHOUT ANY WARRANTY; without even the implied warranty of
17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18 Lesser General Public License for more details.
20 You should have received a copy of the GNU Lesser General Public License
21 along with systemd; If not, see <http://www.gnu.org/licenses/>.
23 <refentry id="systemd-socket-proxyd">
25 <title>systemd-socket-proxyd</title>
26 <productname>systemd</productname>
29 <contrib>Developer</contrib>
30 <firstname>David</firstname>
31 <surname>Strauss</surname>
32 <email>david@davidstrauss.net</email>
35 <contrib>Developer</contrib>
36 <firstname>Lennart</firstname>
37 <surname>Poettering</surname>
38 <email>lennart@poettering.net</email>
43 <refentrytitle>systemd-socket-proxyd</refentrytitle>
44 <manvolnum>1</manvolnum>
47 <refname>systemd-socket-proxyd</refname>
48 <refpurpose>Bidirectionally proxy local sockets to another (possibly remote) socket.</refpurpose>
52 <command>systemd-socket-proxyd</command>
53 <arg choice="opt" rep="repeat"><replaceable>OPTIONS</replaceable></arg>
54 <arg choice="plain"><replaceable>HOST</replaceable>:<replaceable>PORT</replaceable></arg>
57 <command>systemd-socket-proxyd</command>
58 <arg choice="opt" rep="repeat"><replaceable>OPTIONS</replaceable></arg>
59 <arg choice="plain"><replaceable>UNIX-DOMAIN-SOCKET-PATH</replaceable>
64 <title>Description</title>
66 <command>systemd-socket-proxyd</command> is a generic
67 socket-activated network socket forwarder proxy daemon
68 for IPV4, IPv6 and UNIX stream sockets. It may be used
69 to bi-directionally forward traffic from a local listening socket to a
70 local or remote destination socket.</para>
72 <para>One use of this tool is to provide
73 socket activation support for services that do not
74 natively support socket activation. On behalf of the
75 service to activate, the proxy inherits the socket
76 from systemd, accepts each client connection, opens a
77 connection to a configured server for each client, and
78 then bidirectionally forwards data between the
80 <para>This utility's behavior is similar to
81 <citerefentry><refentrytitle>socat</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
82 The main differences for <command>systemd-socket-proxyd</command>
83 are support for socket activation with
84 <literal>Accept=false</literal> and an event-driven
85 design that scales better with the number of
89 <title>Options</title>
90 <para>The following options are understood:</para>
93 <term><option>-l</option></term>
94 <term><option>--listener=</option></term>
96 <para>Restricts listening to a
97 single inherited socket, specified
98 as a file descriptor. By default,
99 the proxy listens on all inherited
104 <term><option>-h</option></term>
105 <term><option>--help</option></term>
107 <para>Prints a short help
108 text and exits.</para>
112 <term><option>--version</option></term>
114 <para>Prints a version
115 string and exits.</para>
121 <title>Exit status</title>
122 <para>On success, 0 is returned, a non-zero failure
123 code otherwise.</para>
126 <title>Examples</title>
128 <title>Direct-Use Example</title>
129 <para>Use two services with a dependency
130 and no namespace isolation.</para>
131 <example label="proxy socket unit">
132 <title>/etc/systemd/system/proxy-to-nginx.socket</title>
138 WantedBy=sockets.target]]>
141 <example label="proxy service unit">
142 <title>/etc/systemd/system/proxy-to-nginx.service</title>
146 Requires=nginx.service
149 ExecStart=/usr/bin/systemd-socket-proxyd /tmp/nginx.sock
151 PrivateNetwork=true]]>
154 <example label="nginx configuration">
155 <title>/etc/nginx/nginx.conf</title>
159 listen unix:/tmp/nginx.sock;
163 <example label="commands">
165 <![CDATA[# systemctl enable proxy-to-nginx.socket
166 # systemctl start proxy-to-nginx.socket
167 $ curl http://localhost:80/]]>
172 <title>Indirect-Use Example</title>
173 <para>Use a shell script to isolate the
174 service and proxy into the same namespace.
175 This is particularly useful for running
176 TCP-only daemons without the daemon
177 affecting ports on regular
179 <example label="combined proxy and nginx socket unit">
182 /etc/systemd/system/proxy-with-nginx.socket</title>
188 WantedBy=sockets.target]]>
191 <example label="combined proxy and nginx service unit">
194 /etc/systemd/system/proxy-with-nginx.service</title>
197 After=remote-fs.target nss-lookup.target
200 ExecStartPre=/usr/sbin/nginx -t
201 ExecStart=/usr/bin/socket-proxyd-nginx.sh
203 PrivateNetwork=true]]>
206 <example label="shell script">
208 /usr/bin/socket-proxyd-nginx.sh</title>
212 while [ ! -f /tmp/nginx.pid ]
214 /usr/bin/inotifywait /tmp/nginx.pid
216 exec /usr/bin/systemd-socket-proxyd localhost:8080]]>
218 <para>Make it executable:</para>
220 <![CDATA[chmod 755 /usr/bin/socket-proxyd-nginx.sh]]>
223 <example label="nginx configuration">
225 /etc/nginx/nginx.conf</title>
230 listen unix:/tmp/nginx.sock;
234 <example label="commands">
236 <![CDATA[# systemctl enable proxy-with-nginx.socket
237 # systemctl start proxy-with-nginx.socket
238 $ curl http://localhost:80/]]>
244 <title>Multiple Listeners with Multiple Destinations</title>
245 <para>When using namespaces, it may be useful to
246 have multiple listeners with each going to a unique
247 destination. systemd always passes sockets into
248 services in the order specified in the socket
249 unit, beginning with file descriptor 3.</para>
250 <para>In this example, port <literal>80</literal>
251 will proxy to <literal>localhost:8080</literal>,
252 and port <literal>443</literal> will proxy to
253 <literal>localhost:8443</literal>.</para>
254 <example label="proxy socket unit">
255 <title>/etc/systemd/system/multi-destination.socket</title>
262 WantedBy=sockets.target]]>
265 <example label="proxy service unit">
266 <title>/etc/systemd/system/multi-destination.service</title>
269 ExecStart=/usr/bin/socket-proxyd-multi-destination.sh
271 PrivateNetwork=true]]>
275 <example label="shell script">
277 /usr/bin/socket-proxyd-multi-destination.sh</title>
280 /usr/bin/systemd-socket-proxyd --listener=3 localhost:8080 &
281 /usr/bin/systemd-socket-proxyd --listener=4 localhost:8443 &
284 <para>Make it executable:</para>
286 <![CDATA[chmod 755 /usr/bin/socket-proxyd-multi-destination.sh]]>
290 <example label="commands">
292 <![CDATA[# systemctl enable multi-destination.socket
293 # systemctl start multi-destination.socket
294 $ curl http://localhost/
295 $ curl https://localhost/]]>
301 <title>See Also</title>
303 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
304 <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
305 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
306 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
307 <citerefentry><refentrytitle>socat</refentrytitle><manvolnum>1</manvolnum></citerefentry>