POUND(8) System Manager's Manual POUND(8)

pound - HTTP/HTTPS reverse-proxy and load-balancer

pound
[-chVv] [ -f CONF-FILE] [ -p PID-FILE]

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 backends as plain HTTP.
If more than one backend server is defined, pound chooses one of them randomly, based on defined priorities. By default, pound keeps track of associations between clients and backend servers (sessions).

In general pound needs three types of objects defined in order to function: listeners, services and backends.
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. The services may be defined within a listener or at the top level (global). When a request is received, pound attempts to match them to each service in turn, starting with the services defined in the listener itself and, if needed, continuing with the services defined at the global level. 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). A service may also define a session mechanism: if defined, future requests from a given client will always be answered by the same backend.
backends
The backends 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 backend defines how the server should be contacted.
Three types of backends may be defined: a "regular" backend which receives requests and returns responses, a "redirect" backend, in which case pound will respond with a redirect response, without accessing any backend at all, or an "emergency" backend, which will be used only if all other backends are "dead".
Multiple backends may be defined within a service, in which case pound will load-balance between the available backends.
If a backend fails to respond, it will be considered "dead", in which case pound will stop sending requests to it. Dead backends are periodically checked for availability, and once they respond again they are "resurrected" and requests are sent again their way. If no backends are available (none were defined, or all are "dead") then pound will reply with "503 Service Unavailable", without checking additional services.
Normally, the connection between pound and backends is via plain HTTP. It is, however, possible to use HTTPS as well.

The following command line options are available:
-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.
-f FILE
Location of the configuration file (see below for a full description of the format). Default is $sysconfdir/pound.cfg, where $sysconfdir stands for the system configuration directory, as determined at build time. Most often it is either /usr/local/etc, or /etc.
-h
Print short command line usage summary and exit.
-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
-v
Verbose mode: error messages will be sent to stdout even if pound was configured to log to syslog. This applies only to startup messages, before pound puts itself in the background. Normal operational messages will still go to syslog.
-V
Print version: pound will exit immediately after printing the current version, licensing terms, and configuration flags.
In general, any number of backend servers may be specified. Use the priority to affect the load distribution among unequal-performance servers.

Each line in the file is considered a complete configuration directive. Empty lines and comments are ignored. Comments are introduced with a # sign and extend to the end of line on which it appears.
There are three types of directives: global directives (they affect the settings for the entire program instance), listener directives (they define which requests pound will listen for), and service directives (they affect only a specific group of requests).
In general, a directive consists of a keyword and one or more values, separated by any amount of whitespace. Leading and trailing whitespace is ignored. Keywords are case-insensitive. A value can be:
Numeric
A decimal number.
Boolean
The words yes, true, on, or 1 indicating true, and no, false, off, or 0 indicating false. All words are case-insensitive.
String
Any sequence of characters between double-quotes. A backslash is treated as an escape character: if it is followed by a double-quote or another backslash, it is removed and the character after it is read literally. If it is followed by any other character, a warning message is printed.
Identifier
A sequence of characters starting with an ASCII letter and consisting of letters, digits and underscores.
IP address
An IPv4 or IPv6 address in numeric form, or a hostname.
Unless specified otherwise, directives may appear in any order.

