1Perlbal::Manual::ReversUesPerroxCyo(n3t)ributed Perl DocPuemrelnbtaalt:i:oMnanual::ReverseProxy(3)
2
6 Perlbal::Manual::ReverseProxy - Configuring Perlbal as a Reverse Proxy
7 VERSION
9 Perlbal 1.78.
10 DESCRIPTION
12 How to configure a Perlbal Reverse Proxy service.
13 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 Configuring Perlbal as a Reverse Proxy
20 Configuration of Perlbal as a Reverse Proxy is similar to configuration
21 as a Load Balancer.
22 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 Parameters
28 You can set parameters via commands of either forms:
29 SET <service-name> <param> = <value>
31 SET <param> = <value>
32 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 Default is false.
40 backend_persist_cache = int
42 The number of backend connections to keep alive on reserve
43 while there are no clients.
44 Default is 2.
46 blind_proxy = bool
48 Flag to disable any modification of X-Forwarded-For, X-Host,
49 and X-Forwarded-Host headers.
50 Default is false.
52 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 Default is 100k.
61 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 Default is 256k.
69 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 Default if 50k.
81 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 Default is 0.
88 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 Default is 250k.
95 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 Default is 5.
102 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 Default if false.
111 buffer_uploads_path = path/to/directory
113 Directory root for storing files used to buffer uploads.
114 client_sndbuf_size = size
116 How large to set the client's socket SNDBUF.
117 Default is 0.
119 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 Default is 0.
125 enable_error_retries = bool
127 Whether Perlbal should transparently retry requests to backends
128 if a backend returns a 500 server error.
129 Default is false.
131 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 Default is false.
142 See the section "Reproxying" in this document for more
144 information.
145 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 Default it 0,0.25,0.50,1,1,1,1,1
155 enable_ssl = bool
157 Enable SSL to the client.
158 Default is false.
160 high_priority_cookie = cookie_name
162 The cookie name to inspect to determine if the client goes onto
163 the high-priority queue.
164 See Perlbal::Manual::HighPriority for more information.
166 high_priority_cookie_contents = string
168 A string that the "high_priority_cookie" must contain to go
169 onto the high-priority queue.
170 See Perlbal::Manual::HighPriority for more information.
172 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 Default is 30.
179 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 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 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 Default is 0.
194 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 Default is 209715200 (200MB).
201 persist_client = bool
203 Whether to enable HTTP keep-alives to the end user.
204 Default is false.
206 persist_backend = bool
208 Whether to enable HTTP keep-alives to the backend webnodes.
209 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 persist_client_idle_timeout = int
215 Timeout in seconds for HTTP persist_client_idle_timeout keep-
216 alives to the end user.
217 Default is 30.
219 persist_client_timeout = int (DEPRECATED)
221 Set both the persist_client_timeout persist_client_idle_timeout
222 and idle_timeout.
223 Deprecated.
225 pool Name of previously-created pool object containing the backend
227 nodes that this reverse proxy sends requests to.
228 queue_relief_chance = int:0-100
230 Chance (percentage) to take a standard priority request when
231 we're in pressure relief mode.
232 Default is 0.
234 See Perlbal::Manual::HighPriority for more information.
236 queue_relief_size = int
238 Number of outstanding standard priority connections to activate
239 pressure relief at.
240 A value of 0 disables the high priority queue system entirely.
242 Default is 0.
244 See Perlbal::Manual::HighPriority for more information.
246 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 Default is 0, which means cache is disabled.
256 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 server_process
266 Executable which will be the HTTP server on stdin/stdout.
267 (ALPHA, EXPERIMENTAL)
268 ssl_cert_file = path/to/file
270 Path to certificate PEM file for SSL.
271 Default is "certs/server-cert.pem".
273 ssl_cipher_list = cipher list
275 OpenSSL-style cipher list.
276 Default is "ALL:!LOW:!EXP".
278 ssl_key_file = path/to/file
280 Path to private key PEM file for SSL.
281 Default is "certs/server-key.pem".
283 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 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 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 Default if false.
309 verify_backend_path = path
311 What path the OPTIONS request sent by "verify_backend" should
312 use.
313 Default is "*".
315 server_tokens = bool
317 Whether to provide a "Server" header.
318 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 Default is "on".
324 More on Parameters
326 backend_persist_cache vs. connect_ahead
327 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 For instance:
333 SET backend_persist_cache = 2
335 SET connect_ahead = 1
336 Let's assume, for simplification purposes, that your service only has
338 one server. Here's an example of what could happen:
339 • Perlbal starts
341 No connections open until the very first request comes in (this may
343 change in the future).
344 • one requests arrives
346 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 • a second request arrives
352 (the first request hasn't concluded yet)
354 The second connection is used, a third one is created so we still
356 have one in anticipation.
357 • the first request finishes
359 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 • the second request finishes
365 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 Reproxying
372 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 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 SET enable_reproxy = true
384 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 /home/pics/$userid/$pic
390 Then you can have URLs such as:
392 http://foo.com/mysite/users/$userid/picture/$pic
394 When this URL gets passed to the backend web node, it could return a
396 simple response that includes this header:
397 X-REPROXY-FILE: /home/pics/$userid/$pic
399 Perlbal will then use asynchronous IO to send the file to the user
401 without slowing down Perlbal at all.
402 This support also extends to URLs that can be located anywhere Perlbal
404 has access to. It's the same syntax, nearly:
405 X-REPROXY-URL: http://foo.com:80/resource.html
407 You can also specify multiple URLs:
409 X-REPROXY-URL: http://foo.com:80/resource.html http://baz.com:8080/res.htm
411 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 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 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 SEE ALSO
428 Perlbal::Manual::Configuration, Perlbal::Manual::FailOver,
429 Perlbal::Manual::LoadBalancer, Perlbal::Manual::Management.
430perl v5.32.1 2021-01-25 Perlbal::Manual::ReverseProxy(3)