NAME
pound - HTTP/HTTPS reverse-proxy and load-balancer
SYNOPSIS
pound [-v] [-c] [-V] [-f config_file] [-p pid_file]
DESCRIPTION
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, based on defined priorities. By default, Pound keeps track of
associations between clients and back-end servers (sessions).
GENERAL PRINCIPLES
In general Pound needs three types of objects defined in order to
function: listeners, services and back-ends.
Listeners
A listener is a definition of how Pound receives requests from
the clients (browsers). Two types of listeners may be defined:
regular HTTP listeners and HTTPS (HTTP over SSL/TLS) listeners.
At the very least a listener must define the address and port to
listen on, with additional requirements for HTTPS listeners.
Services
A service is the definition of how the requests are answered.
The services may be defined within a listener or at the top
level (global). When a request is received Pound attempts to
match them to each service in turn, starting with the services
defined in the listener itself and, if needed, continuing with
the services defined at the global level. The services may
define their own conditions as to which requests they can
answer: typically this involves certain URLs (images only, or a
certain path) or specific headers (such as the Host header). A
service may also define a session mechanism: if defined future
requests from a given client will always be answered by the same
back-end.
Back-ends
The back-ends are the actual servers for the content requested.
By itself, Pound supplies no responses - all contents must be
received from a "real" web server. The back-end defines how the
server should be contacted.
Three types of back-ends may be defined: a "regular" back-end
which receives requests and returns responses, a "redirect"
back-end in which case Pound will respond with a redirect
response, without accessing any back-end at all, or an
"emergency" back-end which will be used only if all other
backends are "dead".
Multiple back-ends may be defined within a service, in which
case Pound will load-balance between the available back-ends.
If a back-end fails to respond it will be considered "dead", in
which case Pound will stop sending requests to it. Dead back-
ends are periodically checked for availability, and once they
respond again they are "resurected" and requests are sent again
their way. If no back-ends are available (none were defined, or
all are "dead") then Pound will reply with "503 Service
Unavailable", without checking additional services.
The connection between Pound and the back-ends is always via
HTTP, regardless of the actual protocol used between Pound and
the client.
OPTIONS
Options available (see also below for configuration file options):
-v Verbose mode: error messages will be sent to stdout even if
Pound was configured to log to syslog. This applies only to
startup messages, before Pound puts itself in the background.
Normal operational messages will still go to syslog.
-V Print version: Pound will exit immediately after printing the
current version and configuration flags.
-c Check only: Pound will exit immediately after parsing the
configuration file. This may be used for running a quick syntax
check before actually activating a server.
-f config_file
Location of the configuration file (see below for a full
description of the format). Default: /usr/local/etc/pound.cfg
-p pid_file
Location of the pid file. Pound will write its own pid into
this file. Normally this is used for shell scripts that control
starting and stopping of the daemon. Default:
/var/run/pound.pid
In general, any number of back-end servers may be specified. Use the
priority to affect the load distribution among unequal-performance
servers.
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 I
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.
CONFIGURATION FILE
Each line in the file is considered a complete configuration directive.
The directives are case-insensitive. Empty lines or lines starting in
’#’ are ignored. There are three types of directives: global directives
(they affect the settings for the entire program instance), listener
directives (they define which requests Pound will listen for), and
service directives (they affect only a specific group of requests).
GLOBAL DIRECTIVES
Global directives may appear anywhere within the configuration file,
though it is customary for them to be at the start. They may appear in
any order.
User "user_name"
Specify the user Pound will run as (must be defined in
/etc/passwd).
Group "group_name"
Specify the group Pound will run as (must be defined in
/etc/group).
RootJail "directory_path_and_name"
Specify the directory that Pound will chroot to at runtime.
Please note that OpenSSL requires access to /dev/urandom, so
make sure you create a device by that name, accessible from the
root jail directory. Pound may also require access to
/dev/syslog or similar.
Daemon 0|1
Have Pound run in the foreground (if 0) or as a daemon (if 1).
By default Pound runs as a daemon (detaches itself from the
controlling terminal and puts itself in the background). By
specifying this option you can force Pound to work like a
regular process. Useful for debugging or if you want to use
something like daemontools.
LogFacility value
Specify the log facility to use. value (default: daemon) must
be one of the symbolic facility names defined in syslog.h. This
facility shall be used for logging. Using a - for the facility
name causes Pound to log to stdout/stderr.
LogLevel value
Specify the logging level: 0 for no logging, 1 (default) for
regular logging, 2 for extended logging (show chosen backend
server as well), 3 for Apache-like format (Combined Log Format
with Virtual Host), 4 (same as 3 but without the virtual host
information) and 5 (same as 4 but with information about the
Service and BackEnd used). This value can be overridden for
specific listeners.
IgnoreCase 0|1
Ignore case when matching URLs (default: 0). This value can be
overridden for specific services.
DynScale 0|1
Enable or disable the dynamic rescaling code (default: 0). If
enabled Pound will periodically try to modify the back-end
priorities in order to equalise the response times from the
various back-ends. This value can be overridden for specific
services.
Alive value
Specify how often Pound will check for resurected back-end hosts
(default: 30 seconds). In general, it is a good idea to set this
as low as possible - it will find resurected hosts faster.
However, if you set it too low it will consume resources - so
beware.
Client value
Specify for how long Pound will wait for a client request
(default: 10 seconds). After this long has passed without the
client sending any data Pound will close the connection. Set it
higher if your clients time-out on a slow network or over-loaded
server, lower if you start getting DOS attacks or run into
problems with IE clients. This value can be overridden for
specific listeners.
TimeOut value
How long should Pound wait for a response from the back-end (in
seconds). Default: 15 seconds. This value can be overridden for
specific back-ends.
ConnTO value
How long should Pound wait for a connection to the back-end (in
seconds). Default: the TimeOut value. This value can be
overridden for specific back-ends.
Grace value
How long should Pound continue to answer existing connections
after a receiving and INT or HUP signal (default: 30 seconds).
The configured listeners are closed immediately. You can bypass
this behaviour by stopping Pound with a TERM or QUIT signal, in
which case the program exits without any delay.
SSLEngine "name"
Use an OpenSSL hardware acceleration card called name. Available
only if OpenSSL-engine is installed on your system.
Control "/path/to/socket"
Set the control socket path. If not defined Pound does not
listen for any commands. The commands may be issued by using the
poundctl(8) program.
HTTP Listener
An HTTP listener defines an address and port that Pound will listen on
for HTTP requests. All configuration directives enclosed between
ListenHTTP and End are specific to a single HTTP listener. At the very
least you must specify and address and a port for each listener. The
following directives are available:
Address address
The address that Pound will listen on. This can be a numeric IP
address, or a symbolic host name that must be resolvable at run-
time. This is a mandatory parameter. The address 0.0.0.0 may be
used as an alias for ’all available addresses on this machine’,
but this practice is strongly discouraged, as it will interfere
with the rewriting mechanisms (see below).
Port port
The port number that Pound will listen on. This is a mandatory
parameter.
xHTTP value
Defines which HTTP verbs are accepted. The possible values are:
0 (default) accept only standard HTTP requests (GET, POST,
HEAD).
1 additionally allow extended HTTP requests (PUT, DELETE).
2 additionally allow standard WebDAV verbs (LOCK, UNLOCK,
PROPFIND, PROPPATCH, SEARCH, MKCOL, MOVE, COPY, OPTIONS, TRACE,
MKACTIVITY, CHECKOUT, MERGE, REPORT).
3 additionally allow MS extensions WebDAV verbs (SUBSCRIBE,
UNSUBSCRIBE, NOTIFY, BPROPFIND, BPROPPATCH, POLL, BMOVE, BCOPY,
BDELETE, CONNECT).
4 additionally allow MS RPC extensions verbs (RPC_IN_DATA,
RPC_OUT_DATA).
Client value
Override the global Client time-out value.
CheckURL "pattern to match"
Define a pattern that must be matched by each request sent to
this listener. A request that does not match is considered to be
illegal. By default Pound accepts all requests (i.e. the
pattern is ".*"), but you are free to limit it to something more
reasonable. Please note that this applies only to the request
path - Pound will still check that the request is syntactically
correct.
Err414 "filename"
A file with the text to be displayed if an Error 414 occurs.
Default: "Request URI is too long.".
Err500 "filename"
A file with the text to be displayed if an Error 500 occurs.
Default: "An internal server error occurred. Please try again
later.".
Err501 "filename"
A file with the text to be displayed if an Error 501 occurs.
Default: "This method may not be used.".
Err503 "filename"
A file with the text to be displayed if an Error 503 occurs.
Default: "The service is not available. Please try again
later.".
MaxRequest nnn
Request maximal size. All requests will be limited to these many
bytes. If a request contains more data than allowed an error 414
is returned. Default: unlimited.
HeadRemove "header pattern"
Remove certain headers from the incoming requests. All
occurences of the matching specified header will be removed.
Please note that this filtering is done prior to other checks
(such as HeadRequire or HeadDeny), so you should not try to
check for these headers in later matches. Multiple directives
may be specified in order to remove more than one header, and
the header itself may be a regular pattern (though this should
be used with caution).
AddHeader "header: to add"
Add the defined header to the request passed to the back-end
server. The header is added verbatim.
RewriteLocation 0|1|2
If 1 force Pound to change the Location: and Content-location:
headers in responses. If they point to the back-end itself or to
the listener (but with the wrong protocol) the response will be
changed to show the virtual host in the request. Default: 1
(active). If the value is set to 2 only the back-end address is
compared; this is useful for redirecting a request to an HTTPS
listener on the same server as the HTTP listener.
RewriteDestination 0|1
If 1 force Pound to change the Destination: header in requests.
The header is changed to point to the back-end itself with the
correct protocol. Default: 0.
LogLevel value
Override the global LogLevel value.
Service [ "name" ]
This defines a private service (see below for service definition
syntax). This service will be used only by this listener. The
service may be optionally named, with the name showing in the
poundctl listings.
HTTPS Listener
An HTTPS listener defines an address and port that Pound will listen on
for HTTPS requests. All configuration directives enclosed between
ListenHTTPS and End are specific to a single HTTPS listener. At the
very least you must specify and address, a port and a server
certificate for each listener. All directives defined for HTTP
listeners are applicable to HTTPS listeners as well. The following
additional directives are also available:
Cert "certificate file"
Specify the server certificate. The certificate file is the file
containing the certificate, possibly a certificate chain and the
signature for this server. This directive is mandatory for HTTPS
listeners.
ClientCert 0|1|2|3 depth
Ask for the client’s HTTPS certificate: 0 - don’t ask (default),
1 - ask, 2 - ask and fail if no certificate was presented, 3 -
ask but do not verify. depth is the depth of verification for a
client certificate (up to 9).
Ciphers "acceptable:cipher:list"
This is the list of ciphers that will be accepted by the SSL
connection; it is a string in the same format as in OpenSSL
ciphers(1) and SSL_CTX_set_cipher_list(3).
CAlist "CAcert_file"
Set the list of "trusted" CA’s for this server. The CAcert_file
is a file containing a sequence of CA certificates (PEM format).
The names of the defined CA certificates will be sent to the
client on connection.
VerifyList "Verify_file"
Set the CA (Certificate Authority). The Verify_file is a file
that contains the CA root certificates (in PEM format).
Please note: there is an important difference between the CAlist
and the VerifyList. The CAlist tells the client (browser) which
client certificates it should send. The VerifyList defines which
CAs are actually used for the verification of the returned
certificate.
CRLlist "CRL_file"
Set the CRL (Certificate Revocation List) file. The CRL_file is
a file that contains the CRLs (in PEM format).
NoHTTPS11 0|1|2
Behave like an HTTP/1.0 server for HTTPS clients. If this value
is 0 disable the check. If the value is 1 do not allow multiple
requests on SSL connections. If the value is 2 (default) disable
multiple requests on SSL connections only for MSIE clients.
Required work-around for a bug in certain versions of IE.
Service
A service is a definition of which back-end servers Pound will use to
reply to incoming requests. A service may be defined as part of a
listener (in which case it will be used only by that listener), or
globally (which makes it available to all listeners). Pound will
always try the private services in the order defined, followed by the
global ones.
All configuration directives enclosed between Service and End are
specific to a single service. The following directives are available:
URL "pattern"
Match the incoming request. If a request fails to match than
this service will be skipped and next one tried. If all services
fail to match Pound returns an error. You may define multiple
URL conditions per service. If no URL was defined then all
requests match. The matching is by default case-sensitive, but
this can be overridden by specifying IgnoreCase 1
IgnoreCase 0|1
Override the global IgnoreCase setting.
HeadRequire "pattern"
The request must contain at least on header matching the given
pattern. Multiple HeadRequire directives may be defined per
service, in which case all of them must be satisfied.
HeadDeny "pattern"
The request may not contain any header matching the given
pattern. Multiple HeadDeny directives may be defined per
service, in which case all of them must be satisfied.
Please note: if the listener defined a HeadRemove directive, the
matching headers are removed before the service matching is
attempted.
DynScale 0|1
Enable or disable dynamic rescaling for the current service.
This value will override the value globally defined.
BackEnd
Directives enclosed between a BackEnd and the following End
directives define a single back-end server (see below for
details). You may define multiple back-ends per service, in
which case Pound will attempt to load-balance between them.
Redirect [code] "url"
This is a special type of back-end. Instead of sending the
request to a back-end Pound replies immediately with a
redirection to the given URL. You may define multiple
redirectors in a service, as well as mixing them with regular
back-ends.
The address the client is redirected to is determined by the
actual url you specify: if it is a "pure" host (i.e. with no
path) then the client will be redirected to the host you
specified, with the original request path appended. If your url
does contain a path then the request path is ignored.
Examples: if you specified
Redirect "http://abc.example"
and the client requested http://xyz/a/b/c then it will be
redirected to http://abc.example/a/b/c, but if you specified
Redirect "http://abc.example/index.html"
it will be sent to http://abc.example/index.html.
Technical note: in an ideal world Pound should reply with a "307
Temporary Redirect" status. Unfortunately, that is not yet
supported by all clients (in particular HTTP 1.0 ones), so Pound
currently replies by default with a "302 Found" instead. You may
override this behaviour by specifying the code to be used (301,
302 or 307).
Emergency
Directives enclosed between an Emergency and the following End
directives define an emergency back-end server (see below for
details). You may define only one emergency server per service,
which Pound will attempt to use if all backends are down.
Session
Directives enclosed between a Session and the following End
directives define a session-tracking mechanism for the current
service. See below for details.
BackEnd
A back-end is a definition of a single back-end server Pound will use
to reply to incoming requests. All configuration directives enclosed
between BackEnd and End are specific to a single service. The following
directives are available:
Address address
The address that Pound will connect to. This can be a numeric IP
address, or a symbolic host name that must be resolvable at run-
time. If the name cannot be resolved to a valid address, Pound
will assume that it represents the path for a Unix-domain
socket. This is a mandatory parameter.
Port port
The port number that Pound will connect to. This is a mandatory
parameter for non Unix-domain back-ends.
HTTPS [ "cert" ]
The back-end is using HTTPS. If the optional parameter cert is
specified, Pound will present this certificate to the back-end.
Priority val
The priority of this back-end (between 1 and 9, 5 is default).
Higher priority back-ends will be used more often than lower
priority ones, so you should define higher priorities for more
capable servers.
TimeOut val
Override the global TimeOut value.
ConnTO val
Override the global ConnTO value.
HAport [ address ] port
A port (and optional address) to be used for server function
checks. See below the "High Availability" section for a more
detailed discussion. By default Pound uses the same address as
the back-end server, but you may use a separate address if you
wish. This directive applies only to non Unix-domain servers.
Emergency
The emergency server will be used once all existing back-ends are
"dead". All configuration directives enclosed between Emergency and
End are specific to a single service. The following directives are
available:
Address address
The address that Pound will connect to. This can be a numeric IP
address, or a symbolic host name that must be resolvable at run-
time. If the name cannot be resolved to a valid address, Pound
will assume that it represents the path for a Unix-domain
socket. This is a mandatory parameter.
Port port
The port number that Pound will connect to. This is a mandatory
parameter for non Unix-domain back-ends.
Session
Defines how a service deals with possible HTTP sessions. All
configuration directives enclosed between Session and End are specific
to a single service. Once a sessions is identified, Pound will attempt
to send all requests within that session to the same back-end server.
The following directives are available:
Type IP|BASIC|URL|PARM|COOKIE|HEADER
What kind of sessions are we looking for: IP (the client
address), BASIC (basic authentication), URL (a request
parameter), PARM (a URI parameter), COOKIE (a certain cookie),
or HEADER (a certain request header). This is a mandatory
parameter.
TTL seconds
How long can a session be idle (in seconds). A session that has
been idle for longer than the specified number of seconds will
be discarded. This is a mandatory parameter.
ID "name"
The session identifier. This directive is permitted only for
sessions of type URL (the name of the request parameter we need
to track), COOKIE (the name of the cookie) and HEADER (the
header name).
See below for some examples.
HIGH-AVAILABILITY
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 Alive seconds, 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.
In general it is a good idea to set this time interval as low as is
consistent with your resources in order to benefit from resurected
servers at the earliest possible time. The default value of 30 seconds
is probably a good choice.
The clients that happen upon a dead backend server will just receive a
503 Service Unavailable message.
The HAport parameter specifies an additional port (and optionally an
address) that is used only for viability checks: if this port is
specified in a BackEnd directive, Pound will attempt periodically
(every Alive seconds) to connect to this port. If the port does not
respond the server is considered dead. It never makes sense to have
the HAport identical to the main back-end port: this would only
generate extra, unncecessary activity (CPU, network traffic) for no
good reason whatsoever. The HAport is meant for applications that
offer an additional health monitoring port or for installations that
wish to take servers off-line in a controlled manner.
By default the address of the HAport health monitor is the same as that
of the back-end server. You may specify a different address though, for
example if you have a monitoring program running on another host.
HTTPS HEADERS
If a client browser connects to Pound via HTTPS and if it presents a
client certificate Pound adds the following headers to the request it
issues to the server:
X-SSL-Subject
Details about the certificate owner.
X-SSL-Issuer
Details about the certificate issuer (Certificate Authority).
X-SSL-notBefore
Starting date of certificate validity.
X-SSL-notAfter
Ending date of certificate validity.
X-SSL-serial
Certificate serial number (decimal).
X-SSL-cipher
The cipher currently in use.
X-SSL-certificate
The full client certificate (PEM-format multi-line)
It is the application’s responsibility to actually use these headers -
Pound just passes this information without checking it in any way
(except for signature and encryption correctness).
SECURITY
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, and 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.
ADDITIONAL NOTES
Pound uses the system log for messages (default facility LOG_DAEMON).
The format is very similar to other web servers, so that if you want to
use a log tool:
fgrep pound /var/log/messages | your_log_tool
Translating HTTPS to HTTP is an iffy proposition: no client information
is passed to the server itself (certificates, etc) and the backend
server may be misled if it uses absolute URLs. A patch for Zope is
included in the distribution to address this issue - for other Web
servers you are on your own. May the source be with you.
Pound deals with (and sanitizes) HTTP/1.1 requests. Thus even if you
have an HTTP/1.0 server, a single connection to an HTTP/1.1 client is
kept, while the connection to the back-end server is re-opened as
necessary.
Pound attempts to resolve the names of the hosts that appear in various
requests and/or responses. That means it need a functioning resolver
of some kind (be it /etc/hosts, DNS or something else).
EXAMPLES
To translate HTTPS requests to a local HTTP server (assuming your
network address is 123.123.123.123):
ListenHTTPS
Address 1.2.3.4
Port 443
Cert "/etc/pound/server.pem"
Service
BackEnd
Address 127.0.0.1
Port 80
End
End
End
To distribute the HTTP/HTTPS requests to three Web servers, where the
third one is a newer and faster machine:
ListenHTTP
Address 123.123.123.123
Port 80
End
ListenHTTPS
Address 1.2.3.4
Port 443
Cert "/etc/pound/server.pem"
End
Service
BackEnd
Address 192.168.0.10
Port 80
End
BackEnd
Address 192.168.0.11
Port 80
End
BackEnd
Address 192.168.0.12
Port 80
Priority 3
End
End
To separate between image requests and other Web content and send all
requests for a specific URL to a secure server:
ListenHTTP
Address 123.123.123.123
Port 80
End
# Images server(s)
Service
URL ".*.(jpg|gif)"
BackEnd
Address 192.168.0.12
Port 80
End
End
# redirect all requests for /forbidden
Service
Url "/forbidden.*"
Redirect "https://xyzzy.com"
End
# Catch-all server(s)
Service
BackEnd
Address 192.168.0.10
Port 80
End
BackEnd
Address 192.168.0.11
Port 80
End
Session
Type BASIC
TTL 300
End
End
Here is a more complex example: assume your static images (GIF/JPEG)
are to be served from a single back-end 192.168.0.10. In addition,
192.168.0.11 is to do the hosting for www.myserver.com with URL-based
sessions, and 192.168.0.20 (a 1GHz PIII) and 192.168.0.21 (800Mhz
Duron) are for all other requests (cookie-based sessions). The logging
will be done by the back-end servers. The configuration file may look
like this:
User "nobody"
Group "nogroup"
RootJail "/var/pound/jail"
Alive 60
LogLevel 0
# Main listening ports
ListenHTTP
Address 1.2.3.4
Port 80
Client 10
End
ListenHTTPS
Address 1.2.3.4
Port 443
Cert "/etc/pound/pound.pem"
Client 20
End
# Image server
Service
URL ".*.(jpg|gif)"
BackEnd
Address 192.168.0.10
Port 80
End
End
# Virtual host www.myserver.com
Service
URL ".*sessid=.*"
HeadRequire "Host:.*www.myserver.com.*"
BackEnd
Address 192.168.0.11
Port 80
End
Session
Type URL
ID "sessid"
TTL 120
End
End
# Everybody else
Service
BackEnd
Address 192.168.0.20
Port 80
Priority 5
End
BackEnd
Address 192.168.0.21
Port 80
Priority 4
End
Session
Type COOKIE
ID "userid"
TTL 180
End
End
FILES
/var/run/pound.nnn
this is where Pound will attempt to record its process id.
/usr/local/etc/pound.cfg
the default configuration file (the location may be changed when
compiling - see the F_CONF flag in the Makefile).
/usr/local/etc/pound/cert.pem
the certificate file(s) for HTTPS. The location must be defined
in the configuration file - this is only a suggestion. The file
must contain a PEM-encoded certificate, optionally a certificate
chain from a known Certificate Authority to your server
certificate and a PEM-encoded private key (not password
protected). See OpenSSL(1) for details. This file should be well
protected, lest someone gets your server private key.
AUTHOR
Written by Robert Segall, Apsis GmbH.
REPORTING BUGS
Report bugs to <roseg@apsis.ch>.
COPYRIGHT
Copyright © 2002-2010 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.