Global directives may appear anywhere within the configuration file, although it is customary for them to be at the start.
User "user_name"
Specify the user pound will run as (must be defined in the system user database).
Group "group_name"
Specify the group pound will run as (must be defined in the system group database).
RootJail "directory_path_and_name"
Specify the directory that pound will chroot to at runtime. Please note that OpenSSL requires 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.
Daemon bool
Have pound run in the foreground (if false) or as a daemon (if true). By default pound runs as a daemon (detaches itself from the controlling terminal and puts itself in the background). By specifying this option you can force pound to work like a regular process. Useful for debugging or if you want to use something like daemontools.
Supervisor bool
When running in daemon mode, start a supervisor process first. This process will monitor the subordinate pound process, restarting it if it fails.
Threads nnn
How many worker threads pound should use. Default: 128. Tune this parameter to improve performance. If you set it too high, pound will use a lot of memory, and some CPU will be wasted on context switches. If you set it too low, requests may be served with some delay. Experiment to find the optimal value for your installation.
LogFacility ident
Specify the log facility to use. The ident is one of the following: auth, authpriv, cron, daemon, ftp, kern, lpr, mail, news, syslog, user, uucp, local0 through local7. The default value is daemon. Using a - (dash) for the facility name causes pound to log to stdout/stderr.
LogLevel n
Specify the logging level: 0 for no logging, 1 (default) for regular logging, 2 for extended logging (show chosen backend server as well), 3 for Apache-like format (Combined Log Format with Virtual Host), 4 (same as 3 but without the virtual host information) and 5 (same as 4 but with information about the Service and Backend used). This value can be overridden for specific listeners.
IgnoreCase bool
Ignore case when matching URLs (default: false). This value can be overridden for specific services.
Alive n
Specify how often pound will check for resurrected backend hosts (default: 30 seconds). In general, it is a good idea to set this as low as possible - it will find resurrected hosts faster. However, if you set it too low it will consume resources - so beware.
Client n
Specify for how long pound will wait for a client request (default: 10 seconds). After this long has passed without the client sending any data pound will close the connection. Set it higher if your clients time-out on a slow network or over-loaded server, lower if you start getting DOS attacks or run into problems with IE clients. This value can be overridden for specific listeners.
TimeOut n
How long should pound wait for a response from the backend (in seconds). Default: 15 seconds. This value can be overridden for specific backends.
ConnTO n
How long should pound wait for a connection to the backend (in seconds). Default: the TimeOut value. This value can be overridden for specific backends.
WSTimeOut n
How long should pound wait for data from either backend or client in a connection upgraded to a WebSocket (in seconds). Default: 600 seconds. This value can be overridden for specific backends.
Grace n
How long should pound continue to answer existing connections after a receiving and INT or HUP signal (default: 30 seconds). The configured listeners are closed immediately. You can bypass this behaviour by stopping pound with a TERM or QUIT signal, in which case the program exits without any delay.
SSLEngine "name"
Use an OpenSSL hardware acceleration card called name. Available only if OpenSSL-engine is installed on your system.
ECDHcurve "name"
Use the named curve for elliptical curve encryption (default: prime256v1).
Control "/path/to/socket"
Set the control socket path. If not defined, pound does not listen for any commands. The commands may be issued by using the poundctl(8) program.
Include "/path/to/file"
Include the file as though it were part of the configuration file.
Anonymise
(alternative spelling Anonymize also accepted) Replace the last byte of the client address with 0 for logging purposes. Default: log the client address in full.

