1Perlbal::Manual::ReversUesPerroxCyo(n3t)ributed Perl DocPuemrelnbtaalt:i:oMnanual::ReverseProxy(3)
2
3
4

NAME

6       Perlbal::Manual::ReverseProxy - Configuring Perlbal as a Reverse Proxy
7
8   VERSION
9       Perlbal 1.78.
10
11   DESCRIPTION
12       How to configure a Perlbal Reverse Proxy service.
13
14   READ ME FIRST
15       Please read Perlbal::Manual::Configuration first for a better
16       explanation on how to configure Perlbal. This document will make much
17       more sense after reading that.
18
19   Configuring Perlbal as a Reverse Proxy
20       Configuration of Perlbal as a Reverse Proxy is similar to configuration
21       as a Load Balancer.
22
23       Check Perlbal::Manual::LoadBalancer under "Using Perlbal as a Load
24       Balancer" for a sample configuration file and for a brief explanation
25       of the differences between a Load Balancer and a Reverse Proxy.
26
27   Parameters
28       You can set parameters via commands of either forms:
29
30           SET <service-name> <param> = <value>
31           SET <param> = <value>
32
33       always_trusted = bool
34               Whether to trust all incoming requests' X-Forwarded-For and
35               related headers. Set to true only if you know that all incoming
36               requests from your own proxy servers that clean/set those
37               headers.
38
39               Default is false.
40
41       backend_persist_cache = int
42               The number of backend connections to keep alive on reserve
43               while there are no clients.
44
45               Default is 2.
46
47       blind_proxy = bool
48               Flag to disable any modification of X-Forwarded-For, X-Host,
49               and X-Forwarded-Host headers.
50
51               Default is false.
52
53       buffer_backend_connect = size
54               How much content-body (POST/PUT/etc) data we read from a client
55               before we start sending it to a backend web node. If
56               "buffer_uploads" is enabled, this value is used to determine
57               how many bytes are read before Perlbal makes a determination on
58               whether or not to spool the upload to disk.
59
60               Default is 100k.
61
62       buffer_size = size
63               How much ahead of a client we'll get while copying from a
64               backend to a client. If a client gets behind this much, we stop
65               reading from the backend for a bit. Once all remaining data
66               fits in the buffer, the backend is released and may be reused.
67
68               Default is 256k.
69
70       buffer_size_reproxy_url = size
71               How much ahead of a client we'll get while copying from a
72               reproxied URL to a client. If a client gets behind this much,
73               we stop reading from the reproxied URL for a bit. The default
74               is lower than the regular "buffer_size" (50k instead of 256k)
75               because it's assumed that you're only reproxying to large files
76               on event-based webservers, which are less sensitive to many
77               open connections, whereas the 256k buffer size is good for
78               keeping heavy process-based free of slow clients.
79
80               Default if 50k.
81
82       buffer_upload_threshold_rate = int
83               If an upload is coming in at a rate less than this value in
84               bytes per second, it will be buffered to disk. A value of 0
85               means the rate will not be checked.
86
87               Default is 0.
88
89       buffer_upload_threshold_size = size
90               If an upload is larger than this size in bytes, it will be
91               buffered to disk. A value of 0 means the size will not be
92               checked.
93
94               Default is 250k.
95
96       buffer_upload_threshold_time = int
97               If an upload is estimated to take more than this number of
98               seconds, it will be buffered to disk. A value of 0 means the
99               time will not be estimated.
100
101               Default is 5.
102
103       buffer_uploads = bool
104               Used to enable or disable the buffer uploads to disk system. If
105               enabled, "buffer_backend_connect" bytes worth of the upload
106               will be stored in memory. At that point, the buffer upload
107               thresholds will be checked to see if we should just send this
108               upload to the backend or if we should spool it to the disk.
109
110               Default if false.
111
112       buffer_uploads_path = path/to/directory
113               Directory root for storing files used to buffer uploads.
114
115       client_sndbuf_size = size
116               How large to set the client's socket SNDBUF.
117
118               Default is 0.
119
120       connect_ahead = int
121               How many extra backend connections we keep alive in addition to
122               the current ones, in anticipation of new client connections.
123
124               Default is 0.
125
126       enable_error_retries = bool
127               Whether Perlbal should transparently retry requests to backends
128               if a backend returns a 500 server error.
129
130               Default is false.
131
132       enable_reproxy = bool
133               Enable 'reproxying' (end-user-transparent internal redirects)
134               to either local files or other URLs. When enabled, the backend
135               servers in the pool that this service is configured for will
136               have access to tell this Perlbal instance to serve any local
137               readable file, or connect to any other URL that this Perlbal
138               can connect to. Only enable this if you trust the backend web
139               nodes.
140
141               Default is false.
142
143               See the section "Reproxying" in this document for more
144               information.
145
146       error_retry_schedule = string of comma-separated seconds (full or
147       partial)
148               String of comma-separated seconds (full or partial) to delay
149               between retries. For example "0,2" would mean do at most two
150               retries, the first zero seconds after the first failure, and
151               the second 2 seconds after the second failure. You probably
152               don't need to modify the default value.
153
154               Default it 0,0.25,0.50,1,1,1,1,1
155
156       enable_ssl = bool
157               Enable SSL to the client.
158
159               Default is false.
160
161       high_priority_cookie = cookie_name
162               The cookie name to inspect to determine if the client goes onto
163               the high-priority queue.
164
165               See Perlbal::Manual::HighPriority for more information.
166
167       high_priority_cookie_contents = string
168               A string that the "high_priority_cookie" must contain to go
169               onto the high-priority queue.
170
171               See Perlbal::Manual::HighPriority for more information.
172
173       idle_timeout = int
174               Timeout in seconds for idle connections to the end user. It's
175               also the limit for how long a backend may take to respond or
176               transfer data.
177
178               Default is 30.
179
180       listen = ip:port
181               The ip:port to listen on. For a service to work, you must
182               either make it listen, or make another selector service map to
183               a non-listening service.
184
185       max_backend_uses = int
186               The maximum number of requests to be made on a single
187               persistent backend connection before releasing the connection.
188
189               A value of 0 means there is no limit and the connection will
190               only be discarded once the backend asks it to be or when
191               Perlbal is sufficiently idle.
192
193               Default is 0.
194
195       max_chunked_request_size = size
196               The maximum size that will be accepted for a chunked request
197               (which is written to disk, buffered uploads must be on). A
198               value of 0 means no limit.
199
200               Default is 209715200 (200MB).
201
202       persist_client = bool
203               Whether to enable HTTP keep-alives to the end user.
204
205               Default is false.
206
207       persist_backend = bool
208               Whether to enable HTTP keep-alives to the backend webnodes.
209
210               Default is false, but setting it to true is highly recommended
211               if Perlbal is the only client to your backends. If not, beware
212               that Perlbal will hog the connections, starving other clients.
213
214       persist_client_idle_timeout = int
215               Timeout in seconds for HTTP persist_client_idle_timeout keep-
216               alives to the end user.
217
218               Default is 30.
219
220       persist_client_timeout = int (DEPRECATED)
221               Set both the persist_client_timeout persist_client_idle_timeout
222               and idle_timeout.
223
224               Deprecated.
225
226       pool    Name of previously-created pool object containing the backend
227               nodes that this reverse proxy sends requests to.
228
229       queue_relief_chance = int:0-100
230               Chance (percentage) to take a standard priority request when
231               we're in pressure relief mode.
232
233               Default is 0.
234
235               See Perlbal::Manual::HighPriority for more information.
236
237       queue_relief_size = int
238               Number of outstanding standard priority connections to activate
239               pressure relief at.
240
241               A value of 0 disables the high priority queue system entirely.
242
243               Default is 0.
244
245               See Perlbal::Manual::HighPriority for more information.
246
247       reproxy_cache_maxsize = int
248               Set the maximum number of cached reproxy results (X-REPROXY-
249               CACHE-FOR) that may be kept in the service cache. These cached
250               requests take up about 1.25KB of RAM each (on Linux x86), but
251               will vary with usage. Perlbal still starts with 0 in the cache
252               and will grow over time. Be careful when adjusting this and
253               watch your RAM usage like a hawk.
254
255               Default is 0, which means cache is disabled.
256
257       role = reverse_proxy|web_server|management|selector
258               What type of service. One of 'reverse_proxy' for a service that
259               load balances to a pool of backend webserver nodes,
260               'web_server' for a typical webserver', 'management' for a
261               Perlbal management interface (speaks both command-line or HTTP,
262               auto-detected), or 'selector', for a virtual service that maps
263               onto other services.
264
265       server_process
266               Executable which will be the HTTP server on stdin/stdout.
267               (ALPHA, EXPERIMENTAL)
268
269       ssl_cert_file = path/to/file
270               Path to certificate PEM file for SSL.
271
272               Default is "certs/server-cert.pem".
273
274       ssl_cipher_list = cipher list
275               OpenSSL-style cipher list.
276
277               Default is "ALL:!LOW:!EXP".
278
279       ssl_key_file = path/to/file
280               Path to private key PEM file for SSL.
281
282               Default is "certs/server-key.pem".
283
284       trusted_upstream_proxies = Net::Netmask filter
285               A comma separated list of Net::Netmask filters (e.g.
286               10.0.0.0/24, see Net::Netmask) that determines whether upstream
287               clients are trusted or not, where trusted means their
288               X-Forwarded-For/etc headers are not munged.
289
290       upload_status_listeners = comma separated list of hosts
291               Comma separated list of hosts in form 'a.b.c.d:port' which will
292               receive UDP upload status packets no faster than once a second
293               per HTTP request (PUT/POST) from clients that have requested an
294               upload status bar, which they request by appending the URL get
295               argument ?client_up_sess=[xxxxx] where xxxxx is 5-50 'word'
296               characters (a-z, A-Z, 0-9, underscore).
297
298       verify_backend = bool
299               Whether Perlbal should send a quick OPTIONS request to the
300               backends before sending an actual client request to them. If
301               your backend is Apache or some other process-based webserver,
302               this is highly recommended. All too often a loaded backend box
303               will reply to new TCP connections, but it's the kernel's TCP
304               stack Perlbal is talking to, not and actual Apache process yet.
305               Using this option reduces end-user latency a ton on loaded
306               sites.
307
308               Default if false.
309
310       verify_backend_path = path
311               What path the OPTIONS request sent by "verify_backend" should
312               use.
313
314               Default is "*".
315
316       server_tokens = bool
317               Whether to provide a "Server" header.
318
319               Perlbal by default adds a header to all replies (such as the
320               web_server role). By setting this default to "off", you can
321               prevent Perlbal from identifying itself.
322
323               Default is "on".
324
325   More on Parameters
326       backend_persist_cache vs. connect_ahead
327
328       The "backend_persist_cache" parameter refers to connections kept alive
329       after being used, while "connect_ahead" refers to connections opened in
330       anticipation.
331
332       For instance:
333
334           SET backend_persist_cache = 2
335           SET connect_ahead         = 1
336
337       Let's assume, for simplification purposes, that your service only has
338       one server. Here's an example of what could happen:
339
340       •   Perlbal starts
341
342           No connections open until the very first request comes in (this may
343           change in the future).
344
345       •   one requests arrives
346
347           This request starts being served on the open connection; Perlbal
348           opens another connection because "connect_ahead"'s value tells it
349           to always open one in anticipation.
350
351       •   a second request arrives
352
353           (the first request hasn't concluded yet)
354
355           The second connection is used, a third one is created so we still
356           have one in anticipation.
357
358       •   the first request finishes
359
360           The connection is kept open; this means we now have three open
361           connections: two being used and one free (the first and the third
362           one are free).
363
364       •   the second request finishes
365
366           The connection is killed, as we already have two other open
367           connections (the first and the third), and that's the number set by
368           "backend_persist_cache" for the number of connections to be kept
369           alive.
370
371       Reproxying
372
373       Perlbal supports the concept of reproxying. Basically, this gives it
374       the ability to ask a backend node for a file and get back a specific
375       header that says "this file is really over there, get it there."
376       Perlbal will then load that file or URL and send it to the user
377       transparently, without them ever knowing that they got reproxied to
378       another location.
379
380       Add the following line to your perlbal.conf to enable reproxying on a
381       per service basis ( reproxying is disabled by default in >= 1.38 ):
382
383           SET enable_reproxy  = true
384
385       This can be useful for having URLs that get mapped to files on disk
386       without giving users enough information to map out your directory
387       structure. For example, you can create a file structure such as:
388
389           /home/pics/$userid/$pic
390
391       Then you can have URLs such as:
392
393           http://foo.com/mysite/users/$userid/picture/$pic
394
395       When this URL gets passed to the backend web node, it could return a
396       simple response that includes this header:
397
398           X-REPROXY-FILE: /home/pics/$userid/$pic
399
400       Perlbal will then use asynchronous IO to send the file to the user
401       without slowing down Perlbal at all.
402
403       This support also extends to URLs that can be located anywhere Perlbal
404       has access to. It's the same syntax, nearly:
405
406           X-REPROXY-URL: http://foo.com:80/resource.html
407
408       You can also specify multiple URLs:
409
410           X-REPROXY-URL: http://foo.com:80/resource.html http://baz.com:8080/res.htm
411
412       Just specify any number of space separated URLs. Perlbal will request
413       them one by one until one returns a response code of 200. At that point
414       Perlbal will proxy the response back to the user just like normal.
415
416       Note that the user's headers are NOT passed through to the web server.
417       To the target server, it looks simply like Perlbal is requesting the
418       resource for itself. This behavior may change at some point.
419
420       One final note: the server that returns the reproxy header can also
421       return a "X-REPROXY-EXPECTED-SIZE" header. If present, Perlbal will
422       consider a reproxy a failure if the file returned by the target system
423       is of a different size than what the expected size header says. On
424       failure, Perlbal tries the next URI in the list. If it's a file being
425       reproxied, a 404 is returned if the file size is different.
426
427   SEE ALSO
428       Perlbal::Manual::Configuration, Perlbal::Manual::FailOver,
429       Perlbal::Manual::LoadBalancer, Perlbal::Manual::Management.
430
431
432
433perl v5.32.1                      2021-01-25  Perlbal::Manual::ReverseProxy(3)
Impressum