|POUND(8)||System Manager's Manual||POUND(8)|
- [-v] [-c] [-d level] [-f config_file] [-p pid_file]
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).
- 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.
- 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).
- 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.
- Print version: Pound will exit immediately after printing the current version.
- 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: /run/pound/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.
- 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.
- 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.
- 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.
- This defines a service. This service will be used only by this listener.
- 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.
- A list of references to previously defined backends.
- 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.
- 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.
The clients that happen upon a dead backend server will just receive a 503 Service Unavailable message.
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.
fgrep pound /var/log/messages | cut -d ':' -f 4- | your_log_tool
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).
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.
Backends: - &be Address: 10.1.1.100 Port: 80 HTTPListeners: - Address: 22.214.171.124 Port: 80 Services: - Backends: - *be HTTPSListeners:
The same thing, but with HTTPS:
Backends: - &be Address: 10.1.1.100 Port: 80 HTTPListeners: HTTPSListeners: - Address: 126.96.36.199 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: 188.8.131.52 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: 184.108.40.206 Port: 80 Threads: 32 Services: - URL: ".*.(gif|jpg|png)" Backends: - *images - Session: 300 Backends: - *text HTTPSListeners:
- this is where Pound will attempt to record its process id.
- the default configuration file (compile-time option).
This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.