POUND(8)

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.