| POUND(8) | System Manager's Manual | POUND(8) |
pound - HTTP/HTTPS reverse-proxy and load-balancer
Pound is a reverse-proxy load balancing server. It accepts requests from HTTP/HTTPS clients and distributes them to one or more Web servers. The HTTPS requests are decrypted and passed to the back-ends as plain HTTP.
If more than one back-end server is defined, Pound chooses one of them randomly. By default, Pound keeps track of associations between clients and back-end servers (sessions).
In general Pound needs three types of objects defined in order to function: listeners, services and back-ends.
Options available (see also below for configuration file options):
One (or more) copies of Pound should be started at boot time. Use "big iron" if you expect heavy loads: while Pound is as light-weight as we know how to make it, with a lot of simultaneous requests it will use quite a bit of CPU and memory. Multiple CPUs are your friend.
The configuration file is in standard YAML syntax. There are four blocks of directives: Global directives (they affect the settings for the entire program instance), Backends directives, defining the available backends, HTTPlisteners directives (they define which requests Pound will listen for), and HTTPSlisteners directives (same as HTTPlistener but via TLS).
A back-end is a definition of a single back-end server Pound will use to reply to incoming requests. Each backend must be marked with an anchor. The following directives are available:
An HTTP listener defines an address and port that Pound will listen on for HTTP requests. The following directives are available:
The following directives are allowed in a service definition:
All HTTPListeners directives are also available in the
HTTPSListener blocks.
The following additional directives are available:
Pound attempts to keep track of active back-end servers, and will temporarily disable servers that do not respond (though not necessarily dead: an overloaded server that Pound cannot establish a connection to will be considered dead). However, every 60 seconds (compile-time option), an attempt is made to connect to the dead servers in case they have become active again. If this attempt succeeds, connections will be initiated to them again.
The clients that happen upon a dead backend server will just receive a 503 Service Unavailable message.
In general, Pound does not read or write to the hard-disk. The exceptions are reading the configuration file and (possibly) the server certificate file(s) and error message(s), which are opened read-only on startup, read, and closed; secondly the pid file which is opened on start-up, written to and immediately closed. Following this there is no disk access whatsoever, so using a RootJail directive is only for extra security bonus points.
Pound tries to sanitise all HTTP/HTTPS requests: the request itself, the headers and the contents are checked for conformance to the RFC's and only valid requests are passed to the back-end servers. This is not absolutely fool-proof - as the recent Apache problem with chunked transfers demonstrated. However, given the current standards, this is the best that can be done - HTTP is an inherently weak protocol.
Pound uses the system log for messages (default facility LOG_DAEMON - compile-time option). The format is very similar to other web servers, so if you want to use a log tool:
fgrep pound /var/log/messages | cut -d ':' -f 4- | your_log_tool
Pound deals with (and sanitizes) HTTP/1.1 requests. Thus a single connection to an HTTP/1.1 client is kept, while the connection to the back-end server is (re)opened as necessary.
Unless you start Pound as root it won't be able to listen on privileged ports. That applies even if you do start it as root but set the User to something else.
There is no point in setting User to root: either you start as root, so you already are, or you are not allowed to setuid(0).
The two important factors in tuning the performance are the number of threads for the backends end the number of threads for the listeners.
The number of backend threads defines how many requests may be issued in parallel to a specific backend server, but also backend priorities. Increasing it may overload the web server, but setting it too low will cause longer wating ques for servicing requests. Please note that you may define several backends for the same server in order to use them in separate services.
The number of listener threads defines how many client requests can be serviced in parallel. If this number is too low for your load clients may be faced with long waiting times even when the backends are almost idle.
The simplest configuration, with Pound used strictly to sanitise requests:
Backends:
- &be
Address: 10.1.1.100
Port: 80 HTTPListeners:
- Address: 123.1.2.3
Port: 80
Services:
- Backends:
- *be HTTPSListeners:
The same thing, but with HTTPS:
Backends:
- &be
Address: 10.1.1.100
Port: 80 HTTPListeners: HTTPSListeners:
- Address: 123.1.2.3
Port: 443
Services:
- Backends:
- *be
Certificates: "cert.pem"
Client: 60
Ciphers:
- TLS-ECDHE-RSA-WITH-AES-256-GCM-SHA384
- TLS-DHE-RSA-WITH-3DES-EDE-CBC-SHA
- TLS-DHE-RSA-WITH-AES-128-CBC-SHA
- TLS-RSA-WITH-CAMELLIA-128-CBC-SHA
- TLS-RSA-WITH-AES-128-CCM
- TLS-RSA-WITH-AES-256-GCM-SHA384
- TLS-RSA-WITH-RC4-128-MD5
- TLS-RSA-WITH-3DES-EDE-CBC-SHA
To distribute the HTTP/HTTPS requests to three Web servers, where the third one is a newer and faster machine:
Backends:
- &be0
Address: 10.1.1.100
Port: 80
Threads: 8
- &be1
Address: 10.1.1.101
Port: 80
Threads: 8
- &be2
Address: 10.1.1.102
Port: 80
Threads: 12 HTTPListeners: HTTPSListeners:
- Address: 123.1.2.3
Port: 80
Threads: 32
Services:
- Backends:
- *be0
- *be1
- *be2
Certificates:
- "cert1.pem"
- "cert2.pem"
To separate between image requests and other Web content:
Backends:
- &text
Address: 10.1.1.100
Port: 80
Threads: 16
- &images
Address: 10.1.1.101
Port: 80
Threads: 16 HTTPListeners:
- Address: 123.1.2.3
Port: 80
Threads: 32
Services:
- URL: ".*.(gif|jpg|png)"
Backends:
- *images
- Session: 300
Backends:
- *text HTTPSListeners:
Written by Robert Segall, Apsis GmbH.
Report bugs to <roseg@apsis.ch>.
Copyright © 2002-2020 Apsis GmbH.
This is free software; see the source for copying conditions. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
PURPOSE.
| Jan 2010 | pound |