POUND(8) System Manager's Manual POUND(8) NAME pound - HTTP/HTTPS reverse-proxy and load-balancer SYNOPSIS pound [-FVcehv] [-W [no-]FEATURE] [-f CONF-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 (back- ends). These requests may be passed to backends as plain HTTP or re-en- crypted as HTTPS. If more than one backend server is defined, pound chooses one of them ran- domly, based on the requested balancing algorithm and backend priorities. By default, pound keeps track of associations between clients and backend servers (sessions). GENERAL PRINCIPLES 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). Listeners of two types are supported: regular HTTP listeners and HTTPS listeners. In the simplest case, a lis- tener must define the address and port to listen on, with additional requirements for HTTPS listeners. Services A service routes requests to backends. Services may be defined within a listener or in global scope. When a request is received, pound attempts to match it to each service in turn, starting with the services defined in the listener itself and, if needed, continu- ing with those defined at the global level. Services may define their own conditions as to which requests they can answer: typically this involves certain URLs (e.g. images only, or a certain path) or specific headers (such as the Host header). A service may also de- fine a session mechanism: if so, future requests from a given client will always be answered by the same backend. Backends Backends define where to obtain the content requested. Most often, they refer to "real" web servers and define how to contact them. Several types of backends are defined: Regular backend Regular backends are the most often used type of backends and the raison d'etre of pound. A regular backend passes re- ceived requests to a backend server, waits for it to respond and sends the response back to the requesting client. Emergency backend A special case of regular backend which will be used only if all other regular backends fail to respond. Redirect backend A redirect backend responds to each request with a redirect response. See Redirect, below. ACME backend A special backend designed to handle ACME challenges. Back- ends of this type are used to handle HTTP-01 authorization when re-issuing LetsEncrypt certificates. See the ACME section below. Error backend The error backend creates and returns a predefined HTTP sta- tus response. Static file backend This backend responds with a contents of a disk file. Multiple regular or emergency backends may be defined within a ser- vice, in which case pound will balance the load between the avail- able backends. Two types of load-balancing strategies are implemented: random bal- ancing (default), and interleaved weighted round-robin balancing. If a regular 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 check- ing additional services. Normally, pound communicates with its backends via plain HTTP. It is, however, possible to use HTTPS as well. A working pound configuration may define multiple listeners and services. They can be identified either by 0-based ordinal number within the configu- ration (or, for services, within the listener) or by their symbolic name. Backends are identified by their ordinal number within the service. REQUEST BALANCING Load balancing strategy defines algorithm used to distribute incoming re- quests between multiple regular backends. Each backend is assigned a pri- ority -- a positive number indicating its relative weight among other back- ends. The share of requests a backend handles can be estimated as: Pi / S(P), where Pi is priority of the backend with index i, and S(P) is sum of all priorities. Two balancing strategies are implemented: Weighted Random Balancing This is the default strategy. The backend to use for each request is determined at random taking into account backend priorities, so that backends with numerically greater priorities have proportion- ally greater chances of being selected than the ones with lesser priorities. Interleaved Weighted Round Robin Balancing This strategy cycles over all active backends, considering each one in its turn. An integer ordinal number is assigned to each round, which is incremented (modulo number of backends) each time a new round is started. A backend is assigned a request only if its pri- ority is greater than the round number. This strategy offers several advantages compared with the previous one. First, it results in a more even distribution of the requests. Secondly, the resulting distribution is predictable. Within each Service, multiple backends are grouped in balancer groups. Each such group is assigned a unique integer priority, which defines the order in which the groups are tried. When selecting a backend, a group with the numerically lesser priority is selected and a suitable backend is looked up among backends defined in the group, using one of the balancing strategies discussed above. If no backend can be selected (e.g. all back- ends are unavailable), next group is tried. The process continues until either a backend is chosen or the list of balancer groups is exhausted. By default, backends declared using the Backend keyword are assigned to the balancer group 0. These are backends used during normal operation. Back- ends declared using the Emergency keyword are assigned to the balancer group 65535. These backends form a pull of high availability backends, which will be tried only if all of the normal backends fail. More backend groups can be added using dynamic backends, discussed below. WORKER MODEL Each incoming connection is assigned to a specific worker, i.e. a thread in the running program. This worker processes all requests that arrive via that connection. The number of running workers is controlled by three con- figuration parameters. WorkerMinCount defines the minimum number of work- ers that should always be running (5, by default). Another parameter, Work- erMaxCount sets the upper limit on the number of running workers (it de- faults to 128). At each given moment, a worker can be in one of two states: idle or active (handling a connection). If an incoming connection arrives when all run- ning workers are active, and total number of workers is less than Worker- MaxCount, a new worker is started and the new connection is handed to it. If the number of active workers has already reached maximum, the new con- nection is added to the connection queue, where it will wait for a worker to become available to process it. If the queue becomes full as well, the program stops accepting new connections until at least one worker becomes available again. The third parameter, WorkerIdleTimeout, specifies maximum time a thread is allowed to spend in the idle state. If a worker remains idle longer than that and total number of workers is greater than the allotted minimum (WorkerMinCount), the idle worker is terminated. The capacity of the connection queue is computed so as to accept as many connection requests as is permitted by the current system limit on the open files. It can also be set using the ConnectionQueueSize configuration di- rective. OPTIONS The following command line options are available: -c Check only: pound will exit immediately after parsing the configura- tion file. This may be used for running a quick syntax check before actually activating a server. -e Log to standard error (standard output for LOG_DEBUG and LOG_INFO severity levels). Both standard streams are set to line buffering mode. This option implies foreground mode (-F) and overrides the LogLevel configuration setting. -F Foreground mode. The program will not detach from the controlling terminal and will remain in foreground after startup. This over- rides the Daemon configuration setting. The log stream (syslog fa- cility or stderr) requested in the configuration remains in effect. See also the -e option, above. -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. See the description of PIDFile statement in the GLOBAL DIRECTIVES section below, for a detailed discussion of this file. -v Verbose mode: during startup, error messages will be sent to stderr (stdout for LOG_DEBUG and LOG_INFO severity levels). If pound was configured to log to syslog, error diagnostics will be duplicated there as well. After startup the configuration settings take ef- fect. -V Print version: pound will exit immediately after printing the cur- rent version, licensing terms, and configuration flags. -W [no-]FEATURE Enable or disable (if prefixed with no-) additional pound features. As of this version, the following FEATUREs are implemented: [no-]warn-deprecated Warn if any deprecated statements are used in configuration file. [no-]dns Resolve host names found in configuration file. This is the default. You can disable it if your configuration file refers to backends only by their IP addresses, in order to suppress potentially lengthy network host address lookups. no-include-dir Don't set the include directory to the system configuration directory. This means that each relative filename used in arguments to the directives in the configuration file will be looked up in the current working directory. This feature is useful mainly in testsuite. include-dir=DIR Override the default include directory setting. Set it to DIR. See the discussion of the IncludeDir directive in sec- tion GLOBAL DIRECTIVES, below. CONFIGURATION FILE 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, sepa- rated by any amount of whitespace. Leading and trailing whitespace is ig- nored. 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 consist- ing 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 Global directives may appear anywhere at the top level within the configu- ration file, although it is customary for them to be at the start. Program settings Daemon bool Instructs pound to run in the foreground (if false) or as a daemon (if true). By default pound runs as a daemon (i.e. detaches itself from the controlling terminal and continues operating in the back- ground). By setting this directive to false you can force pound to work like a regular process. See also -F and -e options, above. Balancer random | iwrr Defines the load-balancing strategy to use. Possible arguments are: random, to use weighted random balancing algorithm, and iwrr, mean- ing interleaved weighted round robin balancing. See REQUEST BALANC- ING, above, for a detailed discussion of these balancing strategies. The Balancer statement in the global scope applies to all Service directives that don't contain Balancer definitions of their own. Constant "NAME" [OPTIONS] ["VALUE"] Defines a configuration constant for use in string expansions and Lua code. NAME gives the name of the constant. Either OPTIONS or VALUE must be given, but not both. If OPTIONS are not given, VALUE supplies the value for the constant. Otherwise, the value is assigned as described in the table below: -file "FILENAME" Use contents of the file "FILENAME". The contents is treated as an opaque binary string. The file is read exactly once, at program startup. -filewatch "FILENAME" Same as -file, except that FILENAME is monitored for changes during the runtime. Whenever the file changes, it will be re-read, and the constant will be updated, without the need to restart the program. -trim Used with one of the above, instructs pound to treat FILENAME as a plain text file, and remove from its contents all trail- ing whitespace characters, i.e. horizontal tabulation (ASCII 9), newline (ASCII 10), vertical tabulation (ASCII 11), form feed (ASCII 12), carriage return (ASCII 13), and space (ASCII 32). ConnectionQueueSize "N" Set the capacity of the incoming connection queue. The default value is computed as a function of WorkerMaxCount and the system limit on open file descriptors. See the description in WORKER MODEL , and that of the ReserveFD statement, below. Control "pathname" Set the control socket path. See the Control socket section below, for a detailed description of this feature. IgnoreCase bool Ignore letter case when doing regex matching (default: false). This directive sets the default for the following service matching direc- tives: URL, Path, QueryParam, Query, StringMatch, as well as for the DeleteHeader modification directive. Its value can be overridden for specific services. This statement is deprecated and will be removed in future versions. Please, use the -icase option to the service matching directive in- stead. See the discussion of options in Service Matching Directives section below. LineBufferSize N Sets the line buffer size. Line buffer is used when reading request line, backend response status line, and header fields in both re- quests and responses. Thus, this value limits the maximum length allowed for these parts of HTTP messages. By default, it is set to the internal buffer size (4096 bytes, configurable at compile time using the --with-maxbuf option). It cannot be set to a value less than that default. PIDFile "filename" Sets the name of the file where to store program PID. It can be overridden by the -p command line option. Notice the following: 1. When running with a supervisor, this file holds PID of the supervisor process. Otherwise, it holds PID of the main pound process. This means it is always suitable for sig- nalling the program using the traditional kill `cat filename` technique. 2. Before shutting down, pound removes this file. However, this may not be possible if it switches to privileges of another user after startup (i.e. at least one of User or Group are set in the configuration file) and the file is stored in a directory whose permissions forbid write access for that user. RegexType posix | pcre | perl Sets the type of regular expressions to use in request matching statements. posix selects POSIX extended regular expressions and pcre or perl select Perl-compatible regular expressions. The latter requires compile-time support. The selected regular expression type remains in effect until next RegexType statement or end of the con- figuration file, whichever occurs first. ReserveFD [-worker] N Reserve N additional file descriptors for the purpose of computing the capacity of the incoming connection queue. If the -worker op- tion is given, increases number of file descriptors per worker thread (default value: 2). Otherwise, increases number of reserved global descriptors (default value: 3). 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 N This statement, retained for backward compatibility with previous versions of pound, is equivalent to: WorkerMinCount N WorkerMaxCount N WorkerIdleTimeout SEC Sets idle timeout for a worker thread. Default is 30 seconds. See the section WORKER MODEL above for a detailed discussion. WorkerMinCount N Sets minimum number of worker threads that must always be running. The default is 5. See the section WORKER MODEL above for a detailed discussion. WorkerMaxCount N Sets maximum number of worker threads. The default is 128. See the section WORKER MODEL above for a detailed discussion. WorkerStackSize N Sets worker stack size, in bytes. The default size is 262144. Privilege selection 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" Specify the directory that pound will chroot to at runtime. SSL engine settings SSLEngine "name" Use an OpenSSL hardware acceleration card called name. Available only if OpenSSL-engine is installed on your system. Logging 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. LogFacility ident Specify the log facility to use. 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 std- out/stderr. LogFormat "name" "format_def" Define HTTP log format. Name is a string uniquely identifying this format. Format_def is the format string definition. See below, section REQUEST LOGGING, for a detailed description. LogLevel n Specify the logging level using built-in format indices: 0 for no logging, 1 (default) for regular logging, 2 for extended logging (show chosen backend server as well), 3 for Apache-like format (Com- bined Log Format with Virtual Host), 4 (same as 3 but without the virtual host information) and 5 (same as 3 but with information about the Service and Backend used). This value can be overridden for specific listeners. See below, section REQUEST LOGGING, for a detailed description. LogLevel "name" Select a named format for logging HTTP requests. Name can be either one of five built-in format names (null, regular, extended, vhost_combined, combined, or detailed), corresponding to the numeric indices discussed above, or a format name defined earlier via the LogFormat directive. See section REQUEST LOGGING, for a detailed discussion. LogTag "string" Sets the string to tag log messages with. This is used when log output goes to syslog. Default is the name with which pound was started. ForwardedHeader name Defines the name of the HTTP header that carries the list of proxies the request has passed through. It is used to report the originator IP address when logging. See the description of %a specifier in RE- QUEST LOGGING. The default is X-Forwarded-For. TrustedIP Defines a list of trusted proxy IP addresses, which is used to de- termine the originator IP. See the description of %a specifier in REQUEST LOGGING, for a detailed discussion. This statement is a special form of ACL statement, described below. It can appear as an anonymous ACL (section), file reference, or as an ACL reference. In anonymous ACL form, it is followed by a list of one or more CIDRs each appearing on a separate line. The End keyword terminates the statement, e.g.: TrustedIP "127.0.0.1/8" "10.16.0.0/16" End In file reference form, the statement is: TrustedIP -file "filename" or TrustedIP -filewatch "filename" and the list of IP addresses is read from file filename. When used with -filewatch, the file will be watched for changes and reloaded when such occur. In ACL reference form, this statement takes single argument, the name of the access control list defined earlier using the ACL state- ment, e.g. TrustedIP "proxy_addresses" Timeouts 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, or lower it down if you start getting DOS attacks or run into problems with IE clients. This value can be overridden for specific listeners. ConnTO n How long should pound wait for a connection to the backend (in sec- onds). Default: the TimeOut value. This value can be overridden for specific backends. Grace n How long should pound continue to answer existing connections after a receiving a INT or HUP signal (default: 30 seconds). The config- ured listeners are closed immediately. You can bypass this behaviour by stopping pound with a TERM or QUIT signal, in which case the pro- gram exits without any delay. TimeOut n How long should pound wait for a response from the backend (in sec- onds). Default: 15 seconds. This value can be overridden for spe- cific 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 sec- onds. This value can be overridden for specific backends. WatcherTTL N If conditions with -filewatch flag are used, and the underlying op- erating system doesn't provide file system monitoring API (inotify or kqueue), this directive defines the interval between two succes- sive checks of file modification times. Header manipulation CombineHeaders ... End Declare names of the headers that can appear multiple times in a message, and that should be combined into one value. Header names must appear one per line between CombineHeaders and End. See the section MULTI-VALUE HEADERS, for a detailed discussion of this feature. HeaderOption opt... Sets default options for header addition. opt is one of: none to disable additional headers, forwarded to enable adding X-For- warded-For, X-Forwarded-Proto, and X-Forwarded-Port headers, and ssl to enable passing information about SSL certificates in various X-SSL-* headers. The option may be prefixed with no- in which case it disables the corresponding header group. The default is HeaderOption forwarded ssl This setting can be overridden on a per-listener basis. See the de- scription of HeaderOption directive in HTTP Listener section, and section BUILT-IN HEADERS, for a detailed discussion of various header modification directives and their effect. File inclusion IncludeDir "dir" Sets the include directory. This is the directory where pound looks for relative file names that appear in other configuration direc- tives (e.g. Include). The default value is the system configuration directory as set at compile time (you can check its value in the output of pound -V). This initial value can be changed in the com- mand line using the -W include-dir=name option or reset to the cur- rent working directory using the -W no-include-dir option (see the discussion of -W below). The directory set by IncludeDir statement remains in effect until next IncludeDir statement is encountered, or end of input, whichever occurs first. Include "file" Include the file as though it were part of the configuration file. If file is a relative file name, it will be looked in the include directory (see above). If file is a shell globbing pattern (glob(7)), all regular files matching that pattern will be included. The list or files will be sorted lexicographically. This directive is allowed both at topmost level and in any subsec- tions of the configuration file. Access control lists ACL "name" Define a named access control list (ACL). An ACL is a list of net- work addresses in CIDR notation, one address per line, terminated with an End directive on a line by itself. E.g.: ACL "secure" "192.0.2.0/26" "203.0.113.0/24" End The Include directive is allowed within ACL. Named ACLs can be used in Service definitions to make services available from certain IP addresses only. ACL "name" -file "filename" Same as above, but reads ACL definition from file filename. The name is taken relative to the IncludeDir directory, unless it starts with a slash. The ACL file should contain one CIDR per line. Empty lines and com- ments are allowed. ACL "name" -filewatch "filename" Same as above, but filename will be watched for changes during the runtime. Once a change is detected, the file will be reloaded and the ACL updated. If possible, this uses OS-specific API (inotify(7), on GNU/Linux and kqueue(7) on *BSD systems). On systems that don't provide such an API the file will be checked for changes periodically. The interval between two successive checks is defined by the WatcherTTL setting. Detached conditions Condition "NAME" ... End Saves away a set of conditional statements for further evaluation. Ellip- sis represents a sequence of conditional statements as described in section Service Matching Directives. The detached condition can be used where a normal conditional is allowed, using the following construct: Eval "NAME" Detached conditions are evaluated at most once. Result of evaluation is cached and used by all subsequent Eval statements that refer to the same NAME. Control socket Pound can be instructed to listen for management requests, which will allow you to obtain information about the running instance, change state of con- figured listeners, services, and backends, etc. These requests may be is- sued by using the poundctl(8) utility. Usually, a UNIX socket is used to communicate with the management inter- face. It is configured via the Control statement. This statement has two forms. In inline form, it takes a single argument, specifying the name of the UNIX socket file to create and listen on. For example: Control "/run/pound.sock" The file will be owned by the user that started pound (normally root) and will have mode 0600. The block form allows you to specify file mode and, to certain extent, the socket file ownership: Control Socket "/run/pound.sock" Mode 660 ChangeOwner true End The substatements are: Socket filename Specifies the name of the socket file to use. This is the only mandatory statement in the block form. Mode octal Sets the mode of the socket file. ChangeOwner bool This statement takes effect if at least one of User or Group global statements is used. When set to true it will change the owner of the socket file to that specified by those two statements. It is also possible to have pound listen for management requests on an INET or INET6 address. See description of the Control statement in section Backend definitions, below. HTTP Listener An HTTP listener defines an address and port that pound will listen on for HTTP requests. The listener declaration begins with the keyword ListenHTTP on a separate line. The keyword may be followed by a quoted string supply- ing listener name. This name is a unique label that identifies the lis- tener. All configuration directives enclosed between ListenHTTP and End are spe- cific to a single HTTP listener. At the very least you must specify IP ad- dress and, optionally, port for each listener. The following directives are available: Address address The address that pound will listen on. This can be a numeric IP ad- dress, or a full pathname of a UNIX socket. If neither this direc- tive nor SocketFrom (see below) is given, ::0 is assumed. Port port The port number or service name that pound will listen on. If not given, default port number is assumed, i.e. 80, for ListenHTTP, and 443, for ListenHTTPS (see below). SocketFrom "pathname" 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 directive 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, UNSUB- SCRIBE, NOTIFY, BPROPFIND, BPROPPATCH, POLL, BMOVE, BCOPY, BDELETE, CONNECT). Client n Override the global Client time-out value. CheckURL "pattern" 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. Constant "NAME" [OPTIONS] ["VALUE"] Defines a configuration constant for use in string expansions and Lua code. See Constant in section GLOBAL DIRECTIVES, for a detailed discussion of its arguments and their meaning. Per-listener constants augment global ones. If the name of a per- listener constant coincides with the name of a globally defined one, the former overrides the latter for all services defined in that listener. ErrorFile NNN "filename" Read the content to be returned along with the HTTP status code NNN from the file filename. The file will be read exactly once, at the program startup. The file can begin with one or more HTTP headers, separated from the actual body with an empty line (i.e., two newline characters). These headers will be returned along with the response. This can be used, in particular, to change the response content type, which is text/html by default. Allowed values for NNN are: 400, 401, 404, 405, 413, 414, 500, 501, 503. ErrNNN "filename" This statement is equivalent to ErrorFile NNN "filename" See above for the allowed values of NNN. This form is provided for compatibility with previous versions of the program. It will be removed in future releases. RewriteErrors bool If bool is true, this enables backend error response rewriting, i.e. replacing the content of error responses returned by a regular back- end with a custom error text defined by the ErrorFile statement. See ERROR RESPONSE REWRITING, for a detailed discussion of this fea- ture. The same statement can also appear in Service block, in which case it overrides the settings of the listener. LineBufferSize N Sets the line buffer size. Line buffer is used when reading request line, backend response status line, and header fields in both re- quests and responses. The default is inherited from the global set- ting. MaxRequest n Maximum allowed size of incoming request. All requests will be lim- ited to these many bytes. If a request contains more data than al- lowed, an error 413 is returned. Default: unlimited. MaxURI n Maximum allowed length of an URI. If the URI of a request is longer than n bytes, an error 414 is returned. Default: unlimited. RewriteLocation 0|1|2 If set to 1, force pound to change the Location: and Content-loca- tion: 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 (ac- tive). If the value is set to 2, only the backend address is com- pared; 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 re- quests. The header is changed to point to the backend itself with the correct protocol. Default: false. LogLevel n Log HTTP requests using built-in format n. This statement config- ures logging specific for this listener, overriding the global LogLevel setting. See REQUEST LOGGING, for a detailed discussion. LogLevel "name" Select a named format for logging HTTP requests. Name can be either one of five built-in format names (null, regular, extended, vhost_combined, combined, or detailed), or a format name defined earlier via the LogFormat directive. This statement configures logging specific for this listener, over- riding the global LogLevel setting. See section REQUEST LOGGING, for a detailed discussion. ForwardedHeader name Defines the name of the HTTP header that carries the list of proxies the request has passed through. It is used to report the originator IP address when logging. See the description of %a specifier in RE- QUEST LOGGING. This statement overrides the ForwardedHeader direc- tive from the global scope. The default is X-Forwarded-For. TrustedIP Defines a list of trusted proxy IP addresses, which is used to de- termine the originator IP. See the description of %a specifier in REQUEST LOGGING, for a detailed discussion. This statement overrides the TrustedIP directive from the global scope. Service [ "name" ] This defines a private service (see below for service definition syntax). This service will be used only by this listener. Optional name supplies the label, that can be used in poundctl(8) requests to identify the service. This label must be unique among all services within the enclosing listener, or, for global services, within the configuration. ACME "directory" Serve ACME challenge requests from the given directory. See section ACME below. HeaderOption opt... Modifies global header addition options for this listener. Global options are set by the HeaderOption directive in the global scope and default to forwarded ssl. opt is one of: all Enable all additional headers. none Disable all additional headers. forwarded Enable adding X-Forwarded-For, X-Forwarded-Proto, and X-For- warded-Port headers. ssl Enable passing information about SSL certificates in various X-SSL-* headers. Each option except none can be prefixed with no- to revert its mean- ing. For example, to disable adding the X-SSL-* headers for a listener, one would use: HeaderOption no-ssl See the description of HeaderOption directive in GLOBAL DIRECTIVES section, and section BUILT-IN HEADERS, for a detailed discussion of various header modification directives and their effect. String expansion Some of the statements described below take as their arguments string val- ues that undergo several expansions before use. These expansions are as follows: Backreference expansion Backreference is a construct that refers to a parenthesized group within a regular expression matched by one of service matching di- rectives (see the section Service Matching Directives, below). Dur- ing backreference expansion, each occurrence of such construct in a string is replaced with the actual value of that parenthesized group. Syntactically a backreference can take two forms. The construct $N (where N is a decimal number) refers to Nth parenthesized subexpres- sion of the most recently matched statement, and $N(M) refers to Nth parenthesized subexpression of Mth recently matched statement. Num- bering of subexpressions starts at 1 ($0 refers to the entire match- ing string). Numbering of matched statements starts at 0. Conditional statements can also be tagged using the -tag T option. When referring to a subexpression in such a statement, the form $N(T) can be used. For example, given the following statements Host -tag "host" -re "www\.(.+)" Header -tag "type" -re -icase "^Content-Type: *(.*)" Path -tag "dir" "^/static(/.*)?" $1 or $1(dir) refers to the subgroup of Path, $1(1) or $1(type) - to that of Header, and $1(2) or $1(host) - to that of Host. Curly braces may be used to avoid incorrectly parsing text fragment that follows the reference as being its part. This is useful if the reference is immediately followed by a decimal digit or opening parenthesis, as in: "${1}(text)". To insert a literal dollar or percent sign in url, use $$ or $%, correspondingly. Request accessor interpretation Request accessor is %[name], where name denotes a part of the incom- ing request to access. Accessors are interpreted and replaced with the corresponding part of the request. Some accessors take an argu- ment, which is specified after accessor name and is separated from it by one or more whitespace characters. The following accessors are defined: const NAME [ENCODE] Configuration constant NAME (see Constant in the section GLOBAL DIRECTIVES, above). Optional ENCODE defines the en- coding in which to represent it. Its possible values are: none Don't encode it. This is the default if no ENCODE ar- gument is specified. url Encode the value using percent-encoding (RFC 3986). base64 Encode the value using BASE64 encoding (RFC 3548). url Request URL. path Request path. query Query part. param NAME The value of the query parameter NAME. header NAME The value of HTTP header NAME. host Hostname part of the Host header. If the latter does not in- clude port number, it is equivalent to %[header host]. port If the value of the Host header includes port number, %[port] evaluates to port number with the leading colon character. Otherwise, it evaluates to empty string. remoteip FWD Expands to the request originator IP address. If FWD is 0, expands to its real IP, otherwise expands to the IP deter- mined from the X-Forwarded-For (or similar) header. user If the request bears the Authorization: Basic header, expands to the user name extracted from its value. Otherwise, its expansion is empty. Modification directives The following directives modify the incoming request prior to passing it to the selected service. These are discussed in detail in section REQUEST MOD- IFICATION, below. DeleteHeader [options] "pattern" Remove certain headers from the incoming requests. All occurrences of the matching header will be removed. Options define how to match pattern: -beg Exact match at the beginning of header (prefix match). -case Case-sensitive comparison. -contain Match substring of the header. -end Exact match at the end of string (suffix match). -exact Exact string match. -icase Case-insensitive comparison. -pcre or -perl Use Perl-compatible regular expression (requires compilation- time support). -posix Use POSIX extended regular expression. -re Use regular expression matching, as set by the RegexType statement. The default is -re, that is pattern is treated as a regular expres- sion as defined by the RegexType statement. SetHeader "header: value" Adds header to the request passed to the backend server. Argument undergoes string expansion as described above. The expanded value must be a valid header line. SetURL "value" Sets the URL part of the request. Argument is subject to string ex- pansion. SetPath [-encode] "value" Sets the path part of the request. Argument is subject to string ex- pansion, and, if -encode is given, percent-encoding. SetQuery "value" Sets the query part of the request. Argument is subject to string expansion. SetQueryParam "name" [-encode] "value" Modifies the query. Sets the query parameter name to value. The value argument is subject to string expansion, and, if -encode is given, percent-encoding. Rewrite [request|response] ... [ Else ... ] End Conditionally modify request or response depending on whether it matches certain conditions. If the argument is omitted, request is assumed. Request modification is described in detail in section REQUEST MODI- FICATION DIRECTIVES. Response modification is covered by section RESPONSE MODIFICATION. Compatibility directives The following directives are retained for compatibility with previous ver- sions of pound. They will be removed in future releases. HeaderAdd "header: value" Same as SetHeader. AddHeader "header: value" Same as SetHeader. HeaderRemove "pattern" Same as DeleteHeader. HeadRemove "pattern" Same as DeleteHeader. HTTPS Listener HTTPS listener defines an address and port that pound will listen on for HTTPS requests. The listener declaration begins with the keyword Listen- HTTPS on a separate line. The keyword may be followed by a quoted string supplying listener name. This name is a unique label that identifies the listener. All configuration directives enclosed between ListenHTTPS and End are spe- cific to a single HTTPS listener. At the very least you must specify an ad- dress, optionally 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 "filename" Specify the server certificate. Filename is either a certificate file name, or the name of a directory containing certificate files. Certificate file is a file containing the certificate, possibly a certificate chain and the signature for this server, in that order. 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. wild- card 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 cer- tificate (up to 9). The default depth limit is 9, allowing for the peer certificate and additional 9 CA certificates that must be veri- fied. 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 sin- gle protocol. For example, Disable TLSv1 would disable SSLv2, SSLv3 and TLSv1, thus allowing only TLSv1_1 and TLSv1_2. Ciphers [typeopt] "ciphers" ... Defines the list of ciphers (for TLSv2 and below) or ciphersuites (for TLSv3) that will be accepted by the SSL connection. The type- opt option defines how to interpret the ciphers argument that fol- lows it: -cipherlist Sets the list of ciphers that affects only TLSv2 and prior protocols. This is the default. -ciphersuites Sets the list of TLSv3 ciphersuites. It will be combined with any TLSv1.2 and below cipher lists that may have been configured. Refer to ciphers(1), for a discussion of the ciphers argument. SSLHonorCipherOrder bool If set to true, the server will broadcast a preference to use ci- phers 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, re- gardless of the patch status of clients and servers related to "Se- cure 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 Mid- dle attack! The default value is 0. CAlist "filename" Set the list of "trusted" CA's for this server. The filename is the name of a file containing a sequence of CA certificates (PEM for- mat). The names of the defined CA certificates will be sent to the client on connection. VerifyList "filename" Set the CA (Certificate Authority). The filename is a file that con- tains 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 "filename" Set the CRL (Certificate Revocation List) file. The filename 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 re- quests on SSL connections. If the value is 2 (default), disable mul- tiple requests on SSL connections only for clients whose User-Agent header contains substring MSIE. This may be required as a work- around for a bug in certain versions of IE. Tunnel Tunnel is a special listener that defines a transparent, protocol-agnostic communication channel between two sockets. Anything sent to one end of the tunnel appears at its other end and vice-versa. Tunnels can be thought of as a software equivalent of port forwarding. Syntactically a tunnel is declared using the following construct: Tunnel [ "ID" ] Address IPADDR Port PORT Backend Address IPADDR Port PORT End End Service 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 selects a listener based on user- supplied conditions that analyze the incoming request URL and/or headers. It will always scan listener-specific services first. If none matches, it will try the global ones. Services are tried in the same order as they are defined in configuration. All configuration directives enclosed between Service and End are specific to a single service. They can be subdivided into two categories: service matching directives and backend definitions. Service Matching Directives These directives determine whether a particular request should be handled by this service. When a request arrives, each service is considered in turn (first services defined within the listener that received the request, then the ones defined in global scope). The first service that matches the request will be used. If no service matches, a 503 "Service unavailable" error is returned. Unless explicitly stated in the configuration file, all matching directives are joined by a boolean AND. A service with no matching directives always matches. ACL [-forwarded] "name" Match the source IP address against the named ACL. The ACL must have been defined earlier (see the ACL statement in GLOBAL DIREC- TIVES section above). If the originating IP doesn't match any CIDR from the list, then this service will be skipped and next one tried. The -forwarded keyword, if present, instructs the program to deduce originator IP from the X-Forwarded-For header, instead of using the actual source IP address. See the description of %a specifier in REQUEST LOGGING, for a detailed discussion of how the IP is deter- mined. ACL [-forwarded] This statement defines an unnamed ACL to match the source IP against. See above for the meaning of the optional argument. This line must be followed by one or more lines defining CIDRs, as de- scribed in the GLOBAL DIRECTIVES section above. The ACL definition is finished with a End keyword on a line by itself. Semantically it is equivalent to the named ACL reference described above. ACL [-forwarded] -file "filename" Same as above, but reads ACL definition from file filename. The name is taken relative to the IncludeDir directory, unless it starts with a slash. The ACL file should contain one CIDR per line. CIDRs need not be quoted. Empty lines and comments are allowed. The -forwarded optional keyword has the same meaning as described above. ACL [-forwarded] -filewatch "filename" Same as above, but filename will be watched for changes during the runtime. Once a change is detected, the file will be reloaded and the ACL updated. If possible, this uses OS-specific filesystem monitoring API (ino- tify(7), on GNU/Linux and kqueue(7) on *BSD systems). On systems that don't provide such API, the file will be checked for changes periodically, in intervals defined by the WatcherTTL setting. BasicAuth [option] "filename" Evaluates to true if the incoming request passes basic authorization as described in RFC 7617. filename is the name of a plain text file containing usernames and passwords, created with htpasswd(1) or sim- ilar utility. Unless it starts with a slash, it is taken relative to the IncludeDir directory. The file is read at startup and cached in memory, so that authorizations normally don't result in disk op- erations. Pound will monitor the file using the same mechanism as for ACL -filewatch (see above), and reload it when it changes. See the section entitled BASIC AUTHENTICATION, for a detailed dis- cussion. For consistency with other conditions, BasicAuth accepts an option: -file or -filewatch. The latter is the default and normally need not be specified explicitly. The former can be used to disable file change monitoring. ClientCert "filename" Evaluates to true if the client presented the certificate matching that from the file filename (PEM format). This conditional cannot be used in standalone services (i.e. ser- vices that are defined in global scope), or if the ListenHTTPS sec- tion that hosts the service has the ClientCert statement on its own. ContentCapture SIZE Enables capturing of the incoming request content. If the content length is less than or equal to SIZE, the content is captured and stored away while sending it over to the backend. The saved value is made available to Lua procedures (invoked by LuaMatch, LuaModify, and LuaBackend) via the variable http.req.body. Eval "NAME" Evaluate detached condition NAME. The condition should be defined using a Condition statement preceding this one (see above, section GLOBAL DIRECTIVES). If multiple Eval statements refer to the same NAME, the condition is evaluated once, and the result is reused by subsequent statements. Header [options] "pattern" The request must contain at least one header matching the given pat- tern. By default, pattern is treated as a case-insensitive extended regular expression. This can be changed by options, described be- low. Header "Name" [options] "pattern" Alternative form of the Header statement. In this form, pattern is matched against the value of each header having the supplied Name. For example: Header "Content-Type" -beg "text/" Host [options] "hostname" The request must contain a Host header whose value matches hostname. In the absence of options, case-insensitive exact match is assumed, i.e. this construct is equivalent to Header "Host" -exact "hostname" See below for the discussion of options and their effect on match- ing. This statement is provided to facilitate handling of virtual hosts. See the EXAMPLES section. Method [options] "pattern" Match the request method. Path [options] "pattern" Match the path part of the incoming request. Query [options] "pattern" Match the query part of the incoming request. The argument must be properly percent-encoded, if it contains whitespace or other non- printable characters. QueryParam "name" [options] "pattern" Match the value of the query parameter name. StringMatch "string" [options] "pattern" Expand string as described in String expansion (see below) and match the resulting value against pattern. TBF "key" rate burst Defines a token bucket filter for that service. See below, the sec- tion entitled REQUEST RATE, for a discussion. Arguments are: key A string identifying the bucket to use. It is subject to string expansion (see the subsection String expansion, above). rate Allowed request rate, requests per second. Fractional rates are allowed as well: 1/2 (one request each two seconds), 3/500ms (three requests each 500 milliseconds), etc. burst Burst size, i.e. maximum number of tokens the bucket can con- tain. The TBF conditional evaluates to true if the request conforms to the defined rate policy, and false otherwise. URL [options] "pattern" Match the URL of the incoming request. By default, pattern is treated as case-sensitive extended regular expression. This can be changed by options, described below. The options argument in the above directives can be used to select the com- parison method. It consists of zero or more option flags from the follow- ing list: -beg Exact match at the beginning of string (prefix match). -case Case-sensitive comparison. -contain Match substring. -end Exact match at the end of string (suffix match). -exact Exact string match. -file Treat pattern as the name of a file to read patterns from. If the name is relative, it will be looked up in the include directory (see the discussion of the IncludeDir directory above). Patterns are read from the file line by line. Leading and trailing whitespace is removed. Empty lines and comments (lines starting with #) are ig- nored. -filewatch Same as -file, except that the file will be monitored for changes and reloaded as soon as these occur. If possible, this uses OS-specific API (inotify(7), on GNU/Linux and kqueue(7) on *BSD systems). On systems that don't provide such an API the file will be checked for changes periodically. The interval between two successive checks is defined by the WatcherTTL setting. -icase Case-insensitive comparison. -pcre or -perl Use Perl-compatible regular expression (requires compile-time sup- port). This overrides global RegexType settings. -posix Use POSIX extended regular expression. This overrides global Regex- Type settings. -re Use regular expression matching, as set by the RegexType statement. -tag "T" Tag the statement with string T. This string can be used in subse- quent modification statements to refer to a subexpression of this statement's pattern, using the following syntax: $I(T), where I is the ordinal number of the subexpression. For example, the following will match any request whose Host header begins with "www." (case-insensitive): Host -icase -beg "www." Additionally, Path and QueryParam directives accept the option -decode, which causes the obtained value to undergo percent-decoding prior to com- parison. Compatibility directives The following directives are provided for backward compatibility with older versions of pound. They will be removed in future versions. HeadRequire "pattern" Same as Header. HeadDeny "pattern" A shortcut for Not header "pattern" In other words: the request may not contain any header matching the given pattern. See the Negation section, below. Negation Prefixing any of the directives discussed above with not will revert the sense of comparison. For example, Not url "^/static/" will match any request, whose URL does not begin with "/static/". Negating compound statements is allowed as well, e.g.: Not ACL "192.0.2.0/26" "203.0.113.0/24" End Match statement A Match statement allows you to group matching directives using arbitrary boolean operations. The syntax is: Match OP directives... End where OP is AND or OR (case-insensitive), and directives stand for any num- ber of matching directives discussed above (including the Match directive itself). Prefixing Match directive with a word not reverts its result. Match directives can be nested to any depth. Technically, an implicit Match AND block is created around unenclosed matching directives on the top level of a Service block. Modification directives The following directives modify the incoming request prior to passing it to the selected backend. These are discussed in detail in the section REQUEST MODIFICATION, below. DeleteHeader [options] "pattern" Remove matching headers from the incoming requests. For the list of available options and their effect on matching, see the description of DeleteHeader statement in section HTTP Listener, subsection Modi- fication directives, above. SetHeader "header: value" Add the defined header to the request passed to the backend server. SetURL "value" Sets the URL part of the request. SetPath [-encode] "value" Sets the path part. If given the -encode option, after usual expan- sions, value will be percent-encoded. SetQuery "value" Sets the query part. SetQueryParam "name" [-encode] "value" Modifies the query. Sets the query parameter name to value. If given the -encode option, after usual expansions, value will be per- cent-encoded. Rewrite [request|response] ... [ Else ... ] End Conditionally modify request or response depending on whether it matches certain conditions. If the argument is omitted, request is assumed. Request modification is described in detail in section REQUEST MODI- FICATION DIRECTIVES . Response modification is covered by section RESPONSE MODIFICATION. RewriteErrors bool If bool is true, this enables backend error response rewriting for this service, i.e. replacing the content of error responses returned by a regular backend with a custom error text defined by the Error- File statement in the listener. See ERROR RESPONSE REWRITING, for a detailed discussion of this feature. This statement overrides settings of the enclosing listener, so that RewriteErrors off appearing in a Service will disable that feature for that particular service. Backend definitions Balancer random | iwrr Defines the load-balancing strategy to use. Possible arguments are: random, to use weighted random balancing algorithm. an iwrr, meaning interleaved weighted round robin balancing. See REQUEST BALANCING, above, for a detailed discussion of these balancing strategies. This directive overrides the Balancer directive in global scope. Backend Directives enclosed between Backend and the following End directives define a single backend server (see below for details). You may de- fine multiple backends per service, in which case pound will dis- tribute the load between them, according to the selected balancer strategy. Control Enables a special control backend -- a management interface that re- turns information about the running pound server, makes it possible to change state of configured listeners, services and backends, and provides other management facilities. The management interface is discussed in detail in section Control socket, above. The Control backend provides remote access to this interface. Be careful to properly protect the control interface by use of HTTPS, ACLs and/or basic authorization, e.g.: ListenHTTPS Address 192.0.2.1 Port 443 Cert "/etc/ssl/priv/example.pem" Service Not BasicAuth "pound/htpasswd" Rewrite response SetHeader "WWW-Authenticate: Basic realm=\"Restricted access\"" End Error 401 End Service ACL "secure" Control End End Emergency Directives enclosed between Emergency and the following End direc- tives define an emergency backend server (see below for details). You may define any number of emergency servers. A backend will be selected from emergency backends if all regular backends are down. Error STATUS [FILE] Special case of backend that returns HTTP error page. The STATUS argument supplies HTTP status code. Optional FILE argument is the name of a disk file with the error page content. If supplied, the file is handled as in ErrorFile directive, which see. If not present, the content to return in the response is determined as usual: first the ErrorFile STATUS statement for the enclosing lis- tener is consulted. If it is not present, the default error page is used. The Error directive is useful in a catch-all service, which outputs an error page if no service matching the incoming request was found. See the EXAMPLES section for details. Metrics Special backend type that implements Openmetrics protocol output. See the section Metrics below for a detailed discussion. 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. It is allowed to define multiple redirectors in a service, as well as mixing them with regular backends, but there is little if any justification for such usage, so it is deprecated. Optional code can be one of: 301, 302 (the default), 303, 307, or 308. The redirection destination is determined by the actual url you specify. It is expanded as described in String expansion above. For compatibility with previous pound versions, if no $N references are found in url, the following logic is used: 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: the following swaps the first two path components of the original URL: Service Host -re "(.+)" URL "^/([^/]+)/([^/]+)(/.*)?" Redirect "http://$0(1)/$2/$1$3" End Notice the use of Host to supply hostname part for the redirect. Using request accessors, the above example can be rewritten as: Service URL "^/([^/]+)/([^/]+)(/.*)?" Redirect "http://%[header host]/$2/$1$3" End Compatibility syntax: 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. SendFile DIR Static file backend. It responds with the content of a file from directory DIR. The path part of the request supplies the path to the requested file, relative to the directory DIR. The path may be modified, if need be, using request rewriting techniques (in partic- ular, SetPath) discussed in REQUEST MODIFICATION DIRECTIVES. Con- tent type of the response is assumed to be text/plain. This can be changed using SetHeader statement (see RESPONSE MODIFICATION). Success Special backend that responds with code 200. It can be used for de- bugging or for side effects, such as setting headers using the Set- Header statement. Session control Session Directives enclosed between Session and the following End directives define a session-tracking mechanism for the current service. See be- low for details. Other directives Constant "NAME" [OPTIONS] ["VALUE"] Defines a configuration constant for use in string expansions and Lua code. See Constant in section GLOBAL DIRECTIVES, for a detailed discussion of its arguments and their meaning. Per-service constants augment per-listener and global ones. If the name of a per-service constant coincides with the name of a per-lis- tener or a globally defined one, the former overrides the latter for this service. IgnoreCase bool Override the global IgnoreCase setting. This statement is deprecated and will be removed in future versions. Please, use the -icase option to the URL directive instead. See the discussion of options in Service Matching Directives section above. Disabled bool Start pound with this service disabled (true) or enabled (false). If started as disabled, the service can be later enabled with pound- ctl(8). ForwardedHeader name Defines the name of the HTTP header that carries the list of proxies the request has passed through. It is used to report the originator IP address when logging. See the description of %a specifier in RE- QUEST LOGGING. This statement overrides the ForwardedHeader direc- tive from the listener scope. The default is X-Forwarded-For. TrustedIP Defines a list of trusted proxy IP addresses, which is used to de- termine the originator IP. See the description of %a specifier in REQUEST LOGGING, for a detailed discussion. This statement overrides the TrustedIP directive from the listener scope. LogSuppress class Suppresses HTTP logging for requests that resulted in status codes from the specified class. Valid status classes are: info or 1 1xx response codes. success or 2 2xx response codes. redirect or 3 3xx response codes. clterr or 4 4xx response codes. srverr or 5 5xx response codes. all All response codes. Multiple arguments are allowed. This statement is designed for services that receive a constant stream of similar HTTP requests from a controlled set of IP ad- dresses, such as e.g. Openmetric services. See the Metric section below for an example. ACME This statement creates a service specially crafted for answering ACME HTTP-01 challenge requests (see https://letsencrypt.org/docs/challenge- types/#http-01-challenge). It takes a single argument specifying a direc- tory where ACME challenges are stored. The argument is subject to string expansion (see the subsection String expansion, above). It is supposed that another program is started periodically, which checks for certificates approaching their expiration, issues renewal requests and stores the obtained ACME challenges in that directory. Backend A backend is a definition of a single backend server pound will use to re- ply to incoming requests. Backends are defined via a Backend statement. There are two forms of this statement: service-specific and global (or named) backend. These will be discussed later in this section. All con- figuration directives enclosed between Backend and End are specific to a single backend. The following directives are available: Address address The address that pound will connect to. This can be a numeric IP ad- dress, 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. ServerName "name" Specify the name to use for server name identification (SNI). This directive also rewrites the Host: header for this particular back- end. This means you don't have to use SetHeader in addition to it. This directive may appear only after the HTTPS directive. Cert "filename" Specify the certificate that pound will use as a client. The file- name 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 sin- gle 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 [typeopt] "ciphers" ... Defines the list of ciphers (for TLSv2 and below) or ciphersuites (for TLSv3) to negotiate with the backend. The typeopt option de- fines how to interpret the ciphers argument that follows it: -cipherlist Sets the list of ciphers that affects only TLSv2 and prior protocols. This is the default. -ciphersuites Sets the list of TLSv3 ciphersuites. It will be combined with any TLSv1.2 and below cipher lists that may have been configured. Refer to ciphers(1), for a discussion of the ciphers argument. This directive may appear only after the HTTPS directive. Priority n The priority of this backend. Higher priority backends will be used more often than lower priority ones, so you should define higher priorities for more capable servers. The scheduling algorithm de- pends on the load balancing strategy in use (see the section REQUEST BALANCING, above). Allowed range for priorities is 0 to 65535, in- clusive. Default value is 5. TimeOut n Override the global TimeOut value. ConnTO n Override the global ConnTO value. WSTimeOut n Override the global WSTimeOut value. Disabled bool Start pound with this backend disabled (1) or enabled (0). If started as disabled, the backend can be later enabled with pound- ctl(8). Dynamic backends Dynamic backends are created and updated on the fly based on the informa- tion from DNS. A backend is declared as dynamic by the Resolve statement. Its value defines what type of DNS record is used to generate dynamic back- end instances: first Resolve the symbolic host name from the Address directive and use first IP from the DNS response as the address of the created dynamic backend. Thus, at most one dynamic backend will be produced. all Resolve the symbolic host name from the Address directive and create one backend for each address from the DNS response. This enables load balancing between created backends. Each backend will be as- signed the same priority. srv Obtain SRV records for the host name and use them to generate back- ends. Each record produces new dynamic backend of the Resolve all type, which produces regular backends as described above. The weight field of the SRV record is mapped to the priority field of each generated backend. The SRV priority field identifies the bal- ancer group where the backend will be hosted. The following directives further configure dynamic backends: Family any | inet | inet6 Selects the family of the addresses to look for: any Use all address families available. This is the default. inet Use only IPv4 addresses (A DNS RRs). inet6 Use only IPv6 addresses (AAAA DNS RRs). IgnoreSRVWeight bool When using SRV records, ignore their weight fields and assign prior- ities for the generated backends from the priority of the producing backend. This directive is valid when used together with Resolve srv. OverrideTTL N Query DNS each N seconds for possible changes in configuration of the existing dynamic backends. If this statement is not used, the TTL value returned with the DNS response will be used instead. RetryInterval N Retry failed DNS queries each N seconds. Default is 600. Global and per-service backends A Backend definition can appear as a part of the service, i.e. in a Service section. or globally. In the latter case, the Backend keyword must be followed by a symbolic name assigned to this backend, e.g.: Backend "name" ... End This name must uniquely identify the backend among other globally defined backends. A global backend is attached to a service using the UseBackend statement. It takes the symbolic name of the backend as its argument. The statement UseBackend "name" has essentially the same effect as if full backend definition appeared in- stead of it in this place. A substantial difference between the use of service-specific and global backends is that a single global backend can be used in multiple services. In a way, UseBackend statement expands to a backend definition within the service. Furthermore, you can also adjust the Priority and Disabled parameters of the global backend definition for use in a particular service. To do so, use the following syntax: Backend "name" Priority 3 Disabled no End In this form, the Backend statement acts as UseBackend. Two directives can appear within such Backend statement: Priority, and Disabled. They over- ride the settings defined in the global backend "name". Notice, that in spite of their similarity, the two named forms of the Back- end statement serve different purposes: when used in global scope, a named Backend defines a backend for further use in various services, and when used within a service, it creates a copy of the backend defined elsewhere and attaches it to this service. The actual global definition may appear before as well as after service or services it is used in. Resolver The Resolver section controls DNS lookups for dynamic backend generation (see above). It can contain the following directives: CNAMEChain N Maximum allowed length of a CNAME chain. CNAME chains are formed by DNS CNAME records pointing to another CNAME. Although prohibited by the RFC, such usage does occur sometimes. By default, pound does not accept CNAME chains. If you work with nameservers that return them, set this statement to a small integer value, defining maximum number of CNAMEs in the chain that can be accepted. The value of 2 or 3 should suffice in most cases. ConfigFile "FILE" Read the resolver configuration from FILE, instead of the default /etc/resolv.conf. ConfigText ... End Alternative way to supply resolver configuration. The material within this section is read verbatim and used as the content of the resolver configuration file. If both ConfigFile and ConfigText are used, the last used statement wins. debug bool Whether to enable DNS debugging info. RetryInterval N Interval in seconds, after which to retry failed DNS queries or queries that returned no RRs. This value is used unless the backend defines its own retry interval value. Emergency Emergency servers will be used once all existing backends are "dead". All configuration directives enclosed between Emergency and End are specific to a single service. For the list of directives allowed for use in Emergency sections, refer to the description of Backend. Session Defines how a service deals with possible HTTP sessions. All configuration directives enclosed between Session and End are specific to a single ser- vice. 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 dis- carded. This is a mandatory parameter. ID "name" The session identifier. This directive is permitted only for ses- sions 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. Metrics The following service definition enables Openmetric telemetry output on endpoint /metrics: Service URL "/metrics" Metrics End To control access to the telemetry endpoint, use the ACL statement. The LogSuppress directive can be used in openmetric services to suppress logging of served HTTP requests. For example: Service URL "/metrics" Metrics ACL "secure" LogSuppress success End The metrics output is sufficiently self-documented by # HELP descriptor lines. HIGH-AVAILABILITY Pound attempts to keep track of active backend servers, and will temporar- ily disable servers that do not respond (though not necessarily dead: an overloaded server that pound cannot establish a connection to will be con- sidered 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 consis- tent 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. REQUEST MODIFICATION DIRECTIVES Several statements are provided to modify incoming requests prior to pass- ing them to the backend. These statements can be present both in Listen- HTTP (ListenHTTPS) and in Service sections. Basic request modification directives are: SetURL "value" Set the URL of the incoming request to value. SetPath [-encode] "value" Set the path part of the URL to the given string. The -encode op- tion enables percent-encoding of value. SetQuery "value" Set the query part of the URL to the given string. value must be a valid query with the special characters properly encoded using per- cent encoding. SetQueryParam "name" [-encode] "value" Set the query parameter name to the value. If -encode is given, af- ter usual expansions value will undergo percent-encoding. SetHeader "name: value" Sets the HTTP header. If the header name already exists, it will be overwritten. Otherwise, new header will be added to the end of the header list. DeleteHeader [options] "pattern" Remove from the request all headers matching pattern. By default, pattern is treated as extended POSIX regular expression. The op- tions argument can be used to change this behavior. It consists of zero or more option flags from the following list: -beg Exact match at the beginning of string (prefix match). -case Case-sensitive comparison. -contain Match substring. -end Exact match at the end of string (suffix match). -exact Use exact string matching. -icase Case-insensitive comparison. -pcre or -perl Use Perl-compatible regular expression (requires compilation- time support). This overrides global RegexType settings. -posix Use POSIX extended regular expression. This overrides global RegexType settings. -re Use regular expression matching, as set by the RegexType statement. The value argument in the above directives is subject to string expansion. Refer to subsection String expansions, for details. The Rewrite block statement is used to associate one or more of the above directives with request matching directives (discussed in the subsection Service Matching Directives above), so that request modification takes place only when the request matches certain conditions. Syntactically, a Rewrite block is: Rewrite [request] . . . Else . . . End where dots stand for any number of request matching and request modifica- tion statements. The Else part is optional; any number of Else blocks can be supplied, thus providing for conditional branching. The following con- cocted example illustrates it: Rewrite Path "\.(jpg|gif)$" SetPath "/images%[path]" Else Match AND Host "example.org" Path "\.[^.]+$" End SetPath "/static%[path]" Else Path "\.[^.]+$" SetPath "/assets%[path]" End Here, if a path ends with a filename with suffix ".jpg" or ".gif", "/im- ages" is prepended to it (notice that path always starts with a slash, hence it should not be used explicitly). If the path ends with any other extension, the action depends on the host being addressed. The path is prefixed with "/static" if the host is "example.org", and with "/assets" otherwise. To illustrate the effects of string expansion, here's the the above example rewritten using backreference expansion instead of request accessors: Rewrite Path ".*\.(jpg|gif)$" SetPath "/images$0" Else Match AND Host "example.org" Path ".*\.[^.]+$" End SetPath "/static$0" Else Path ".*\.[^.]+$" SetPath "/assets$0" End Request modification directives from ListenHTTP (or ListenHTTPS) section are applied first, followed by directives from the Service section. Direc- tives appearing within a single section are applied in the same order as they appear in the configuration file. BUILT-IN HEADERS In addition to the SetHeader and DeleteHeader directives discussed above, the HeaderOption directive controls insertion of the built-in headers: HeaderOption opt... There are two kinds of such headers: forwarded headers that convey informa- tion about original destination of the request, and ssl headers (for HTTPS connections), that hold information about server and client SSL certifi- cates. These are discussed in detail below. By default, both kinds of built-in additional headers are enabled. This default can be changed by using the HeaderOption directive. Placed in global scope, this directive sets global options. Used within a ListenHTTP or ListenHTTPS block, it affects only settings for that listener. The opt values passed to the directive are: all Enable both kinds of additional headers. none Disable both kinds of additional headers. forwarded Enable forwarded headers. no-forwarded Disable forwarded headers. ssl Enable ssl headers. no-ssl Disable ssl headers. The built-in headers are added before request modification directives are applied. Thus, you can use DeleteHeader and SetHeader to trim down headers added by HeaderOptions. Forwarded Headers The headers in the forwarded header group are: X-Forwarded-For IP address of the HTTP client that sent the request, X-Forwarded-Proto Protocol (http or https) that the client used to connect to pound. X-Forwarded-Port Destination port that the client used to connect to pound. HTTPS Headers If a client browser connects to pound via HTTPS and the ssl header group is enabled, then the following header is added: X-SSL-Cipher Contains SSL version followed by a slash and active cipher algo- rithm. Additionally, if the client presented its certificate, the following head- ers are added that describe the client certificate: 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-Certificate The full client certificate (PEM-format multi-line) RESPONSE MODIFICATION Headers in the response obtained from a regular backend or generated with a Error backend can be modified before sending them back to the requesting server. A special form of the Rewrite directive is provided for this pur- pose: Rewrite response . . . Else . . . End where dots stand for any number of response matching and modification statements. The Else part is optional; any number of Else blocks can be supplied, thus providing for conditional branching. This directive can be used in ListenHTTP, ListenHTTPS, and Service defini- tions. Response modification directives from the Service section are applied first, followed by directives from the ListenHTTP (or ListenHTTPS) section. Directives appearing within a single section are applied in the same order as they appear in the configuration file. Response matching statements are: Header [options] "pattern" Matches if the response contains at least one header matching the given pattern. Header "name" [options] "pattern" Alternative form of the Header statement, that matches pattern against value part of each header name. StringMatch "string" [options] "pattern" Expand string as described in String expansion (see below) and match the resulting value against pattern. By default, pattern is treated as case-insensitive extended regular expression. This can be changed by options, as described in section Service Matching Directives, above. Match The Match statement is as described in section Match statement, ex- cept that only directives described above are allowed within it. Not Placed before any of the above directives, reverts its result. Following response modification statements are defined: DeleteHeader "pattern" Remove matching headers from the response. SetHeader "header: value" Add header to the response. Argument undergoes string expansion as described above. The expanded value must be a valid header line. ERROR RESPONSE REWRITING When a regular backend responds with an error, the content of that response can be replaced with an arbitrary custom page, if its status code is one of the http status codes supported by pound, i.e. one of 400, 401, 404, 405, 413, 414, 500, 501, 503, and a custom error page for that status is pro- vided using the ErrorFile directive (or one of the legacy ErrNNN direc- tives). To enable such error response rewriting use the following statement: RewriteErrors on in the Service block, where the responding backend is defined, or in the enclosing ListenHTTP (ListenHTTPS) block. MULTI-VALUE HEADERS HTTP protocol allows for certain headers to appear in the message multiple times. Namely, multiple headers with the same header name are permitted if that header field is defined as a comma-separated list. The standard spec- ifies that such fields can be combined in a single header: value pair, by appending each subsequent field value to the previous one, each separated by a comma. Pound is able to perform such combining both on incoming requests and on responses. To enable this feature, declare names of headers that can be combined using the CombineHeaders section statement. This statement must be followed by header names, each on a separate line, and terminated with an End statement. E.g.: CombineHeaders "Accept" "Allow" "Forwarded" End You can also store header names in a file, and include that file after Com- bineHeaders, e.g.: CombineHeaders Include "multivalue.txt" End BASIC AUTHENTICATION To limit access to a service or services to certain authenticated users, use a combination of BasicAuth matching and response modification. The BasicAuth matching directive evaluates to true, if the incoming request contains Authorization header with scheme "Basic", such that user name and password obtained from it match a line in the given disk file. The file must be a plain-text file created with htpasswd(1) or similar utility, i.e. each non-empty line of it must contain username and password hash separated by a colon. Password hash can be one of: 1. Password in plain text. 2. Hash created by the system crypt(3) function. 3. Password hashed using SHA1 algorithm and encoded in base64. This hash must be prefixed by {SHA}. 4. Apache-style apr1 hash. Combined with the response rewriting described above, this can be used to implement basic HTTP authentication in Pound as shown in the following ex- ample: Service "auth" Not BasicAuth "/etc/pound/htpass" Rewrite response SetHeader "WWW-Authenticate: Basic realm=\"Restricted access\"" End Error 401 End Placing this service definition before others ensures that services defined below it will be tried only if the incoming request passes basic authenti- cation. REQUEST RATE Request rate can be controlled using the TBF service selection statement. The statement implements a token bucket filter, and takes three arguments: a string identifying the bucket, request flow rate in requests per second, and token burst size, i.e. maximum number of requests per bucket. The first argument is expanded as discussed in String expansion. The statement evaluates to true, if the request conforms to the rate policy, and to false otherwise. It is customary to use its negation together with the Error special backend in order to control request flow, e.g.: Service "rate-limit" Path -re "^/([^/]+).*" Not TBF "$1" 3 10 Error 429 End REQUEST LOGGING Logging of HTTP requests and responses is controlled by LogLevel directive. This directive can appear either in global scope, in which case it affects all listeners defined below it, or in listener scope, in which case it af- fects only this listener, overriding the global setting. Argument to the LogLevel directive can be either an integer number in range 0 through 5 (inclusive), or a quoted string. Numeric value identifies one of the built-in log formats, described later in this section. String value refers either to a built-in format name, or to a user-defined format name. In the latter case, the named format must be defined earlier using the Log- Format statement. Format specification The syntax of the LogFormat statement is: LogFormat "name" "format_string" First argument, name, is a unique identifier for this format, which will be used later to refer to it. Format_string is a character string composed of ordinary characters (not %), which are copied unchanged to the resulting log message, and conversion specifications, each of which are replaced by a corresponding piece of information about the request or reply. Conversion specifications are single characters prefixed with a percent sign. Depending on the specification, an optional conversion argument in curly brackets may appear between % and the conversion character. The following conversion characters are defined: %% Replaced with the percent sign. %a Originator IP address of the request. If the request contains the X-Forwarded-For header and TrustedIP ACL is defined, the value of the header is consulted to obtain the IP address. The value must be a comma-delimited list of intermediate user agent IP addresses. To determine the actual user agent IP, the list is traversed from right to left, until an IP is found that is not listed in TrustedIP ACL. If X-Forwarded-For header is not present, or TrustedIP is not de- fined, or the above algorithm does not return an IP address, %a ex- pands to the actual remote IP address the request came from (same as %h). The TrustedIP ACL can be defined in global scope, or in ListenHTTP (ListenHTTPS) section, or in Service section. Most-specific ACL overrides least-specific ones, that is TrustedIP defined in Service will be used, if it is defined. If not, the one defined in listener will be used, etc. The syntax of the TrustedIP statement is the same as that of ACL, i.e. TrustedIP "name" refers to the named ACL name (which must be defined earlier), TrustedIP -file "name" or TrustedIP -filewatch "name" read the list of IPs (or CIDRs) from the file name, and TrustedIP "CIDR0" "CIDR1" ... End defines the list of trusted IPs in place. ForwardedHeader statement defines the name of the header to use in- stead of X-Forwarded-For. As TrustedIP, this statement can appear in global, listener, or in service scope. %A Local IP address of the listener. %B Size of response in bytes, excluding headers. %b Same as %B, but in CLF format, i.e. a dash is used when response size is zero. %D The time taken to serve the request, in microseconds. %h Client IP address of the request. %H The request protocol. %{VARNAME}i The contents of VARNAME: header line in the request. Changes made by header modification directives affect this. %{VARNAME}I Same as %i, except that if no such header is present in the request, a dash is substituted. %l Single dash. This specifier is reserved for future use. %{OBJNAME}L Location of the Pound object that is involved in handling the re- quest. Valid values for OBJNAME are: listener, service, and back- end. The location gives position in the configuration file where the object was defined, and is formatted as NAME:LN1.COL1-LN2.COL2 where NAME is the configuration file name, LN1 and COL1 are number of line and column where the object definition begins, and LN2 and COL2 are number of line and column where it ends. Line and column numbers start with 1. %m The request method. %{OBJNAME}N Name of the Pound object that is involved in handling the request. Valid values for OBJNAME are: listener, service, and backend. %p Port number of the listener serving the request. %P Thread ID of the serving thread. %q The query string prepended with a ? if it exists, otherwise an empty string. %r First line of request. %s Response status code. %>s First line of the response. %t Time the request was received, in the format [18/Sep/2011:19:18:28 -0400]. The last number indicates the timezone offset from UTC. %{format}t Time the request was received, in the format specified by the argu- ment (strftime(3)). If the format starts with begin: (default) the time is taken at the beginning of the request processing. If it starts with end: it is the time after the response from the backend has been sent back to the requester. In addition to strftime(3) formats, the following specifications are recognized: sec Number of seconds since the Epoch. msec Number of milliseconds since the Epoch. usec Number of microseconds since the Epoch. msec_frac Millisecond fraction of the time. usec_frac Microsecond fraction of the time. %T The time taken to process the request, in seconds. %{UNIT}T The time taken to process the request, in a time unit given by UNIT. Valid units are ms for milliseconds, us for microseconds, s for sec- onds, and f for seconds with fractional part. Using s gives the same result as %T without any format; using us gives the same result as %D. %u Remote user if the request was authenticated. %U The URL path requested. This is affected by request modification directives. %v Hostname used in the request (from the Host header, without port number). Built-in formats There are five built-in formats. These can be identified either by their numeric index in the format table, or by symbolic name. The table below describes each built-in format using the format specification string: 0, null No request logging at all. 1, regular "%a %r - %>s" 2, extended "%a %r - %>s (%{Host}i/%{service}N -> %{backend}N) %{f}T sec" 3, vhost_combined (Split in two lines for readability) "%v:%p %a %l %u %t \"%r\" %s %b \"%{Referer}i\" \ \"%{User-Agent}i\"" 4, combined "%a %l %u %t \"%r\" %s %b \"%{Referer}i\" \"%{User-Agent}i\"" 5, detailed (Split in two lines for readability) "%v:%p %a %l %u %t \"%r\" %s %b \"%{Referer}i\" \ \"%{User-Agent}\" (%{service}N -> %{backend}N) %{f}T sec" SECURITY Pound makes very limited use of the hard disk. The configuration file, server certificate files and error messages (ErrorFile) are opened read- only on startup, read, and closed immediately afterwards. Read access dur- ing runtime is required only for certain special features, such as Basi- cAuth, SendFile, and request matching directives with the -filewatch op- tion. The only disk write pound ever does, is saving its PID in the pid file at startup. Giving such limitied I/O, using a RootJail directive can provide only lim- ited security bonus. Pound tries to sanitize all HTTP/HTTPS requests: the request itself, the headers and the contents are checked for conformance to the RFCs and only valid requests are passed to the backend servers. This is not absolutely fool-proof - as the recent Apache problem with chunked transfers demon- strated. However, given the current standards, this is the best that can be done - HTTP is an inherently weak protocol. DEPRECATED FEATURES Configuration statements The following configuration statements are retained for backward compati- bility with earlier pound versions. They will disappear from future re- leases: HeadRequire Use Header instead. See Service Matching Directives, for details. HeadDeny Use Not Header. For details, see the Negation subsection in Service Matching Directives. AddHeader and HeaderAdd Use SetHeader instead. See the section REQUEST MODIFICATION DIREC- TIVES, for details. HeaderRemove and HeadRemove Use DeleteHeader instead. See the section REQUEST MODIFICATION DI- RECTIVES, for details. IgnoreCase Use the -icase option to the URL directive instead. See the discus- sion of options in the Service Matching Directives section. ErrNNN (where NNN is one of: 400, 401, 403, 404, 413, 414, 500, 501, 503) Use the ErrorFile directive, described in the section HTTP Listener, above. Redirect request hack The use of the redirect request hack in the Redirect statement is depre- cated as well. Instead of relying on the trailing slash to append the original URL to the redirect location, use URL backreferences. For exam- ple, instead of Redirect "http://example.org/" use: URL ".*" Redirect "http://example.org$0" Multiple redirect backends Use of multiple Redirect backends in a single service is deprecated, as well as using Redirect backends together with regular ones. If you know of any valid usage for such configuration, please drop a note to the au- thors (see REPORTING BUGS, below). ADDITIONAL NOTES Pound uses the system log for messages (default facility LOG_DAEMON). If using rsyslog, you can use the following configuration fragment to redirect pound messages to a separate file: :programname, startswith, "pound" { /var/log/pound.log stop } The format requested by LogLevel 3 is understood by most log analyzers. 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. Pound tries to handle this by adding various X-Forwarded-* and X-SSL-* headers. See HEADER MODIFICATION above, for a detailed discussion. 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 re- quests and/or responses. That means it needs a functioning resolver of some kind (be it /etc/hosts, DNS or something else). However, the use of DNS can be disabled using the -W no-dns command line option. EXAMPLES 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 re- quests 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 -beg "/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. Two back- ends, 192.168.0.20 and 192.168.0.21, will handle the rest of requests (cookie-based sessions). Among these, the latter (192.168.0.21) is less powerful than the former, so care should be taken that it gets less re- quests. The logging will be done by backend servers. All plain HTTP re- quests are to be redirected to HTTPS and all requests directed to my- server.com - to www.myserver.com. The configuration file may look like this: User "nobody" Group "nogroup" RootJail "/var/pound/jail" Alive 60 LogLevel 0 # HTTP: redirect all requests to the corresponding HTTPS server. ListenHTTP Address 192.0.2.1 Port 80 Client 10 Service Host -re ".+" URL ".*" Redirect 301 "https://$0(1)$0" End 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=.*" Host "www.myserver.com" Backend Address 192.168.0.11 Port 80 End Session Type URL ID "sessid" TTL 120 End End # Virtual host myserver.com - redirects to www. Service Host "myserver.com" URL ".*" Redirect 301 "https://www.myserver.com$0" End # Virtual host server1.com and www.server1.com Service Host -re "^(www.)?server1.com$" 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 # Return custom error page if no matching service was found. Service Error 404 "/var/lib/pound/notfound.html" End FILES /var/run/pound.pid This is where pound will attempt to record its process id. The ex- act location is determined at compile time by the value of the --lo- calstatedir configuration switch. It can be changed at runtime us- ing the -p command line option. Use pound -V to inspect the actual default. /etc/pound.cfg 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 Certificate file(s) for HTTPS. The location must be defined in the configuration file - this is only a suggestion. The file must con- tain 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 de- tails. This file should be well protected, lest someone gets your server private key. AUTHOR Written by Robert Segall (Apsis GmbH), and Sergey Poznyakoff. REPORTING BUGS Report bugs to <gray@gnu.org>. You may also use github issue tracker at https://github.com/graygnuorg/pound/issues. COPYRIGHT Copyright (C) 2002-2010 Apsis GmbH. Copyright (C) 2018-2026 Sergey Poznyakoff License GPLv3+: GNU GPL version 3 or later <http://gnu.org/li- censes/gpl.html> This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. pound May 7, 2026 POUND(8)
NAME | SYNOPSIS | DESCRIPTION | GENERAL PRINCIPLES | REQUEST BALANCING | WORKER MODEL | OPTIONS | CONFIGURATION FILE | GLOBAL DIRECTIVES | HTTP Listener | HTTPS Listener | Tunnel | Service | ACME | Backend | Resolver | Emergency | Session | Metrics | HIGH-AVAILABILITY | REQUEST MODIFICATION DIRECTIVES | BUILT-IN HEADERS | RESPONSE MODIFICATION | ERROR RESPONSE REWRITING | MULTI-VALUE HEADERS | BASIC AUTHENTICATION | REQUEST RATE | REQUEST LOGGING | SECURITY | DEPRECATED FEATURES | ADDITIONAL NOTES | EXAMPLES | FILES | AUTHOR | REPORTING BUGS | COPYRIGHT
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=pound&sektion=8&manpath=FreeBSD+Ports+15.1.quarterly>