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-saproxy">
25 <title>systemd-saproxy</title>
26 <productname>systemd</productname>
29 <contrib>Developer</contrib>
30 <firstname>David</firstname>
31 <surname>Strauss</surname>
32 <email>david@davidstrauss.net</email>
37 <refentrytitle>systemd-saproxy</refentrytitle>
38 <manvolnum>1</manvolnum>
41 <refname>systemd-saproxy</refname>
42 <refpurpose>Inherit a socket. Bidirectionally
47 <command>systemd-saproxy</command>
48 <arg choice="opt" rep="repeat">OPTIONS</arg>
49 <arg choice="plain"><replaceable>HOSTNAME-OR-IP</replaceable></arg>
50 <arg choice="plain"><replaceable>PORT-OR-SERVICE</replaceable></arg>
53 <command>systemd-saproxy</command>
54 <arg choice="opt" rep="repeat">OPTIONS</arg>
55 <arg choice="plain"><replaceable>UNIX-DOMAIN-SOCKET-PATH</replaceable>
60 <title>Description</title>
62 <command>systemd-saproxy</command> provides a proxy
63 to socket-activate services that do not yet support
64 native socket activation. On behalf of the daemon,
65 the proxy inherits the socket from systemd, accepts
66 each client connection, opens a connection to the server
67 for each client, and then bidirectionally forwards
68 data between the two.</para>
69 <para>This utility's behavior is similar to
70 <citerefentry><refentrytitle>socat</refentrytitle><manvolnum>1</manvolnum> </citerefentry>.
71 The main differences for <command>systemd-saproxy</command>
72 are support for socket activation with
73 <literal>Accept=false</literal> and an event-driven
74 design that scales better with the number of
78 <title>Options</title>
79 <para>The following options are understood:</para>
82 <term><option>-h</option></term>
83 <term><option>--help</option></term>
85 <para>Prints a short help
86 text and exits.</para>
90 <term><option>--version</option></term>
92 <para>Prints a version
93 string and exits.</para>
97 <term><option>--ignore-env</option></term>
99 <para>Skips verification of
100 the expected PID and file
101 descriptor numbers. Use if
102 invoked indirectly, for
103 example with a shell script
105 <option>ExecStart=/usr/bin/systemd-saproxy</option>
112 <title>Exit status</title>
113 <para>On success 0 is returned, a non-zero failure
114 code otherwise.</para>
117 <title>Examples</title>
119 <title>Direct-Use Example</title>
120 <para>Use two services with a dependency
121 and no namespace isolation.</para>
122 <example label="proxy socket unit">
123 <title>/etc/systemd/system/proxy-to-nginx.socket</title>
129 WantedBy=socket.target]]>
132 <example label="proxy service unit">
133 <title>/etc/systemd/system/proxy-to-nginx.service</title>
137 Requires=nginx.service
140 ExecStart=/usr/bin/systemd-saproxy /tmp/nginx.sock
142 PrivateNetwork=true]]>
145 <example label="nginx configuration">
146 <title>/etc/nginx/nginx.conf</title>
150 listen unix:/tmp/nginx.sock;
154 <example label="commands">
156 <![CDATA[$ sudo systemctl --system daemon-reload
157 $ sudo systemctl start proxy-to-nginx.socket
158 $ sudo systemctl enable proxy-to-nginx.socket
159 $ curl http://localhost:80/]]>
164 <title>Indirect-Use Example</title>
165 <para>Use a shell script to isolate the
166 service and proxy into the same namespace.
167 This is particularly useful for running
168 TCP-only daemons without the daemon
169 affecting ports on regular
171 <example label="combined proxy and nginx socket unit">
174 /etc/systemd/system/proxy-with-nginx.socket</title>
180 WantedBy=socket.target]]>
183 <example label="combined proxy and nginx service unit">
186 /etc/systemd/system/proxy-with-nginx.service</title>
189 After=syslog.target remote-fs.target nss-lookup.target
192 ExecStartPre=/usr/sbin/nginx -t
193 ExecStart=/usr/bin/saproxy-nginx.sh
195 PrivateNetwork=true]]>
198 <example label="shell script">
200 /usr/bin/saproxy-nginx.sh</title>
204 while [ ! -f /tmp/nginx.pid ]
206 /usr/bin/inotifywait /tmp/nginx.pid
208 /usr/bin/systemd-saproxy --ignore-env localhost 8080]]>
211 <example label="nginx configuration">
213 /etc/nginx/nginx.conf</title>
218 listen unix:/tmp/nginx.sock;
222 <example label="commands">
224 <![CDATA[$ sudo systemctl --system daemon-reload
225 $ sudo systemctl start proxy-with-nginx.socket
226 $ sudo systemctl enable proxy-with-nginx.socket
227 $ curl http://localhost:80/]]>
233 <title>See Also</title>
237 systemd.service</refentrytitle>
238 <manvolnum>5</manvolnum>
242 systemd.socket</refentrytitle>
243 <manvolnum>5</manvolnum>
246 <refentrytitle>systemctl</refentrytitle>
247 <manvolnum>1</manvolnum>
250 <refentrytitle>socat</refentrytitle>
251 <manvolnum>1</manvolnum>
252 </citerefentry></para>