view release on metacpan or  search on metacpan

lib/Perlbal/Manual/ReverseProxy.pod  view on Meta::CPAN

=head1 NAME

Perlbal::Manual::ReverseProxy - Configuring Perlbal as a Reverse Proxy


=head2 VERSION

Perlbal 1.78.


=head2 DESCRIPTION

How to configure a Perlbal Reverse Proxy service.


=head2 READ ME FIRST

Please read L<Perlbal::Manual::Configuration> first for a better explanation on how to configure Perlbal. This document will make much more sense after reading that.


=head2 Configuring Perlbal as a Reverse Proxy

Configuration of Perlbal as a Reverse Proxy is similar to configuration as a Load Balancer.

Check L<Perlbal::Manual::LoadBalancer> under C<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.


=head2 Parameters

You can set parameters via commands of either forms:

    SET <service-name> <param> = <value>
    SET <param> = <value>


=over 8

=item B<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.


=item B<backend_persist_cache> = int

The number of backend connections to keep alive on reserve while there are no clients.

Default is 2.


=item B<blind_proxy> = bool

Flag to disable any modification of X-Forwarded-For, X-Host, and X-Forwarded-Host headers.

Default is false.


=item B<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 C<buffer_uploads> is enabled, this value is used to determine how many bytes are read before Perlbal makes a determination on whether...

Default is 100k.


=item B<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.


=item B<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 C<buffer_size> (50k instead of 256k) becau...

Default if 50k.


=item B<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.


=item B<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.


=item B<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.


=item B<buffer_uploads> = bool

Used to enable or disable the buffer uploads to disk system. If enabled, C<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 uplo...

Default if false.


=item B<buffer_uploads_path> = path/to/directory

Directory root for storing files used to buffer uploads.


=item B<client_sndbuf_size> = I<size>

lib/Perlbal/Manual/ReverseProxy.pod  view on Meta::CPAN

=item B<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 L<Perlbal::Manual::HighPriority> for more information.


=item B<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 L<Perlbal::Manual::HighPriority> for more information.


=item B<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 an...

Default is 0, which means cache is disabled.


=item B<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-detecte...


=item B<server_process>

Executable which will be the HTTP server on stdin/stdout. (B<ALPHA>, B<EXPERIMENTAL>)


=item B<ssl_cert_file> = path/to/file

Path to certificate PEM file for SSL.

Default is C<certs/server-cert.pem>.


=item B<ssl_cipher_list> = cipher list

OpenSSL-style cipher list.

Default is C<ALL:!LOW:!EXP>.


=item B<ssl_key_file> = path/to/file

Path to private key PEM file for SSL.

Default is C<certs/server-key.pem>.


=item B<trusted_upstream_proxies> = Net::Netmask filter

A comma separated list of L<Net::Netmask> filters (e.g. 10.0.0.0/24, see L<Net::Netmask>) that determines whether upstream clients are trusted or not, where trusted means their X-Forwarded-For/etc headers are not munged.


=item B<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 ...


=item B<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 ...

Default if false.


=item B<verify_backend_path> = path

What path the OPTIONS request sent by C<verify_backend> should use.

Default is C<*>.

=item B<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 C<on>.

=back


=head2 More on Parameters

=head3 backend_persist_cache vs. connect_ahead

The C<backend_persist_cache> parameter refers to connections kept alive after being used, while C<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:

=over 4

=item * Perlbal starts

No connections open until the very first request comes in (this may change in the future).

=item * one requests arrives

This request starts being served on the open connection; Perlbal opens another connection because C<connect_ahead>'s value tells it to always open one in anticipation.

=item * 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.