An HTTP listener defines an address and port that pound will listen on for HTTP requests. All configuration directives enclosed between ListenHTTP and End are specific to a single HTTP listener. At the very least you must specify and address and a port for each listener. 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, or a full pathname of a UNIX socket. Either this parameter or SocketFrom (see below) must be present. 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, as it will interfere with the rewriting mechanisms (see below).
Port port
The port number or service name that pound will listen on. This parameter must be present if the Address parameter contains an IPv4 or IPv6 address.
SocketFrom /path/to/socket
Read the socket to listen on from the UNIX socket given as argument. If this parameter is supplied, neither Address nor Port may be used. This parameter is intended for testing pound.
xHTTP n
Defines which HTTP verbs are accepted. The possible values are:
0 (default) accept only standard HTTP requests (GET, POST, HEAD).
1 additionally allow extended HTTP requests (PUT, PATCH, DELETE).
2 additionally allow standard WebDAV verbs (LOCK, UNLOCK, PROPFIND, PROPPATCH, SEARCH, MKCOL, MOVE, COPY, OPTIONS, TRACE, MKACTIVITY, CHECKOUT, MERGE, REPORT).
3 additionally allow MS extensions WebDAV verbs (SUBSCRIBE, UNSUBSCRIBE, NOTIFY, BPROPFIND, BPROPPATCH, POLL, BMOVE, BCOPY, BDELETE, CONNECT).
4 additionally allow MS RPC extensions verbs (RPC_IN_DATA, RPC_OUT_DATA).
Client n
Override the global Client time-out value.
CheckURL "pattern to match"
Define a pattern that must be matched by each request sent to this listener. A request that does not match is considered to be illegal. By default pound accepts all requests (i.e. the pattern is ".*"), but you are free to limit it to something more reasonable. Please note that this applies only to the request path - pound will still check that the request is syntactically correct.
Err413 "filename"
A file with the text to be displayed if an Error 413 occurs. Default: "Request too large.".
Err414 "filename"
A file with the text to be displayed if an Error 414 occurs. Default: "Request URI is too long.".
Err500 "filename"
A file with the text to be displayed if an Error 500 occurs. Default: "An internal server error occurred. Please try again later.".
Err501 "filename"
A file with the text to be displayed if an Error 501 occurs. Default: "This method may not be used.".
Err503 "filename"
A file with the text to be displayed if an Error 503 occurs. Default: "The service is not available. Please try again later.".
MaxRequest n
Request maximal size. All requests will be limited to these many bytes. If a request contains more data than allowed, an error 413 is returned. Default: unlimited.
HeadRemove "header pattern"
Remove certain headers from the incoming requests. All occurrences of the matching specified header will be removed. Please note that this filtering is done prior to other checks (such as HeadRequire or HeadDeny), so you should not try to check for these headers in later matches. Multiple directives may be specified in order to remove more than one header, and the header itself may be a regular pattern (though this should be used with caution).
AddHeader "header: to add"
Add the defined header to the request passed to the backend server. The header is added verbatim. Use multiple AddHeader directives if you need to add more than one header.
RewriteLocation 0|1|2
If set to 1, force pound to change the Location: and Content-location: headers in responses. If they point to the backend itself or to the listener (but with the wrong protocol), the response will be changed to show the virtual host in the request. Default: 1 (active). If the value is set to 2, only the backend address is compared; this is useful for redirecting a request to an HTTPS listener on the same server as the HTTP listener.
RewriteDestination bool
If set to true, force pound to change the "Destination:" header in requests. The header is changed to point to the backend itself with the correct protocol. Default: false.
LogLevel value
Override the global LogLevel value.
Service [ "name" ]
This defines a private service (see below for service definition syntax). This service will be used only by this listener. The service may be optionally named, with the name showing in the poundctl(8) listings.

An HTTPS listener defines an address and port that pound will listen on for HTTPS requests. All configuration directives enclosed between ListenHTTPS and End are specific to a single HTTPS listener. At the very least you must specify and address, a port and a server certificate for each listener. All directives defined for HTTP listeners are applicable to HTTPS listeners as well. The following additional directives are also available:
Cert "certificate file"
Specify the server certificate. The certificate file is the file containing the certificate, possibly a certificate chain and the signature for this server. This directive is mandatory for HTTPS listeners.
Please note that multiple Cert directives are allowed if your OpenSSL version supports SNI. In such cases, the first directive is the default certificate, with additional certificates used if the client requests them.
The ordering of the directives is important: the first certificate where the CN matches the client request will be used, so put your directives in the most-specific-to-least specific order (i.e. wildcard certificates after host-specific certificates).
Cert directives must precede all other SSL-specific directives.
ClientCert 0|1|2|3 depth
Ask for the client's HTTPS certificate: 0 - don't ask (default), 1 - ask, 2 - ask and fail if no certificate was presented, 3 - ask but do not verify. Depth is the depth of verification for a client certificate (up to 9). The default depth limit is 9, allowing for the peer certificate and additional 9 CA certificates that must be verified.
Disable SSLv2|SSLv3|TLSv1|TLSv1_1|TLSv1_2
Disable the protocol and all lower protocols as well. This is due to a limitation in OpenSSL, which does not support disabling a single protocol. For example, Disable TLSv1 would disable SSLv2, SSLv3 and TLSv1, thus allowing only TLSv1_1 and TLSv1_2.
Ciphers "acceptable:cipher:list"
This 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).
SSLHonorCipherOrder bool
If set to true, the server will broadcast a preference to use ciphers in the order supplied in the Ciphers directive. If the value is false, the server will accept any cipher from the Ciphers list. Default value is false.
SSLAllowClientRenegotiation 0|1|2
If this value is 0, client initiated renegotiation will be disabled. This will mitigate DoS exploits based on client renegotiation, regardless of the patch status of clients and servers related to "Secure renegotiation". If the value is 1, secure renegotiation is supported. If the value is 2, insecure renegotiation is supported, with unpatched clients. This can lead to a DoS and a Man in the Middle attack! The default value is 0.
CAlist "CAcert_file"
Set the list of "trusted" CA's for this server. The CAcert_file is a file containing a sequence of CA certificates (PEM format). The names of the defined CA certificates will be sent to the client on connection.
VerifyList "Verify_file"
Set the CA (Certificate Authority). The Verify_file is a file that contains the CA root certificates (in PEM format).
Please note: there is an important difference between the CAlist and the VerifyList. The CAlist tells the client (browser) which client certificates it should send. The VerifyList defines which CAs are actually used for the verification of the returned certificate.
CRLlist "CRL_file"
Set the CRL (Certificate Revocation List) file. The CRL_file is a file that contains the CRLs (in PEM format).
NoHTTPS11 0|1|2
Behave like an HTTP/1.0 server for HTTPS clients. If this value is 0, disable the check. If the value is 1, do not allow multiple requests on SSL connections. If the value is 2 (default), disable multiple requests on SSL connections only for MSIE clients. Required work-around for a bug in certain versions of IE.

