Debian Codegraph @

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

raw
1 '\" t
2 .TH "SYSTEMD\-SOCKET\-PROXYD" "8" "" "systemd 257.13" "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 .SH "EXIT STATUS"
84 .PP
85 On success, 0 is returned, a non\-zero failure code otherwise\&.
86 .SH "EXAMPLES"
87 .SS "Simple Example"
88 .PP
89 Use two services with a dependency and no namespace isolation\&.
90 .PP
91 \fBExample\ \&1.\ \&proxy\-to\-nginx\&.socket\fR
92 .sp
93 .if n \{\
94 .RS 4
95 .\}
96 .nf
97 [Socket]
98 ListenStream=80
99
100 [Install]
101 WantedBy=sockets\&.target
102 .fi
103 .if n \{\
104 .RE
105 .\}
106 .PP
107 \fBExample\ \&2.\ \&proxy\-to\-nginx\&.service\fR
108 .sp
109 .if n \{\
110 .RS 4
111 .\}
112 .nf
113 [Unit]
114 Requires=nginx\&.service
115 After=nginx\&.service
116 Requires=proxy\-to\-nginx\&.socket
117 After=proxy\-to\-nginx\&.socket
118
119 [Service]
120 Type=notify
121 ExecStart=/usr/lib/systemd/systemd\-socket\-proxyd /run/nginx/socket
122 PrivateTmp=yes
123 PrivateNetwork=yes
124 .fi
125 .if n \{\
126 .RE
127 .\}
128 .PP
129 \fBExample\ \&3.\ \&nginx\&.conf\fR
130 .sp
131 .if n \{\
132 .RS 4
133 .\}
134 .nf
135 [\&...]
136 server {
137 listen unix:/run/nginx/socket;
138 [\&...]
139 .fi
140 .if n \{\
141 .RE
142 .\}
143 .PP
144 \fBExample\ \&4.\ \&Enabling the proxy\fR
145 .sp
146 .if n \{\
147 .RS 4
148 .\}
149 .nf
150 # systemctl enable \-\-now proxy\-to\-nginx\&.socket
151 $ curl http://localhost:80/
152 .fi
153 .if n \{\
154 .RE
155 .\}
156 .PP
157 If
158 nginx\&.service
159 has
160 \fIStopWhenUnneeded=\fR
161 set, then passing
162 \fB\-\-exit\-idle\-time=\fR
163 to
164 \fBsystemd\-socket\-proxyd\fR
165 allows both services to stop during idle periods\&.
166 .SS "Namespace Example"
167 .PP
168 Similar as above, but runs the socket proxy and the main service in the same private namespace, assuming that
169 nginx\&.service
170 has
171 \fIPrivateTmp=\fR
172 and
173 \fIPrivateNetwork=\fR
174 set, too\&.
175 .PP
176 \fBExample\ \&5.\ \&proxy\-to\-nginx\&.socket\fR
177 .sp
178 .if n \{\
179 .RS 4
180 .\}
181 .nf
182 [Socket]
183 ListenStream=80
184
185 [Install]
186 WantedBy=sockets\&.target
187 .fi
188 .if n \{\
189 .RE
190 .\}
191 .PP
192 \fBExample\ \&6.\ \&proxy\-to\-nginx\&.service\fR
193 .sp
194 .if n \{\
195 .RS 4
196 .\}
197 .nf
198 [Unit]
199 Requires=nginx\&.service
200 After=nginx\&.service
201 Requires=proxy\-to\-nginx\&.socket
202 After=proxy\-to\-nginx\&.socket
203 JoinsNamespaceOf=nginx\&.service
204
205 [Service]
206 Type=notify
207 ExecStart=/usr/lib/systemd/systemd\-socket\-proxyd 127\&.0\&.0\&.1:8080
208 PrivateTmp=yes
209 PrivateNetwork=yes
210 .fi
211 .if n \{\
212 .RE
213 .\}
214 .PP
215 \fBExample\ \&7.\ \&nginx\&.conf\fR
216 .sp
217 .if n \{\
218 .RS 4
219 .\}
220 .nf
221 [\&...]
222 server {
223 listen 8080;
224 [\&...]
225 .fi
226 .if n \{\
227 .RE
228 .\}
229 .PP
230 \fBExample\ \&8.\ \&Enabling the proxy\fR
231 .sp
232 .if n \{\
233 .RS 4
234 .\}
235 .nf
236 # systemctl enable \-\-now proxy\-to\-nginx\&.socket
237 $ curl http://localhost:80/
238 .fi
239 .if n \{\
240 .RE
241 .\}
242 .SH "SEE ALSO"
243 .PP
244 \fBsystemd\fR(1), \fBsystemd.socket\fR(5), \fBsystemd.service\fR(5), \fBsystemctl\fR(1), \fBsocat\fR(1), \fBnginx\fR(1), \fBcurl\fR(1)