NAME¶
Perlbal::Manual::ReverseProxy - Configuring Perlbal as a Reverse Proxy
VERSION¶
Perlbal 1.78.
DESCRIPTION¶
How to configure a Perlbal Reverse Proxy service.
READ ME FIRST¶
Please read Perlbal::Manual::Configuration first for a better explanation on how
to configure Perlbal. This document will make much more sense after reading
that.
Configuring Perlbal as a Reverse Proxy¶
Configuration of Perlbal as a Reverse Proxy is similar to configuration as a
Load Balancer.
Check Perlbal::Manual::LoadBalancer under "Using Perlbal as a Load
Balancer" for a sample configuration file and for a brief explanation of
the differences between a Load Balancer and a Reverse Proxy.
Parameters¶
You can set parameters via commands of either forms:
SET <service-name> <param> = <value>
SET <param> = <value>
- always_trusted = bool
- Whether to trust all incoming requests' X-Forwarded-For and
related headers. Set to true only if you know that all incoming requests
from your own proxy servers that clean/set those headers.
Default is false.
- backend_persist_cache = int
- The number of backend connections to keep alive on reserve
while there are no clients.
Default is 2.
- blind_proxy = bool
- Flag to disable any modification of X-Forwarded-For,
X-Host, and X-Forwarded-Host headers.
Default is false.
- buffer_backend_connect = size
- How much content-body (POST/PUT/etc) data we read from a
client before we start sending it to a backend web node. If
"buffer_uploads" is enabled, this value is used to determine how
many bytes are read before Perlbal makes a determination on whether or not
to spool the upload to disk.
Default is 100k.
- buffer_size = size
- How much ahead of a client we'll get while copying from a
backend to a client. If a client gets behind this much, we stop reading
from the backend for a bit. Once all remaining data fits in the buffer,
the backend is released and may be reused.
Default is 256k.
- buffer_size_reproxy_url = size
- How much ahead of a client we'll get while copying from a
reproxied URL to a client. If a client gets behind this much, we stop
reading from the reproxied URL for a bit. The default is lower than the
regular "buffer_size" (50k instead of 256k) because it's assumed
that you're only reproxying to large files on event-based webservers,
which are less sensitive to many open connections, whereas the 256k buffer
size is good for keeping heavy process-based free of slow clients.
Default if 50k.
- buffer_upload_threshold_rate = int
- If an upload is coming in at a rate less than this value in
bytes per second, it will be buffered to disk. A value of 0 means the rate
will not be checked.
Default is 0.
- buffer_upload_threshold_size = size
- If an upload is larger than this size in bytes, it will be
buffered to disk. A value of 0 means the size will not be checked.
Default is 250k.
- buffer_upload_threshold_time = int
- If an upload is estimated to take more than this number of
seconds, it will be buffered to disk. A value of 0 means the time will not
be estimated.
Default is 5.
- buffer_uploads = bool
- Used to enable or disable the buffer uploads to disk
system. If enabled, "buffer_backend_connect" bytes worth of the
upload will be stored in memory. At that point, the buffer upload
thresholds will be checked to see if we should just send this upload to
the backend or if we should spool it to the disk.
Default if false.
- buffer_uploads_path = path/to/directory
- Directory root for storing files used to buffer
uploads.
- client_sndbuf_size = size
- How large to set the client's socket SNDBUF.
Default is 0.
- connect_ahead = int
- How many extra backend connections we keep alive in
addition to the current ones, in anticipation of new client connections.
Default is 0.
- enable_error_retries = bool
- Whether Perlbal should transparently retry requests to
backends if a backend returns a 500 server error.
Default is false.
- enable_reproxy = bool
- Enable 'reproxying' (end-user-transparent internal
redirects) to either local files or other URLs. When enabled, the backend
servers in the pool that this service is configured for will have access
to tell this Perlbal instance to serve any local readable file, or connect
to any other URL that this Perlbal can connect to. Only enable this if you
trust the backend web nodes.
Default is false.
See the section "Reproxying" in this document for more
information.
- error_retry_schedule = string of comma-separated
seconds (full or partial)
- String of comma-separated seconds (full or partial) to
delay between retries. For example "0,2" would mean do at most
two retries, the first zero seconds after the first failure, and the
second 2 seconds after the second failure. You probably don't need to
modify the default value.
Default it 0,0.25,0.50,1,1,1,1,1
- enable_ssl = bool
- Enable SSL to the client.
Default is false.
- high_priority_cookie = cookie_name
- The cookie name to inspect to determine if the client goes
onto the high-priority queue.
See Perlbal::Manual::HighPriority for more information.
- high_priority_cookie_contents = string
- A string that the "high_priority_cookie" must
contain to go onto the high-priority queue.
See Perlbal::Manual::HighPriority for more information.
- idle_timeout = int
- Timeout in seconds for idle connections to the end user.
It's also the limit for how long a backend may take to respond or transfer
data.
Default is 30.
- listen = ip:port
- The ip:port to listen on. For a service to work, you must
either make it listen, or make another selector service map to a
non-listening service.
- max_backend_uses = int
- The maximum number of requests to be made on a single
persistent backend connection before releasing the connection.
A value of 0 means there is no limit and the connection will only be
discarded once the backend asks it to be or when Perlbal is sufficiently
idle.
Default is 0.
- max_chunked_request_size = size
- The maximum size that will be accepted for a chunked
request (which is written to disk, buffered uploads must be on). A value
of 0 means no limit.
Default is 209715200 (200MB).
- persist_client = bool
- Whether to enable HTTP keep-alives to the end user.
Default is false.
- persist_backend = bool
- Whether to enable HTTP keep-alives to the backend webnodes.
Default is false, but setting it to true is highly recommended if Perlbal is
the only client to your backends. If not, beware that Perlbal will hog the
connections, starving other clients.
- persist_client_idle_timeout = int
- Timeout in seconds for HTTP persist_client_idle_timeout
keep-alives to the end user.
Default is 30.
- persist_client_timeout = int
(DEPRECATED)
- Set both the persist_client_timeout
persist_client_idle_timeout and idle_timeout.
Deprecated.
- pool
- Name of previously-created pool object containing the
backend nodes that this reverse proxy sends requests to.
- queue_relief_chance = int:0-100
- Chance (percentage) to take a standard priority request
when we're in pressure relief mode.
Default is 0.
See Perlbal::Manual::HighPriority for more information.
- queue_relief_size = int
- Number of outstanding standard priority connections to
activate pressure relief at.
A value of 0 disables the high priority queue system entirely.
Default is 0.
See Perlbal::Manual::HighPriority for more information.
- reproxy_cache_maxsize = int
- Set the maximum number of cached reproxy results
(X-REPROXY-CACHE-FOR) that may be kept in the service cache. These cached
requests take up about 1.25KB of RAM each (on Linux x86), but will vary
with usage. Perlbal still starts with 0 in the cache and will grow over
time. Be careful when adjusting this and watch your RAM usage like a hawk.
Default is 0, which means cache is disabled.
- role =
reverse_proxy|web_server|management|selector
- What type of service. One of 'reverse_proxy' for a service
that load balances to a pool of backend webserver nodes, 'web_server' for
a typical webserver', 'management' for a Perlbal management interface
(speaks both command-line or HTTP, auto-detected), or 'selector', for a
virtual service that maps onto other services.
- server_process
- Executable which will be the HTTP server on stdin/stdout.
(ALPHA, EXPERIMENTAL)
- ssl_cert_file = path/to/file
- Path to certificate PEM file for SSL.
Default is "certs/server-cert.pem".
- ssl_cipher_list = cipher list
- OpenSSL-style cipher list.
Default is "ALL:!LOW:!EXP".
- ssl_key_file = path/to/file
- Path to private key PEM file for SSL.
Default is "certs/server-key.pem".
- trusted_upstream_proxies = Net::Netmask filter
- A comma separated list of Net::Netmask filters (e.g.
10.0.0.0/24, see Net::Netmask) that determines whether upstream clients
are trusted or not, where trusted means their X-Forwarded-For/etc headers
are not munged.
- upload_status_listeners = comma separated list of
hosts
- Comma separated list of hosts in form 'a.b.c.d:port' which
will receive UDP upload status packets no faster than once a second per
HTTP request (PUT/POST) from clients that have requested an upload status
bar, which they request by appending the URL get argument
?client_up_sess=[xxxxx] where xxxxx is 5-50 'word' characters (a-z, A-Z,
0-9, underscore).
- verify_backend = bool
- Whether Perlbal should send a quick OPTIONS request to the
backends before sending an actual client request to them. If your backend
is Apache or some other process-based webserver, this is highly
recommended. All too often a loaded backend box will reply to new TCP
connections, but it's the kernel's TCP stack Perlbal is talking to, not
and actual Apache process yet. Using this option reduces end-user latency
a ton on loaded sites.
Default if false.
- verify_backend_path = path
- What path the OPTIONS request sent by
"verify_backend" should use.
Default is "*".
- server_tokens = bool
- Whether to provide a "Server" header.
Perlbal by default adds a header to all replies (such as the web_server
role). By setting this default to "off", you can prevent Perlbal
from identifying itself.
Default is "on".
More on Parameters¶
backend_persist_cache vs. connect_ahead
The "backend_persist_cache" parameter refers to connections kept alive
after being used, while "connect_ahead" refers to connections opened
in anticipation.
For instance:
SET backend_persist_cache = 2
SET connect_ahead = 1
Let's assume, for simplification purposes, that your service only has one
server. Here's an example of what could happen:
- •
- Perlbal starts
No connections open until the very first request comes in (this may change
in the future).
- •
- one requests arrives
This request starts being served on the open connection; Perlbal opens
another connection because "connect_ahead"'s value tells it to
always open one in anticipation.
- •
- a second request arrives
(the first request hasn't concluded yet)
The second connection is used, a third one is created so we still have one
in anticipation.
- •
- the first request finishes
The connection is kept open; this means we now have three open connections:
two being used and one free (the first and the third one are free).
- •
- the second request finishes
The connection is killed, as we already have two other open connections (the
first and the third), and that's the number set by
"backend_persist_cache" for the number of connections to be kept
alive.
Reproxying
Perlbal supports the concept of reproxying. Basically, this gives it the ability
to ask a backend node for a file and get back a specific header that says
"this file is really over there, get it there." Perlbal will then
load that file or URL and send it to the user transparently, without them ever
knowing that they got reproxied to another location.
Add the following line to your
perlbal.conf to enable reproxying on a per
service basis ( reproxying is disabled by default in >= 1.38 ):
SET enable_reproxy = true
This can be useful for having URLs that get mapped to files on disk without
giving users enough information to map out your directory structure. For
example, you can create a file structure such as:
/home/pics/$userid/$pic
Then you can have URLs such as:
http://foo.com/mysite/users/$userid/picture/$pic
When this URL gets passed to the backend web node, it could return a simple
response that includes this header:
X-REPROXY-FILE: /home/pics/$userid/$pic
Perlbal will then use asynchronous IO to send the file to the user without
slowing down Perlbal at all.
This support also extends to URLs that can be located anywhere Perlbal has
access to. It's the same syntax, nearly:
X-REPROXY-URL: http://foo.com:80/resource.html
You can also specify multiple URLs:
X-REPROXY-URL: http://foo.com:80/resource.html http://baz.com:8080/res.htm
Just specify any number of space separated URLs. Perlbal will request them one
by one until one returns a response code of 200. At that point Perlbal will
proxy the response back to the user just like normal.
Note that the user's headers are NOT passed through to the web server. To the
target server, it looks simply like Perlbal is requesting the resource for
itself. This behavior may change at some point.
One final note: the server that returns the reproxy header can also return a
"X-REPROXY-EXPECTED-SIZE" header. If present, Perlbal will consider
a reproxy a failure if the file returned by the target system is of a
different size than what the expected size header says. On failure, Perlbal
tries the next URI in the list. If it's a file being reproxied, a 404 is
returned if the file size is different.
SEE ALSO¶
Perlbal::Manual::Configuration, Perlbal::Manual::FailOver,
Perlbal::Manual::LoadBalancer, Perlbal::Manual::Management.