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.