A service is a definition of which backend servers pound will use to reply to incoming requests. A service may be defined as part of a listener (in which case it will be used only by that listener), or globally (which makes it available to all listeners). Pound will always try the private services in the order defined, followed by the global ones.
All configuration directives enclosed between Service and End are specific to a single service. The following directives are available:
URL "pattern"
Match the incoming request. If a request fails to match, then this service will be skipped and next one tried. If all services fail to match, pound returns an error. You may define multiple URL conditions per service, in which case all patterns must match. If no URL was defined, then all requests match. The matching is by default case-sensitive, but this can be overridden by specifying IgnoreCase.
IgnoreCase bool
Override the global IgnoreCase setting.
HeadRequire "pattern"
The request must contain at least on header matching the given pattern. Multiple HeadRequire directives may be defined per service, in which case all of them must be satisfied.
HeadDeny "pattern"
The request may not contain any header matching the given pattern. Multiple HeadDeny directives may be defined per service, in which case all of them must be satisfied.
Please note: if the listener defined a HeadRemove directive, the matching headers are removed before the service matching is attempted.
Disabled bool
Start pound with this service disabled ( true) or enabled (false). If started as disabled, the service can be later enabled with poundctl(8).
Backend
Directives enclosed between a Backend and the following End directives define a single backend server (see below for details). You may define multiple backends per service, in which case pound will attempt to load-balance between them.
Redirect [code] "url"
This is a special type of backend. Instead of sending the request to a backend pound replies immediately with a redirection to the given URL. You may define multiple redirectors in a service, as well as mixing them with regular backends.
The address the client is redirected to is determined by the actual url you specify: if it is a "pure" host (i.e. with no path) then the client will be redirected to the host you specified, with the original request path appended. If your url does contain a path, then the request path is ignored.
Examples: if you specified
Redirect "http://abc.example"
    
and the client requested http://xyz/a/b/c then it will be redirected to http://abc.example/a/b/c, but if you specified
Redirect "http://abc.example/index.html"
    
it will be sent to http://abc.example/index.html.
Technical note: in an ideal world pound should reply with a "307 Temporary Redirect" status. Unfortunately, that is not yet supported by all clients (in particular HTTP 1.0 ones), so pound currently replies by default with a "302 Found" instead. You may override this behaviour by specifying the code to be used (301, 302 or 307).
Emergency
Directives enclosed between an Emergency and the following End directives define an emergency backend server (see below for details). You may define only one emergency server per service, which pound will attempt to use if all backends are down.
Session
Directives enclosed between a Session and the following End directives define a session-tracking mechanism for the current service. See below for details.

