Provided by: pound_3.0.2-1build1_amd64 
NAME
pound - HTTP/HTTPS reverse-proxy and load-balancer
SYNOPSIS
pound [-v] [-c] [-d level] [-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. 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. When a request is received Pound
attempts to match them to each service in turn. 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).
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.
Multiple back-ends may be used 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 Print version: Pound will exit immediately after printing the current version.
-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.
-d level
Debug mode: if level is greater than 0 error messages will be sent to stdout and Pound will stay
in the foreground. Level 0 (default) are the regular log messages, level 1 and up will produce
more detailed information.
-f config_file
Location of the configuration file (see below for a full description of the format). Default:
/etc/pound/pound.yaml
-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
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.
CONFIGURATION FILE
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).
Global Directives
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 SSL may require
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.
Err404: path_to_file
Specify a path to an HTML file to be returned in case of a 404 error.
Err405: path_to_file
Specify a path to an HTML file to be returned in case of a 405 error.
Err500: path_to_file
Specify a path to an HTML file to be returned in case of a 500 error.
Backends
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:
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. This is a mandatory parameter.
Port: port
The port number that Pound will connect to. This is a mandatory parameter.
Timeout: number
How long to wait for a backend (server) to complete and operation. Default: 15 seconds.
Threads: number
How many threads will be used to service requests to this backend. See also below for remarks on
performance tuning. Default: 8 threads.
HeadAdd: header
A header to add to each reply received from this backend. The header is a string.
HTTPListeners
An HTTP listener defines an address and port that Pound will listen on for HTTP requests. 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.
Port: port
The port number that Pound will listen on. This is a mandatory parameter.
Client: value
Define how long Pound will wait for client activity. Default: 5 seconds.
Threads: value
Define how many threads Pound will use to service client requests. Default: 8 threads.
Services:
This defines a service. This service will be used only by this listener.
Services
The following directives are allowed in a service definition:
URL: pattern
The service will only be used if the request URL matches the given pattern.
HeadRequire: pattern
Use the service only if any of the request headers matches the given pattern.
HeadDeny: pattern
Use the service only if none of the request headers matches the given pattern.
Session: number
How long to keep the client sessions (in seconds). Sessions are a long term association between a
client IP address and a specific backend in this service. A value of 0 seconds means no sessions
are kept. Default: 0.
BackEnds:
A list of references to previously defined backends.
HTTPSListeners
All HTTPListeners directives are also available in the HTTPSListener blocks.
The following additional directives are available:
Certificates:
A file name or a list of file names. Each file must contain a certificate, optionally additional
chained certificates up to a known certificate authority, and the private key corresponding to the
certificate. Note: the private key should probably not be password-protected, as Pound normally
starts as a daemon and cannot ask for the password at start-up time.
Ciphers:
A list of acceptable cipher names for this listener. The negotiation with the client will result
in one of these ciphers being used, or the hand-shake will fail.
ADDITIONAL REMARKS
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 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.
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; 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.
Additional Notes
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
(assuming messages is you log file; it may be syslog or something else, depending on your configuration).
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).
Performance Tuning Considerations
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.
EXAMPLES
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:
FILES
/var/run/pound.pid
this is where Pound will attempt to record its process id.
/etc/pound/pound.yaml
the default configuration file (compile-time option).
AUTHOR
Written by Robert Segall, Apsis GmbH.
REPORTING BUGS
Report bugs to <roseg@apsis.ch>.
COPYRIGHT
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.
pound Jan 2010 POUND(8)