Perlbal Service parameters
Set via commands of either forms:
SET <service-name> <param> = <value>
SET <param> = <value>
Note on types: 'bool' values can be set using one of 1, true, yes, on, 0,
false, off, or no. 'size' values are in integer bytes, or an integer
followed by 'b', 'k', or 'm' (case-insensitive) for bytes, KiB, or MiB.
For all services:
+------------------------------------------------------------------------+
| Param | type | Default | Description |
|-----------------+------+-----------------------+-----------------------|
| enable_ssl | bool | false | Enable SSL to the |
| | | | client. |
|-----------------+------+-----------------------+-----------------------|
| | | | The ip:port to listen |
| | | | on. For a service to |
| | | | work, you must either |
| listen | | | make it listen, or |
| | | | make another selector |
| | | | service map to a |
| | | | non-listening |
| | | | service. |
|-----------------+------+-----------------------+-----------------------|
| | | | Whether to enable |
| persist_client | bool | false | HTTP keep-alives to |
| | | | the end user. |
|-----------------+------+-----------------------+-----------------------|
| | | | Timeout in secs for |
| persist_client_ | int | 30 | HTTP keep-alives to |
| timeout | | | the end user. |
|-----------------+------+-----------------------+-----------------------|
| | | | 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 |
| role | | | 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. |
|-----------------+------+-----------------------+-----------------------|
| ssl_cert_file | | certs/server-cert.pem | Path to certificate |
| | | | PEM file for SSL. |
| | | | Include any needed |
| | | | chain PEMs here, too. |
|-----------------+------+-----------------------+-----------------------|
| ssl_cipher_list | | ALL:!LOW:!EXP | OpenSSL-style cipher |
| | | | list. |
|-----------------+------+-----------------------+-----------------------|
| ssl_key_file | | certs/server-key.pem | Path to private key |
| | | | PEM file for SSL. |
+------------------------------------------------------------------------+
Only for 'reverse_proxy' services:
+----------------------------------------------------------------------------------+
| Param |type| Default | Description |
|-----------------------------+----+-------------------+---------------------------|
| | | |Whether to trust all |
| | | |incoming requests' |
| | | |X-Forwarded-For and related|
|always_trusted |bool|false |headers. Set to true only |
| | | |if you know that all |
| | | |incoming requests from your|
| | | |own proxy servers that |
| | | |clean/set those headers. |
|-----------------------------+----+-------------------+---------------------------|
| | | |The number of backend |
|backend_persist_cache |int |2 |connections to keep alive |
| | | |on reserve while there are |
| | | |no clients. |
|-----------------------------+----+-------------------+---------------------------|
| | | |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_backend_connect |size|100k |'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. |
|-----------------------------+----+-------------------+---------------------------|
| | | |How much we'll ahead of a |
| | | |client we'll get while |
| | | |copying from a backend to a|
|buffer_size |size|256k |client. If a client gets |
| | | |behind this much, we stop |
| | | |reading from the backend |
| | | |for a bit. |
|-----------------------------+----+-------------------+---------------------------|
| | | |How much we'll get 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_reproxy_url |size|50k |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. |
|-----------------------------+----+-------------------+---------------------------|
| | | |If an upload is coming in |
| | | |at a rate less than this |
|buffer_upload_threshold_rate |int |0 |value in bytes per second, |
| | | |it will be buffered to |
| | | |disk. Set to 0 to not check|
| | | |rate. |
|-----------------------------+----+-------------------+---------------------------|
| | | |If an upload is larger than|
|buffer_upload_threshold_size |size|250k |this size in bytes, it will|
| | | |be buffered to disk. Set to|
| | | |0 to not check size. |
|-----------------------------+----+-------------------+---------------------------|
| | | |If an upload is estimated |
| | | |to take more than this |
|buffer_upload_threshold_time |int |5 |number of seconds, it will |
| | | |be buffered to disk. Set to|
| | | |0 to not check estimated |
| | | |time. |
|-----------------------------+----+-------------------+---------------------------|
| | | |Used to enable or disable |
| | | |the buffer uploads to disk |
| | | |system. If enabled, |
| | | |'buffer_backend_connect' |
| | | |bytes worth of the upload |
|buffer_uploads |bool|false |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 disk. |
|-----------------------------+----+-------------------+---------------------------|
| | | |Directory root for storing |
|buffer_uploads_path | | |files used to buffer |
| | | |uploads. |
|-----------------------------+----+-------------------+---------------------------|
| | | |How many extra backend |
| | | |connections we keep alive |
|connect_ahead |int |0 |in addition to the current |
| | | |ones, in anticipation of |
| | | |new client connections. |
|-----------------------------+----+-------------------+---------------------------|
| | | |Whether Perlbal should |
| | | |transparently retry |
|enable_error_retries |bool|false |requests to backends if a |
| | | |backend returns a 500 |
| | | |server error. |
|-----------------------------+----+-------------------+---------------------------|
| | | |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 |
|enable_reproxy |bool|false |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. |
|-----------------------------+----+-------------------+---------------------------|
| | | |String of comma-separated |
| | | |seconds (full or partial) |
| | | |to delay between retries. |
| | | |For example "0,2" would |
| | | |mean do at most two |
|error_retry_schedule | |0,.25,.50,1,1,1,1,1|retries, the first zero |
| | | |seconds after the first |
| | | |failure, and the second 2 |
| | | |seconds after the 2nd |
| | | |failure. You probably don't|
| | | |need to modify the default |
| | | |value |
|-----------------------------+----+-------------------+---------------------------|
| | | |The cookie name to inspect |
|high_priority_cookie | | |to determine if the client |
| | | |goes onto the high-priority|
| | | |queue. |
|-----------------------------+----+-------------------+---------------------------|
| | | |A string that the |
|high_priority_cookie_contents| | |high_priority_cookie must |
| | | |contain to go onto the |
| | | |high-priority queue. |
|-----------------------------+----+-------------------+---------------------------|
| | | |The max number of requests |
| | | |to be made on a single |
| | | |persistent backend |
| | | |connection before releasing|
| | | |the connection. The default|
|max_backend_uses | |0 |value of 0 means no limit, |
| | | |and the connection will |
| | | |only be discarded once the |
| | | |backend asks it to be, or |
| | | |when Perlbal is |
| | | |sufficiently idle. |
|-----------------------------+----+-------------------+---------------------------|
| | | |Whether to enable HTTP |
| | | |keep-alives to the backend |
| | | |webnodes. (Off by default, |
| | | |but highly recommended if |
|persist_backend |bool|false |Perlbal will be the only |
| | | |client to your backends. If|
| | | |not, beware that Perlbal |
| | | |will hog the connections, |
| | | |starving other clients.) |
|-----------------------------+----+-------------------+---------------------------|
| | | |Name of previously-created |
| | | |pool object containing the |
|pool | | |backend nodes that this |
| | | |reverse proxy sends |
| | | |requests to. |
|-----------------------------+----+-------------------+---------------------------|
|queue_relief_chance | |0 | |
|-----------------------------+----+-------------------+---------------------------|
|queue_relief_size |int |0 | |
|-----------------------------+----+-------------------+---------------------------|
| | | |A Net::Netmask filter (e.g.|
| | | |10.0.0.0/24, see |
| | | |Net::Netmask) that |
|trusted_upstream_proxies | | |determines whether upstream|
| | | |clients are trusted or not,|
| | | |where trusted means their |
| | | |X-Forwarded-For/etc headers|
| | | |are not munged. |
|-----------------------------+----+-------------------+---------------------------|
| | | |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 |
|upload_status_listeners | | |that have requested an |
| | | |upload status bar, which |
| | | |they request by appending |
| | | |the URL get argument |
| | | |?client_up_session=[xxxxxx]|
| | | |where xxxxx is 5-50 'word' |
| | | |characters (a-z, A-Z, 0-9, |
| | | |underscore). |
|-----------------------------+----+-------------------+---------------------------|
| | | |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.|
|verify_backend |bool|false |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 |
| | | |an actual Apache process |
| | | |yet. Using this option |
| | | |reduces end-user latency a |
| | | |ton on loaded sites. |
|-----------------------------+----+-------------------+---------------------------|
|verify_backend_path | |* |Path in the OPTIONS request|
| | | |sent by verify_backend. |
+----------------------------------------------------------------------------------+
Only for 'web_server' services:
+------------------------------------------------------------------------+
| Param | type | Default | Description |
|-------------------+------+------------+--------------------------------|
| | | | Show directory indexes when an |
| | | | HTTP request is for a |
| dirindexing | bool | false | directory. Warning: this is |
| | | | not an async operation, so |
| | | | will slow down Perlbal on |
| | | | heavily loaded sites. |
|-------------------+------+------------+--------------------------------|
| docroot | | | Directory root for web server. |
|-------------------+------+------------+--------------------------------|
| enable_delete | bool | false | Enable HTTP DELETE requests. |
|-------------------+------+------------+--------------------------------|
| enable_put | bool | false | Enable HTTP PUT requests. |
|-------------------+------+------------+--------------------------------|
| | | | Comma-seperated list of |
| index_files | | index.html | filenames to load when a user |
| | | | visits a directory URL, listed |
| | | | in order of preference. |
|-------------------+------+------------+--------------------------------|
| | | | The maximum content-length |
| | | | that will be accepted for a |
| max_put_size | size | 0 | PUT request, if enable_put is |
| | | | on. Default value of 0 means |
| | | | no limit. |
|-------------------+------+------------+--------------------------------|
| | | | If PUT requests are enabled, |
| min_put_directory | int | 0 | require this many levels of |
| | | | directories to already exist. |
| | | | If not, fail. |
+------------------------------------------------------------------------+