Debian Codegraph @

upstream/debian-unstable/man8/systemd-socket-proxyd.8

raw
1 '\" t
2 .TH "SYSTEMD\-SOCKET\-PROXYD" "8" "" "systemd 261~rc3" "systemd-socket-proxyd"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 systemd-socket-proxyd \- Bidirectionally proxy local sockets to another (possibly remote) socket
24 .SH "SYNOPSIS"
25 .HP \w'\fBsystemd\-socket\-proxyd\fR\ 'u
26 \fBsystemd\-socket\-proxyd\fR [\fIOPTIONS\fR...] \fIHOST\fR:\fIPORT\fR
27 .HP \w'\fBsystemd\-socket\-proxyd\fR\ 'u
28 \fBsystemd\-socket\-proxyd\fR [\fIOPTIONS\fR...] \fIUNIX\-DOMAIN\-SOCKET\-PATH\fR
29 .SH "DESCRIPTION"
30 .PP
31 \fBsystemd\-socket\-proxyd\fR
32 is a generic socket\-activated network socket forwarder proxy daemon for IPv4, IPv6 and UNIX stream sockets\&. It may be used to bi\-directionally forward traffic from a local listening socket to a local or remote destination socket\&.
33 .PP
34 One use of this tool is to provide socket activation support for services that do not natively support socket activation\&. On behalf of the service to activate, the proxy inherits the socket from systemd, accepts each client connection, opens a connection to a configured server for each client, and then bidirectionally forwards data between the two\&.
35 .PP
36 This utility\*(Aqs behavior is similar to
37 \fBsocat\fR(1)\&. The main differences for
38 \fBsystemd\-socket\-proxyd\fR
39 are support for socket activation with
40 "Accept=no"
41 and an event\-driven design that scales better with the number of connections\&.
42 .PP
43 Note that
44 \fBsystemd\-socket\-proxyd\fR
45 will not forward socket side channel information, i\&.e\&. will not forward
46 \fBSCM_RIGHTS\fR,
47 \fBSCM_CREDENTIALS\fR,
48 \fBSCM_SECURITY\fR,
49 \fBSO_PEERCRED\fR,
50 \fBSO_PEERPIDFD\fR,
51 \fBSO_PEERSEC\fR,
52 \fBSO_PEERGROUPS\fR
53 and similar\&.
54 .SH "OPTIONS"
55 .PP
56 The following options are understood:
57 .PP
58 \fB\-h\fR, \fB\-\-help\fR
59 .RS 4
60 Print a short help text and exit\&.
61 .RE
62 .PP
63 \fB\-\-version\fR
64 .RS 4
65 Print a short version string and exit\&.
66 .RE
67 .PP
68 \fB\-\-connections\-max=\fR, \fB\-c\fR
69 .RS 4
70 Sets the maximum number of simultaneous connections, defaults to 256\&. If the limit of concurrent connections is reached further connections will be refused\&.
71 .sp
72 Added in version 233\&.
73 .RE
74 .PP
75 \fB\-\-exit\-idle\-time=\fR
76 .RS 4
77 Sets the time before exiting when there are no connections, defaults to
78 \fBinfinity\fR\&. Takes a unit\-less value in seconds, or a time span value such as
79 "5min 20s"\&.
80 .sp
81 Added in version 246\&.
82 .RE
83 .PP
84 \fB\-\-proxy\-protocol=\fR
85 .RS 4
86 Uses the
87 \m[blue]\fBPROXY protocol\fR\m[]\&\s-2\u[1]\d\s+2
88 to communicate with the server\&. This allows an appropriately configured server to know the real client IP address\&. Takes the version of the
89 \m[blue]\fBPROXY protocol\fR\m[]\&\s-2\u[1]\d\s+2
90 used, and only supports
91 "v1"
92 for now\&. Default is not to use a PROXY protocol\&.
93 .sp
94 Added in version 261\&.
95 .RE
96 .SH "EXIT STATUS"
97 .PP
98 On success, 0 is returned, a non\-zero failure code otherwise\&.
99 .SH "EXAMPLES"
100 .SS "Simple Example"
101 .PP
102 Use two services with a dependency and no namespace isolation\&.
103 .PP
104 \fBExample\ \&1.\ \&proxy\-to\-nginx\&.socket\fR
105 .sp
106 .if n \{\
107 .RS 4
108 .\}
109 .nf
110 [Socket]
111 ListenStream=80
112
113 [Install]
114 WantedBy=sockets\&.target
115 .fi
116 .if n \{\
117 .RE
118 .\}
119 .PP
120 \fBExample\ \&2.\ \&proxy\-to\-nginx\&.service\fR
121 .sp
122 .if n \{\
123 .RS 4
124 .\}
125 .nf
126 [Unit]
127 Requires=nginx\&.service
128 After=nginx\&.service
129 Requires=proxy\-to\-nginx\&.socket
130 After=proxy\-to\-nginx\&.socket
131
132 [Service]
133 Type=notify
134 ExecStart=/usr/lib/systemd/systemd\-socket\-proxyd /run/nginx/socket
135 PrivateTmp=yes
136 PrivateNetwork=yes
137 .fi
138 .if n \{\
139 .RE
140 .\}
141 .PP
142 \fBExample\ \&3.\ \&nginx\&.conf\fR
143 .sp
144 .if n \{\
145 .RS 4
146 .\}
147 .nf
148 [\&...]
149 server {
150 listen unix:/run/nginx/socket;
151 [\&...]
152 .fi
153 .if n \{\
154 .RE
155 .\}
156 .PP
157 \fBExample\ \&4.\ \&Enabling the proxy\fR
158 .sp
159 .if n \{\
160 .RS 4
161 .\}
162 .nf
163 # systemctl enable \-\-now proxy\-to\-nginx\&.socket
164 $ curl http://localhost:80/
165 .fi
166 .if n \{\
167 .RE
168 .\}
169 .PP
170 If
171 nginx\&.service
172 has
173 \fIStopWhenUnneeded=\fR
174 set, then passing
175 \fB\-\-exit\-idle\-time=\fR
176 to
177 \fBsystemd\-socket\-proxyd\fR
178 allows both services to stop during idle periods\&.
179 .SS "Namespace Example"
180 .PP
181 Similar as above, but runs the socket proxy and the main service in the same private namespace, assuming that
182 nginx\&.service
183 has
184 \fIPrivateTmp=\fR
185 and
186 \fIPrivateNetwork=\fR
187 set, too\&.
188 .PP
189 \fBExample\ \&5.\ \&proxy\-to\-nginx\&.socket\fR
190 .sp
191 .if n \{\
192 .RS 4
193 .\}
194 .nf
195 [Socket]
196 ListenStream=80
197
198 [Install]
199 WantedBy=sockets\&.target
200 .fi
201 .if n \{\
202 .RE
203 .\}
204 .PP
205 \fBExample\ \&6.\ \&proxy\-to\-nginx\&.service\fR
206 .sp
207 .if n \{\
208 .RS 4
209 .\}
210 .nf
211 [Unit]
212 Requires=nginx\&.service
213 After=nginx\&.service
214 Requires=proxy\-to\-nginx\&.socket
215 After=proxy\-to\-nginx\&.socket
216 JoinsNamespaceOf=nginx\&.service
217
218 [Service]
219 Type=notify
220 ExecStart=/usr/lib/systemd/systemd\-socket\-proxyd 127\&.0\&.0\&.1:8080
221 PrivateTmp=yes
222 PrivateNetwork=yes
223 .fi
224 .if n \{\
225 .RE
226 .\}
227 .PP
228 \fBExample\ \&7.\ \&nginx\&.conf\fR
229 .sp
230 .if n \{\
231 .RS 4
232 .\}
233 .nf
234 [\&...]
235 server {
236 listen 8080;
237 [\&...]
238 .fi
239 .if n \{\
240 .RE
241 .\}
242 .PP
243 \fBExample\ \&8.\ \&Enabling the proxy\fR
244 .sp
245 .if n \{\
246 .RS 4
247 .\}
248 .nf
249 # systemctl enable \-\-now proxy\-to\-nginx\&.socket
250 $ curl http://localhost:80/
251 .fi
252 .if n \{\
253 .RE
254 .\}
255 .SS "PROXY protocol example with nginx"
256 .PP
257 systemd\-socket\-proxyd and nginx using the PROXY protocol
258 .PP
259 \fBExample\ \&9.\ \&proxy\-to\-nginx\&.socket\fR
260 .sp
261 .if n \{\
262 .RS 4
263 .\}
264 .nf
265 [Socket]
266 ListenStream=80
267
268 [Install]
269 WantedBy=sockets\&.target
270 .fi
271 .if n \{\
272 .RE
273 .\}
274 .PP
275 \fBExample\ \&10.\ \&proxy\-to\-nginx\&.service\fR
276 .sp
277 .if n \{\
278 .RS 4
279 .\}
280 .nf
281 [Unit]
282 Requires=nginx\&.service
283 After=nginx\&.service
284 Requires=proxy\-to\-nginx\&.socket
285 After=proxy\-to\-nginx\&.socket
286
287 [Service]
288 Type=notify
289 ExecStart=/usr/lib/systemd/systemd\-socket\-proxyd \-\-proxy\-protocol=v1 /run/nginx/socket
290 PrivateTmp=yes
291 PrivateNetwork=yes
292 .fi
293 .if n \{\
294 .RE
295 .\}
296 .PP
297 \fBExample\ \&11.\ \&nginx\&.conf\fR
298 .sp
299 .if n \{\
300 .RS 4
301 .\}
302 .nf
303 [\&...]
304 server {
305 listen unix:/run/nginx/socket proxy_protocol;
306 real_ip_header proxy_protocol;
307 [\&...]
308 .fi
309 .if n \{\
310 .RE
311 .\}
312 .PP
313 \fBExample\ \&12.\ \&Enabling the proxy\fR
314 .sp
315 .if n \{\
316 .RS 4
317 .\}
318 .nf
319 # systemctl enable \-\-now proxy\-to\-nginx\&.socket
320 $ curl http://localhost:80/
321 .fi
322 .if n \{\
323 .RE
324 .\}
325 .SH "SEE ALSO"
326 .PP
327 \fBsystemd\fR(1), \fBsystemd.socket\fR(5), \fBsystemd.service\fR(5), \fBsystemctl\fR(1), \fBsocat\fR(1), \fBnginx\fR(1), \fBcurl\fR(1), \m[blue]\fBPROXY protocol specification\fR\m[]\&\s-2\u[1]\d\s+2, \m[blue]\fBnginx: Accepting the PROXY Protocol\fR\m[]\&\s-2\u[2]\d\s+2
328 .SH "NOTES"
329 .IP " 1." 4
330 PROXY protocol
331 .RS 4
332 \%https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt
333 .RE
334 .IP " 2." 4
335 nginx: Accepting the PROXY Protocol
336 .RS 4
337 \%https://docs.nginx.com/nginx/admin-guide/load-balancer/using-proxy-protocol/
338 .RE