8:pound
From Linux Man Pages
Maintenance Procedures POUND(8)
NAME
pound - HTTP/HTTPS reverse-proxy and load-balancer
SYNOPSIS
pound
[-f config_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).
OPTIONS
Options available (see also below for configuration file
options):
-f config_file
Location of the configuration file (see below for a
full description of the format). Default:
/usr/local/etc/pound/pound.cfg
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.
Here is the directive syntax:
ListenHTTP host,port
Specify the address and port number where Pound will
listen for HTTP requests. Multiple directives imply
listening on multiple ports.
ListenHTTPS host,port cert_file [ciphers]
Specify the address and port number where Pound will
listen for HTTPS requests. cert_file is the file
pound Last change: May 2002 1
Maintenance Procedures POUND(8)
containing the certificate (and signature) for this
port; the same file may be specified for multiple ports
(as above - multiple directives imply listening on mul-
tiple ports). If specified, ciphers 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). Both ListenHTTP and
ListenHTTPS may be specified as may times as required.
HTTPSHeaders value
if value is 1, add HTTPS-specific headers. By default,
Pound passes requests unchanged to the back-end
server(s).
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 run-
time.
ExtendedHTTP value
if value is 1, allow extended HTTP requests (PUT,
DELETE). By default, Pound only allows GET, POST and
HEAD.
WebDAV value
if value is 1, allow WebDAV requests (LOCK, UNLOCK).
By default, Pound only allows GET, POST and HEAD.
LogLevel value
Specify the logging level: 0 for no logging, 1
(default) for regular logging (same format as regular
Web servers, such as Apache), 2 for extended logging
(show chosen backend server as well).
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: 30 seconds). After this long has
passed without the client sending any data Pound will
pound Last change: May 2002 2
Maintenance Procedures POUND(8)
close the connection. Set it higher if your clients
time-out on a slow network or over-loaded server, lower
is you start getting DOS attacks.
UrlGroup "pattern"
Specify a group of backend servers based on a URL pat-
tern. All requests fitting the pattern will be served
by the defined servers. Pattern is a regular pattern
as specified in regex(7) - extended version. The pat-
terns are tested in order of definition, so the last
pattern should be a catch-all .* The group ends with a
EndGroup directive.
BackEnd address,port,priority
Specify a backend server: address and port. Priority is
1 to 9 and defines a weighting - higher priority
servers get used more often. May only be used in an
UrlGroup directive. If no servers are specified, then
the specified URLs will be simply blocked.
Session TYPE [id] seconds
Specify the time (in seconds) that a session will be
kept. May be used exactly once and only in an UrlGroup
directive. TYPE is one of:
IP - the session is kept based on client IP address. No
id is allowed.
URL - the session is kept based on the value of a
parameter in the request URL. The id indicates which
parameter will be checked.
COOKIE - the session is kept based on a cookie (in the
request or the response). The id indicates which
cookie will be checked.
HeadRequire header "pattern"
Specifiy header(s) that must appear in the request.
Only requests that include the specified HTTP header
will match. May only be used in an UrlGroup directive.
The headers will be checked against the "^header: *pat-
tern$" regular pattern. As many HeadRequire directives
as necessary may appear in a single group.
HeadDeny header "pattern"
Specifiy headers that may not appear in the request.
Only requests that do not include the specified HTTP
header will match. May only be used in an UrlGroup
directive. The headers will be checked against the
"^header: *pattern$" regular pattern. As many HeadDeny
directives as necessary may appear in a single group.
pound Last change: May 2002 3
Maintenance Procedures POUND(8)
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_check 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 innitiated 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.
Set the interval to 0 to disable this feature. The clients
that happen upon a dead backend server will just receive a
503 Service Unavailable message.
HTTPS HEADERS
If a client browser connects to Pound via HTTPS and if it
presents a client certificate and if HTTPSHeaders is set,
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.
It is the application's responsability to actually use these
headers - Pound just passes this information without check-
ing 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 (pos-
sibly) the server certificate file(s), which are opened
read-only on startup, read, and closed. Following this there
is no disk access whatsoever, so using a RootJail directive
is only for extra security bonus points.
pound Last change: May 2002 4
Maintenance Procedures POUND(8)
Pound tries to sanitise all HTTP/HTTPS requests: the request
itself, the headers and the contents are checked for confor-
mance 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 abso-
lute 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.
EXAMPLES
To translate HTTPS requests to a local HTTP server (assuming
your network address is 123.123.123.123):
ListenHTTPS 123.123.123.123,443 /etc/pound/server.pem
UrlGroup ".*"
BackEnd 127.0.0.1,80,1
EndGroup
To distribute the HTTP/HTTPS requests to three read-only Web
servers, where the third one is a newer and faster machine:
ListenHTTP 123.123.123.123,80
ListenHTTPS 123.123.123.123,443 /etc/pound/server.pem
UrlGroup ".*"
BackEnd 192.168.0.10,80,1
BackEnd 192.168.0.11,80,1
BackEnd 192.168.0.12,80,3
EndGroup
To distribute the HTTP/HTTPS requests to two Web servers
with long session times; also change the uid/gid of the run-
ning program and do a chroot:
pound Last change: May 2002 5
Maintenance Procedures POUND(8)
ListenHTTP 123.123.123.123,80
ListenHTTP 123.123.123.123,8080
ListenHTTPS 123.123.123.123,443 /etc/pound/server.pem
User www
Group www
RootJail /var/pound
UrlGroup ".*"
BackEnd 192.168.0.10,80,1
BackEnd 192.168.0.11,80,1
Session IP 600
EndGroup
To separate between image requests and other Web content and
block all requests for a specific URL:
ListenHTTP 123.123.123.123,80
# Images server(s)
UrlGroup ".*.(jpg|gif)"
BackEnd 192.168.0.12,80,1
EndGroup
# Block all requests for /forbidden
UrlGroup "/forbidden.*"
EndGroup
# Catch-all server(s)
UrlGroup ".*"
BackEnd 192.168.0.10,80,1
BackEnd 192.168.0.11,80,1
Session IP 300
EndGroup
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 confi-
guration file may look like this:
# Main listening ports
ListenHTTP 1.2.3.4
ListenHTTPS 1.2.3.4,443 /etc/pound/pound.pem
User nobody
Group nogroup
RootJail /var/pound/jail
Client 15
Alive 60
HTTPSHeaders 1
pound Last change: May 2002 6
Maintenance Procedures POUND(8)
LogLevel 0
# Image server
UrlGroup ".*.(jpg|gif)"
BackEnd 192.168.0.10,80,1
EndGroup
# Virtual host www.myserver.com
UrlGroup ".*sessid=.*"
HeadRequire ".*www.myserver.com"
BackEnd 192.168.0.11,80,1
Session URL sessid 120
EndGroup
# Everybody else
UrlGroup ".*"
BackEnd 192.168.0.11,20,5
BackEnd 192.168.0.11,21,4
Session COOKIE userid 180
EndGroup
FILES
/var/run/pound.pid
this is where Pound will attempt to record its process
id.
/usr/local/etc/pound/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 certi-
ficate and a PEM-encoded private key (not password pro-
tected). 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 O 2002 Apsis GmbH.
This is free software; see the source for copying condi-
tions. There is NO warranty; not even for MERCHANTABILITY
or FITNESS FOR A PARTICULAR PURPOSE.
pound Last change: May 2002 7