A backend is a definition of a single backend server pound will use to reply to incoming requests. All configuration directives enclosed between Backend and End are specific to a single service. The following directives are available:
Address address
The address that pound will connect to. This can be a numeric IP address, a symbolic host name that must be resolvable at run-time, or a full pathname of a UNIX socket. If the name cannot be resolved to a valid address, pound will assume that it represents the path for a Unix-domain socket. This is a mandatory parameter.
Port port
The port number or service name that pound will connect to. This is a mandatory parameter for non Unix-domain backends.
HTTPS
The backend is using HTTPS.
Cert "certificate file"
Specify the certificate that pound will use as a client. The certificate file is the file containing the certificate, possibly a certificate chain and the signature. This directive may appear only after the HTTPS directive.
Disable SSLv2|SSLv3|TLSv1|TLSv1_1|TLSv1_2
Disable the protocol and all lower protocols as well. This is due to a limitation in OpenSSL, which does not support disabling a single protocol. For example, Disable TLSv1 would disable SSLv2, SSLv3 and TLSv1, thus allowing only TLSv1_1 and TLSv1_2. This directive may appear only after the HTTPS directive.
Ciphers "acceptable:cipher:list"
This 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). This directive may appear only after the HTTPS directive.
Priority n
The priority of this backend (between 1 and 9, 5 is default). Higher priority backends will be used more often than lower priority ones, so you should define higher priorities for more capable servers.
TimeOut n
Override the global TimeOut value.
ConnTO n
Override the global ConnTO value.
WSTimeOut n
Override the global WSTimeOut value.
HAport [ address ] port
A port (and optional address) to be used for server function checks. See below the "High Availability" section for a more detailed discussion. By default pound uses the same address as the backend server, but you may use a separate address if you wish. This directive applies only to non Unix-domain servers.
Disabled bool
Start pound with this backend disabled (1) or enabled (0). If started as disabled, the backend can be later enabled with poundctl(8).

The emergency server will be used once all existing backends are "dead". All configuration directives enclosed between Emergency and End are specific to a single service. 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. If the name cannot be resolved to a valid address, pound will assume that it represents the path for a Unix-domain socket. This is a mandatory parameter.
Port port
The port number that pound will connect to. This is a mandatory parameter for non Unix-domain backends.
Additionally, the following directives are also supported: TimeOut, WSTimeOut, ConnTO, HTTPS, Cert, Ciphers, Disable. These have the same meaning as in the Backend section, which see.

Defines how a service deals with possible HTTP sessions. All configuration directives enclosed between Session and End are specific to a single service. Once a session is identified, pound will attempt to send all requests within that session to the same backend server.
The following directives are available:
Type IP|BASIC|URL|PARM|COOKIE|HEADER
What kind of sessions are we looking for: IP (the client address), BASIC (basic authentication), URL (a request parameter), PARM (a URI parameter), COOKIE (a certain cookie), or HEADER (a certain request header). This is a mandatory parameter.
TTL n
How long can a session be idle (in seconds). A session that has been idle for longer than the specified number of seconds will be discarded. This is a mandatory parameter.
ID "name"
The session identifier. This directive is permitted only for sessions of type URL (the name of the request parameter we need to track), COOKIE (the name of the cookie) and HEADER (the header name).
See below for some examples.

Pound attempts to keep track of active backend 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 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 initiated 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 resurrected servers at the earliest possible time. The default value of 30 seconds is probably a good choice.
The clients that happen to hit a dead backend server will just receive a 503 Service Unavailable message.
The HAport parameter specifies an additional port (and optionally an address) that is used only for viability checks: if this port is specified in a Backend directive, pound will attempt periodically (every Alive seconds) to connect to this port. If the port does not respond, the server is considered dead. It never makes sense to have the HAport identical to the main backend port: this would only generate extra, unnecessary activity (CPU, network traffic) for no good reason whatsoever. The HAport is meant for applications that offer an additional health monitoring port or for installations that wish to take servers off-line in a controlled manner.
By default the address of the HAport health monitor is the same as that of the backend server. You may specify a different address though, for example if you have a monitoring program running on another host.

