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.
Note that you can set defaults for all services you create by using the
DEFAULT command:
DEFAULT <param> = <value>
For all 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. |
|---------------------------+----+---------------------+---------------------------|
|client_sndbuf_size |size|0 |How large to set the |
| | | |client's socket SNDBUF. |
|---------------------------+----+---------------------+---------------------------|
|enable_ssl |bool|false |Enable SSL to the client. |
|---------------------------+----+---------------------+---------------------------|
| | | |Timeout in seconds for idle|
|idle_timeout |int |30 |connections to the end user|
| | | |(default is 30) |
|---------------------------+----+---------------------+---------------------------|
| | | |The ip:port to listen on. |
| | | |For a service to work, you |
|listen | | |must either make it listen,|
| | | |or make another selector |
| | | |service map to a |
| | | |non-listening service. |
|---------------------------+----+---------------------+---------------------------|
| | | |The maximum size that will |
| | | |be accepted for a chunked |
| | | |request. Default is 200MB |
|max_chunked_request_size |size|209715200 |(which is written to disk, |
| | | |buffered uploads must be |
| | | |on). A value of 0 means no |
| | | |limit. |
|---------------------------+----+---------------------+---------------------------|
| | | |Whether to enable HTTP |
|persist_client |bool|false |keep-alives to the end |
| | | |user. |
|---------------------------+----+---------------------+---------------------------|
| | | |Timeout in seconds for HTTP|
|persist_client_idle_timeout|int |30 |keep-alives to the end user|
| | | |(default is 30) |
|---------------------------+----+---------------------+---------------------------|
| | | |Set both the |
|persist_client_timeout |int | |persist_client_idle_timeout|
| | | |and idle_timeout |
| | | |(deprecated) |
|---------------------------+----+---------------------+---------------------------|
| | | |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. |
|---------------------------+----+---------------------+---------------------------|
|server_tokens |bool|true |Whether to provide a |
| | | |"Server" header. |
|---------------------------+----+---------------------+---------------------------|
| | | |Path to directory |
|ssl_ca_path | | |containing certificates for|
| | | |SSL. |
|---------------------------+----+---------------------+---------------------------|
|ssl_cert_file | |certs/server-cert.pem|Path to certificate PEM |
| | | |file for SSL. |
|---------------------------+----+---------------------+---------------------------|
|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. |
|---------------------------+----+---------------------+---------------------------|
|ssl_verify_mode |int |0 |SSL verification mode |
|---------------------------+----+---------------------+---------------------------|
| | | |A comma separated list of |
| | | |Net::Netmask filters (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. |
+----------------------------------------------------------------------------------+
Only for 'reverse_proxy' services:
+-------------------------------------------------------------------------------+
| Param |type| Default | Description |
|-----------------------------+----+-------------------+------------------------|
| | | |The number of backend |
|backend_persist_cache |int |2 |connections to keep |
| | | |alive on reserve while |
| | | |there are no clients. |
|-----------------------------+----+-------------------+------------------------|
| | | |Flag to disable any |
| | | |modification of |
|blind_proxy |bool|false |X-Forwarded-For, X-Host,|
| | | |and X-Forwarded-Host |
| | | |headers. |
|-----------------------------+----+-------------------+------------------------|
| | | |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 |
|buffer_size |size|256k |to a 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 |
|buffer_upload_threshold_rate |int |0 |this value in bytes per |
| | | |second, it will be |
| | | |buffered to disk. Set to|
| | | |0 to not check rate. |
|-----------------------------+----+-------------------+------------------------|
| | | |If an upload is larger |
| | | |than this size in bytes,|
|buffer_upload_threshold_size |size|250k |it will be buffered to |
| | | |disk. Set to 0 to not |
| | | |check size. |
|-----------------------------+----+-------------------+------------------------|
| | | |If an upload is |
| | | |estimated to take more |
| | | |than this number of |
|buffer_upload_threshold_time |int |5 |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 will be stored in|
|buffer_uploads |bool|false |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 |
|buffer_uploads_path | | |storing files used to |
| | | |buffer uploads. |
|-----------------------------+----+-------------------+------------------------|
| | | |How many extra backend |
| | | |connections we keep |
|connect_ahead |int |0 |alive 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 |
|high_priority_cookie | | |inspect 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 Perlbal |
|persist_backend |bool|false |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 |
|pool | | |object containing the |
| | | |backend nodes that this |
| | | |reverse proxy sends |
| | | |requests to. |
|-----------------------------+----+-------------------+------------------------|
|queue_relief_chance | |0 | |
|-----------------------------+----+-------------------+------------------------|
|queue_relief_size |int |0 | |
|-----------------------------+----+-------------------+------------------------|
| | | |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 |
|reproxy_cache_maxsize |int |0 |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. |
|-----------------------------+----+-------------------+------------------------|
| | | |Executable which will be|
|server_process | | |the HTTP server on |
| | | |stdin/stdout. (ALPHA, |
| | | |EXPERIMENTAL!) |
|-----------------------------+----+-------------------+------------------------|
| | | |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) |
|upload_status_listeners | | |from clients that have |
| | | |requested an upload |
| | | |status bar, which they |
| | | |request by appending the|
| | | |URL get argument |
| | | |?client_up_sess=[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 |
|verify_backend |bool|false |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 an actual Apache|
| | | |process yet. Using this |
| | | |option reduces end-user |
| | | |latency a ton on loaded |
| | | |sites. |
|-----------------------------+----+-------------------+------------------------|
| | | |What path the OPTIONS |
|verify_backend_path | |* |request sent by |
| | | |verify_backend should |
| | | |use. Default is '*'. |
+-------------------------------------------------------------------------------+
Only for 'web_server' services:
+------------------------------------------------------------------------+
| Param |type| Default | Description |
|----------------------+----+----------+---------------------------------|
| | | |Show directory indexes when an |
| | | |HTTP request is for a directory. |
|dirindexing |bool|false |Warning: this is not an async |
| | | |operation, so will slow down |
| | | |Perlbal on heavily loaded sites. |
|----------------------+----+----------+---------------------------------|
|docroot | | |Directory root for web server. |
|----------------------+----+----------+---------------------------------|
| | | |Enable Perlbal's |
| | | |multiple-files-in-one-request |
| | | |mode, where a client have use a |
| | | |comma-separated list of files to |
| | | |return, always in text/plain. |
| | | |Useful for web apps which have |
|enable_concatenate_get|bool|false |dozens/hundreds of tiny css/js |
| | | |files, and don't trust |
| | | |browsers/etc to do pipelining. |
| | | |Decreases overall round-trip |
| | | |latency a bunch, but requires app|
| | | |to be modified to support it. See|
| | | |t/17-concat.t test for details. |
|----------------------+----+----------+---------------------------------|
|enable_delete |bool|false |Enable HTTP DELETE requests. |
|----------------------+----+----------+---------------------------------|
| | | |Enable verification of the |
|enable_md5 |bool|true |Content-MD5 header in HTTP PUT |
| | | |requests |
|----------------------+----+----------+---------------------------------|
|enable_put |bool|false |Enable HTTP PUT requests. |
|----------------------+----+----------+---------------------------------|
| | | |Comma-separated list of filenames|
|index_files | |index.html|to load when a user visits a |
| | | |directory URL, listed in order of|
| | | |preference. |
|----------------------+----+----------+---------------------------------|
| | | |The maximum content-length that |
| | | |will be accepted for a PUT |
|max_put_size |size|0 |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. |
+------------------------------------------------------------------------+