If a client browser connects to pound via HTTPS and if it presents a client certificate, 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.
X-SSL-Serial
Certificate serial number (decimal).
X-SSL-cipher
The cipher currently in use.
X-SSL-Certificate
The full client certificate (PEM-format multi-line)
It is the application's responsibility to actually use these headers -
it in any way (except for signature and encryption correctness).

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, and 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 sanitize 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 backend 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.

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 absolute 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 backend server is re-opened as necessary.
Pound attempts to resolve the names of the hosts that appear in various requests and/or responses. That means it need a functioning resolver of some kind (be it /etc/hosts, DNS or something else).

To translate HTTPS requests to a local HTTP server (assuming your network address is 192.0.2.1):
ListenHTTPS
    Address 192.0.2.1
    Port    443
    Cert    "/etc/pound/server.pem"
    Service
	Backend
	    Address 127.0.0.1
	    Port    80
	End
    End
End
To distribute the HTTP/HTTPS requests to three Web servers, where the third one is a newer and faster machine:
ListenHTTP
    Address 192.0.2.1
    Port    80
End
ListenHTTPS Address 192.0.2.1 Port 443 Cert "/etc/pound/server.pem" End
Service Backend Address 192.168.0.10 Port 80 End
Backend Address 192.168.0.11 Port 80 End
Backend Address 192.168.0.12 Port 80 Priority 3 End End
To separate between image requests and other Web content and send all requests for a specific URL to a secure server:
ListenHTTP
    Address 192.0.2.1
    Port    80
End
# Images server(s) Service URL ".*.(jpg|gif)" Backend Address 192.168.0.12 Port 80 End End
# redirect all requests for /forbidden
Service Url "/forbidden.*" Redirect "https://xyzzy.com" End
# Catch-all server(s) Service Backend Address 192.168.0.10 Port 80 End
Backend Address 192.168.0.11 Port 80 End
Session Type BASIC TTL 300 End End
Here is a more complex example: assume your static images (GIF/JPEG) are to be served from a single backend 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 backend servers. The configuration file may look like this:
User        "nobody"
Group       "nogroup"
RootJail    "/var/pound/jail"
Alive       60
LogLevel    0
# Main listening ports ListenHTTP Address 192.0.2.1 Port 80 Client 10 End
ListenHTTPS Address 192.0.2.1 Port 443 Cert "/etc/pound/pound.pem" Client 20 End
# Image server Service URL ".*.(jpg|gif)" Backend Address 192.168.0.10 Port 80 End End
# Virtual host www.myserver.com Service URL ".*sessid=.*" HeadRequire "Host:.*www.myserver.com.*" Backend Address 192.168.0.11 Port 80 End
Session Type URL ID "sessid" TTL 120 End End
# Everybody else Service Backend Address 192.168.0.20 Port 80 Priority 5 End
Backend Address 192.168.0.21 Port 80 Priority 4 End
Session Type COOKIE ID "userid" TTL 180 End End

/var/run/pound.pid
This is where pound will attempt to record its process id. The exact location is determined at compile time by the value of the --localstatedir configuration switch. It can be changed at runtime using the -p command line option. Use pound -V to inspect the actual default.
/etc/pound.cfg
The default configuration file. The exact location is determined at compile time by the value of the --sysconfdir configuration switch. It can be changed at runtime using the -f command line option. Use pound -V to inspect the actual default.
/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 certificate, optionally a certificate chain from a known Certificate Authority to your server certificate and a PEM-encoded private key (not password protected). See openssl(1) for details. This file should be well protected, lest someone gets your server private key.

Written by Robert Segall (Apsis GmbH), and Sergey Poznyakoff.

Report bugs to <gray+pound@gnu.org.ua>.

Copyright © 2002-2010 Apsis GmbH.
 
Copyright © 2018-2022 Sergey Poznyakoff
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.
November 19, 2022 pound