Pound
*****
This edition of the 'Pound Manual', last updated 15 July 2025, documents
'pound' version 4.16.90.
Copyright (C) 2024-2025 Sergey Poznyakoff
Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation License,
Version 1.3 or any later version published by the Free Software
Foundation; with no Invariant Sections, no Front-Cover Texts, and
no Back-Cover Texts. A copy of the license is included in the
section entitled "GNU Free Documentation License."
Pound
1 Overview
2 Introduction
3 Usage
4 Simple Proxy
4.1 Service Selection
4.1.1 Regular Expressions
4.1.2 ACL
4.2 Request modifications
4.3 Conditional branches
4.4 Modifying responses
4.5 Authentication
4.6 Redirects
4.7 Error responses
5 HTTPS
5.1 ACME
5.2 Redirect HTTP to HTTPS
5.3 HTTPS backends
6 Request balancing
6.1 Sessions
6.2 Balancer groups
6.3 Dynamic backends
7 Worker model
8 Logging
9 Configuration
9.1 Lexical structure
9.2 Syntax
9.3 String Expansions
9.3.1 Backreference expansion
9.3.2 Request Accessor Interpretation
9.4 Global directives
9.4.1 Runtime directives
9.4.2 Worker Settings
9.4.3 Proxy Tuning Directives
9.4.4 SSL Settings
9.4.5 Regular Expression Settings
9.4.6 ACL Definition
9.5 File inclusion
9.6 Logging configuration
9.7 Management Interface
9.7.1 Remote Access to Management Interface
9.8 Timeouts
9.9 ListenHTTP
9.9.1 Listener address
9.9.2 Listener-specific limits
9.9.3 Error definitions
9.9.4 Listener logging
9.9.5 Request Modification
9.9.5.1 The 'rewrite' statement
9.9.6 Response Modification
9.9.6.1 The 'Rewrite response' statement.
9.9.7 Rewriting error responses
9.9.8 Service definitions
9.10 ListenHTTPS
9.11 Service
9.11.1 Service Selection Statements
9.11.2 Request and Response Modification
9.11.3 Service Logging
9.11.4 Backends
9.11.4.1 Backend
9.11.4.2 Globally Defined Backends
9.11.4.3 Special Backends
9.11.5 Session
9.11.6 Other Statements
9.12 Resolver
10 poundctl
10.1 'poundctl' commands
10.2 Using 'poundctl' for remote access
10.3 Configuring 'poundctl'
10.3.1 Multiple Servers Configuration
10.4 'poundctl' options
10.5 'poundctl' template
10.5.1 Template syntax
10.5.1.1 Actions
10.5.1.2 Arguments
10.5.2 Pipelines
10.5.3 Variables
10.5.4 Input object
10.5.4.1 Full listing
10.5.4.2 Listener
10.5.4.3 Service
10.5.4.4 Backend
Appendix A Metric Families
Appendix B Time and Date Formats
Appendix C GNU Free Documentation License
Index
1 Overview
**********
'Pound' is a reverse proxy, load balancer and HTTPS front-end for Web
servers. It was developed to provide for even distribution of load
between backend httpd servers and to allow for a convenient SSL wrapper
for those servers that do not offer it natively.
The core principles of its design are simplicity and safety. 'Pound'
is a very small program, easily audited for security problems. Normally
it runs as a non-privileged user, and can optionally be run in a
chrooted environment. With several exceptions, it does not access the
hard disk during its runtime. In short, it should pose no security
threat to the server it runs at.
The original version of 'pound' was written by Robert Segall at Apsis
GmbH(1). In 2018, I added support for newer OpenSSL to the then current
version of the program (2.8). This version of 'pound', hosted on
'github' was further modified by Rick O'Sullivan and Frank Schmirler,
who added WebSocket support.
On April 2020, Apsis started development of 'pound' 3.0 - essentially
an attempt to rewrite program from scratch, introducing dependencies on
some third-party software.
On 2022-09-19, the development and maintenance of 'pound' was
officially discontinued and Apsis GmbH was dissolved. Following that, I
decided to continue development of the program taking my fork as a base.
I considered the branch 3.0, which emerged for a short time before the
original project was abandoned, to be a failed experiment. To ensure
consistent versioning and avoid confusion, my versioning of 'pound'
started at number 4.0.
---------- Footnotes ----------
(1) <https://web.archive.org/web/20221202094441/https://apsis.ch/>
2 Introduction
**************
The job of a proxy server is to receive incoming HTTP or HTTPS requests,
route them to the corresponding web server ("backend"), wait for it to
reply and forward the response back to the querying party. If more than
one backend is configured to serve requests, the proxy should distribute
requests evenly between them, so that each backend gets a share of
requests proportional to its capacity.
'Pound' gets information about backends and instructions on HTTP
request routing from its configuration file 'pound.cfg'. It is located
in the "system configuration directory", which is normally '/etc'(1).
Syntactically, the configuration file is a sequence of "statements" and
"sections", separated by arbitrary amount of empty lines and comments.
A "simple statement" occupies a single line and consists of a keyword
("directive") and one or more values separated by whitespace. A
"section" is a compound statement that encloses other statements and
sections. Sections begin with a keyword, optionally followed by
arguments, and end with a word 'End' on a line by itself. All keywords
are case-insensitive.
The configuration file defines three kinds of objects: "listeners",
"services", and "backends". These are defined as configuration
sections.
A "listener" defines IP address (and optionally port), 'pound' will
be listening on for incoming requests. It can also be regarded as a
frontend definition. Listener declarations start with 'ListenHTTP' (for
plaintext HTTP frontends) or 'ListenHTTPS' (for HTTPS frontends)
keywords.
"Service" sections define rules that decide to which backend to route
requests received by the listeners. These rules normally involve
analysis of the requested URL or HTTP headers. A service may also
contain statements that modify requests or responses.
Services are normally declared inside listeners. Thus, when a
listener receives a request, it iterates over its services (in the order
of their appearance in the configuration file) to find the one that
matches the request. If such a service is found, it receives the
request and eventually passes it on to a backend.
Services may also be declared outside any listeners, in the global
scope. Such services are shared between all listeners. They are tried
if none of the services declared within a listener match the incoming
request.
Service declarations start with the 'Service' keyword.
"Backends" are objects that actually handle requests and produce
responses. Most often these are "regular backends", which declare IP
addresses and ports of servers that are to handle the requests.
Backends are defined inside of services, so that the service that
matched the request routes it to its backend. If more than one backend
is defined within a service, incoming requests will be distributed so
that each backend gets its share of the load.
Several special backend types are provided, such as emergency
backends, redirects, etc. Only one special backend can be declared for
a service, and it cannot be used together with other backend types.
Thus, an average request processing looks as follows. First, a
request is received by one of the listeners. The listener then iterates
over its services, until it finds one that matches the request. If no
such service was found, the listener retries the process with the
services defined in the global scope. If no matching service is found,
a 503 error ('Service Unavailable') is returned. Otherwise, if the
matching service was found, that service passes the request to one of
its backends. It may modify the request before that, if it is
instructed so by the configuration. Once the backend responds, the
service passes the response back to the listener (again, optionally
modifying it, if needed), which finally passes it back to the querying
party.
---------- Footnotes ----------
(1) The exact location depends on compilation options. When in
doubt, examine the output of 'pound -V'.
3 Usage
*******
When started, 'pound' first parses its configuration file. If any
errors are detected at this stage, it prints the appropriate diagnostics
on the standard error and exits with code 1. Otherwise, if the
configuration file is OK, 'pound' opens sockets declared in the listener
sections, detaches itself from the controlling terminal and starts
serving incoming requests. From that moment on, all diagnostic messages
are reported via 'syslog' (*note Logging::).
To check whether the configuration file is correct, run 'pound' with
the '-c' (for "check") configuration option:
pound -c
Started this way, 'pound' will check the configuration file, report
any errors, if found, and exit with status 0 if there are no errors or 1
otherwise. The option '-v' can be used to increase the verbosity level.
In particular, it instructs 'pound' to print a confirmation message on
standard error, if no errors have been encountered (by default it would
exit silently in this case).
To use alternative configuration file, supply its full pathname with
the '-f' option, e.g.:
pound -f /etc/pound/test.cfg
If you are experimenting with new configurations, you might want to
run 'pound' in foreground mode and have it print its diagnostics on the
standard error. This is done by the '-e' option. So, for testing
purposes, it is quite common to start it this way:
pound -e
Another option, '-F', has similar effect, except that it honors
logging settings from the configuration file (*note Logging::), i.e.
when used with this option, 'pound' will remain in foreground, but will
report its messages in accordance with its configuration file.
The following table summarizes all command line options:
'-c'
Check configuration file for syntax error and exit. Exit code
indicates whether the configuration is OK (0) or not (1).
'-e'
Start in foreground mode and log to standard error (or standard
output, for messages with LOG_DEBUG and LOG_INFO severity levels).
This option ignores the 'LogLevel' configuration setting (*note
Logging::).
'-F'
Foreground mode. Do not detach from the controlling terminal after
startup, but remain in the foreground instead. This overrides the
'Daemon' configuration setting (*note Daemon::). The log stream
(syslog facility or stderr) requested in the configuration file
remains in effect.
'-f FILE'
Read configuration from the supplied FILE, instead of from the
default location.
'-h'
Print short command line usage summary and exit.
'-p FILE'
Sets location of the "PID file". This is the file where 'pound'
will write its PID after startup. This option overrides the value
set by the 'PIDFile' configuration setting (*note PIDFile::).
'-v'
Verbose mode. During startup, error messages will be sent to
stderr (stdout, for 'LOG_DEBUG' and 'LOG_INFO' severities). If
'pound' is configured to log to syslog, error diagnostics will be
duplicated there as well. After startup the configuration settings
take effect.
When used with '-c' this option also instructs 'pound' to print an
extra confirmation message on standard error, if there are no
errors in the configuration file.
'-V'
Print program version, licensing terms, and configuration flags and
exit with status 0. You can use this option, in particular, to get
the default values 'pound' was built with, such as e.g.
configuration file location.
'-W FEATURE'
'-W no-FEATURE'
Enable or disable (if prefixed with 'no-') additional 'pound'
features. As of version 4.16.90, the following features are
implemented:
-- Feature: warn-deprecated
When parsing the configuration file, warn if it uses any
deprecated statements. This is the default. To suppress
deprecation messages, use '-W no-warn-deprecated'.
-- Feature: dns
Resolve host names found in configuration file and returned in
the 'Location:' header. This is the default.
You can use '-W no-dns' to disable it, in order to suppress
potentially lengthy network host address lookups. Make sure
if your configuration file refers to backends only by their IP
addresses in this case.
This setting affects also redirection location rewriting:
*Note RewriteLocation: Response Modification.
-- Feature: include-dir=DIR
-- Feature: no-include-dir
This controls the "include directory", i.e. the directory
where 'pound' looks for relative file names referred to in its
configuration file. *Note include directory::, for a detailed
discussion of this feature.
Using '-W include-dir=DIR' sets the new value of the include
directory.
By default, the system configuration directory is used as
include directory, so that any relative file names are looked
up there. To disable this, use the '-W no-include-dir'
option. 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 is useful
mainly in testsuite.
4 Simple Proxy
**************
In this chapter we will deploy several simplest proxying configurations
to illustrate the concepts introduced above.
Suppose you have an HTTP server running on localhost port 8080, and
want to make it accessible from outside. This is achieved by the
following configuration file:
ListenHTTP
Address 0.0.0.0
Port 80
Service
Backend
Address 127.0.0.1
Port 8080
End
End
End
This configuration consists of three nested sections: 'ListenHTTP',
'Service', and 'Backend'. Each section ends with a keyword 'End' on a
line by itself.
The first thing that draws attention are 'Address' and 'Port'
statements appearing in both listener and backend sections. In
'ListenHTTP' they specify the IP address and port to listen on for
incoming requests. Address '0.0.0.0' stands for all available IP
addresses(1). In 'Backend' section, these keywords specify the address
and port of the remote server, where incoming requests are to be
forwarded.
The 'Service' section has no matching conditions, so it will match
all requests.
---------- Footnotes ----------
(1) Strictly speaking, for all available _IPv4_ addresses. To bind
to all available IPv4 and IPv6 addresses, use '::0'.
4.1 Service Selection
=====================
To route requests to different servers, multiple services are used. In
this case, each service has one or more "matching rules", i.e.
statements that define conditions that a request must match in order to
be routed to that particular service. Syntactically, such rules have
the form:
KW [OPTIONS] "PATTERN"
where KW is a keyword specifying what part of the request is used in
comparison, PATTERN is a textual pattern which that part is matched
against, and OPTIONS are zero or more flags starting with a dash sign,
which define matching algorithm.
Perhaps the most often used condition is 'Host', which compares the
value of the HTTP 'Host' header with the given pattern. By default it
uses exact case-insensitive match:
Host "example.com"
To treat the pattern as a regular expression, use the '-re' option,
as in:
Host -re ".*\\.example\\.com"
Whenever we speak about regular expression we usually mean POSIX
extended regular expressions (*note POSIX extended regular expressions:
(sed)Extended regexps.). However, other regex types can also be used.
This is covered in *note Regular Expressions::.
Notice the use of double backslashes in the above example. The
backslash before each dot is needed to match it literally, while another
one protects the first one from being interpreted as an escape character
in string (*note Strings::).
Other useful options are '-beg' and '-end', which enable exact
matching at the beginning and end of the value, correspondingly. Thus,
the 'Host' statement above can be rewritten as:
Host -end ".example.com"
The set of options available for use in matching statements is
uniform. *Note Table 9.2: conditional-option, for a detailed discussion
of available options.
The following configuration snippet illustrates the use of matching
rules to select appropriate service (and, correspondingly, backend). It
will route all requests for 'www.example.com' to backend
'192.0.2.1:8080', and requests for 'admin.example.com' to
'192.0.2.4:8080':
ListenHTTP
Address 0.0.0.0
Port 80
Service
Host "www.example.com"
Backend
Address 192.0.2.1
Port 8080
End
End
Service
Host "admin.example.com"
Backend
Address 192.0.2.4
Port 8080
End
End
End
Other matching statements use POSIX regexp matching by default.
These are:
'Header'
Compare HTTP header against a pattern. E.g.
Header "Content-Type:[[:space:]]*text/.*"
'URL'
Match URL:
URL "/login/.*&name=.*"
'Path'
Match the path part of the URL:
Path -beg "/login"
'Query'
Match the query part of the URL.
'QueryParam'
Match the value of a query parameter. This statement takes two
arguments: parameter name and pattern, e.g.:
QueryParam "type" "(int)|(bool)"
*Note Service Selection Statements::, for a detailed description of
these and other matching statements.
Multiple matching rules can be used. Unless expressly specified
otherwise, they are joined by logical 'and' operation. For example:
Service
Host "www.example.com"
URL "^/admin(/.*)?"
Backend
Address 192.0.2.4
Port 8080
End
End
This service will be used for requests directed to host name
'www.example.com' whose URL begins with '/admin', optionally followed by
more path components (such as, e.g.
'http://www.example.com/admin/login').
To select a service that matches one of defined rules (i.e. combine
the rules using logical 'or'), enclose them in 'Match OR' block, as in:
Match OR
Host "example.com"
Host "www.example.com"
End
The argument to 'Match' can be 'OR' or 'AND', specifying logical
operation to be used to join the enclosed statements. The argument can
be omitted, in which case 'AND' is implied. 'Match' statements can be
nested to arbitrary depth, which allows for defining criteria of
arbitrary complexity. For example:
Service
Match OR
Host "admin.example.com"
Match AND
Host "www.example.com"
URL "^/admin(/.*)?"
End
End
Backend
Address 192.0.2.4
Port 8080
End
End
4.1.1 Regular Expressions
-------------------------
Request matching directives use POSIX extended regular expressions by
default. If 'pound' was compiled with 'PCRE' or 'PCRE2' library,
"Perl-compatible regular expressions" can be used instead. This can be
done either globally or individually for a given directive.
To change regular expression type globally, use the following
directive:
RegexType pcre
It affects all request matching directives that appear after it in
the configuration file, until next 'RegexType' directive or end of file,
whichever occurs first. To change back to POSIX regular expressions,
use 'posix' argument:
RegexType posix
Argument to the 'RegexType' directive is case-insensitive.
Regular expression type can also be selected individually for a
directive, using '-posix' or '-pcre' flags. For example:
Host -pcre -icase "(?<!www\\.)example.org"
4.1.2 ACL
---------
Access control lists, or "ACLs", are special request matching statements
that evaluate to true for requests originating from one of the
predefined IP addresses. Access control lists are defined using the
'ACL' section statement, which has three forms: anonymous, file
reference, and ACL reference.
In "anonymous" form, the 'ACL' is a section statement: the keyword is
followed by a newline and a list of CIDRs, terminated with 'End' on a
separate line. Each line in the list defines a single CIDR enclosed in
double quotes. A "CIDR" consists of a "network address" (IPv4 or IPv6),
optionally followed by slash and "network mask length", a decimal number
in the range [0,32] for IPv4 and [0,64] for IPv6. For example:
ACL
"127.0.0.1/8"
"192.0.2.0/25"
End
For convenience, 'Include' statements can also be used between 'ACL'
and 'End'.
In "file reference" form, the ACL syntax is:
ACL -file "NAME"
or
ACL -filewatch "NAME"
Here, NAME is the name of a disk file with the ACL definition. Its
syntax is similar to the contents of anonymous ACL definition, except
that CIDRs need not be quoted, and 'Include' statements are not allowed.
If the file name is relative, it is looked up in the *note include
directory::.
If the '-file' keyword is used, the file is read at startup and its
contents is remembered for the lifetime of the program. It is an error
if the file does not exist. Any errors in the file are treated as
configuration file errors and cause immediate program termination.
If the '-filewatch' keyword is used, the file is read at startup and
is being monitored for changes during the runtime. Once the file
changes, it is re-read and the ACL is reconstructed from its new
contents. If the file is removed, the ACL is cleared (which means that
it will evaluate to false during request matching), and a file creation
monitor is installed. Once the file is re-created, the monitor will
wake up, the file will be rescanned and the ACL updated accordingly.
Consequently, when '-filewatch' form is used, it is OK if the file
does not exist at startup. Furthermore, any errors in the file contents
are reported, but don't cause program termination.
On GNU/Linux systems, 'pound' uses 'inotify' kernel API (1), which
allows it to react immediately on the file system changes. On systems
where 'inotify' is not available, 'pound' falls back to periodic
checking for changes in file modification time. The interval between
two succeeding checks is defined by the 'WatcherTTL' statement (*note
WatcherTTL: Timeouts.).
The third syntax form for 'ACL' statements is "ACL reference". As
its name implies, the ACL in this form refers to another "named ACL",
defined elsewhere in the configuration files. Syntactically, it is
ACL "NAME"
where NAME is the name of the ACL to refer to. This syntax makes it
possible to use a single ACL in multiple places of the configuration
file.
Named access control lists are defined at the top level of a
configuration file. Syntactically, the definition is similar to
anonymous or file reference forms of ACLs as discussed above, except
that the keyword 'ACL' is followed on the same line by the name to be
assigned to that ACL, in double quotes. Thus the following are valid
named ACL declarations:
ACL "secure" -file "aclfile"
ACL "secure" -filewatch "aclfile"
ACL "secure"
"127.0.0.1/8"
"192.0.2.0/25"
End
All three examples define a named ACL 'secure'. The former two read
its contents from the disk file 'aclfile'. The latter one provides its
definition in the form of a section. This ACL can then be used in any
'Service' appearing after its definition by using the following
construct:
ACL "secure"
Consider for example the following service declaration:
Service
ACL "secure"
Path -beg "/stat"
Backend
...
End
End
This service will handle requests whose URL starts with '/stat', if
they came from one of the IP addresses mentioned in the access control
list with the name 'secure'. Effectively, this means that the access to
that URL is limited to these IP addresses.
---------- Footnotes ----------
(1) *Note monitoring file system events: (inotify(7))inotify. To
check, if your 'pound' binary is compiled with the support for inotify
API, examine the output of 'pound -V'.
4.2 Request modifications
=========================
A service can modify requests before forwarding them to backends.
Several statements are provided for that purpose:
SetHeader
Set a HTTP header.
DeleteHeader
Delete a HTTP header.
SetURL
Rewrite the request URL.
SetPath
Rewrite the path part of the URL.
SetQuery
Rewrite the query part of the URL.
SetQueryParam
Set a single query parameter.
For example, the following service declaration will add the header
'X-Resent-By: pound' to each request:
Service
SetHeader "X-Resent-By: pound"
Backend
...
End
End
Arguments to request modification statements are expanded before
actual use. During expansion, references to "parenthesized
subexpressions" in matching rules are replaced with their actual values.
"Parenthesized subexpression" is a part of a regular expression enclosed
in parentheses. It can be referred to in string arguments as '$N',
where N is its ordinal number. Numbers start at one, '$0' referring to
the entire string that matched.
The process of expanding parenthesized subexpressions is called
"backreference expansion".
For example, the following condition:
Header "Content-Type: ([^/]+)/(.+)$"
has two subexpressions: '$1' and '$2'. The following fragment uses
these values to add two query parameters to the URL:
SetQueryParam "type" "$1"
SetQueryParam "subtype" "$2"
As a more practical example, the following service rewrites the path
to JPEG and GIF images:
Service
Path "/([^/]+\\.(jpg|gif))$"
SetPath "/images/$1"
...
End
When several matching statements are used, these forms refer to the
last one that matched. Subexpressions in prior statements can be
referred to using the '$I(J)' construct. Here, J is the 0-based number
of the statement, counted from the last one upwards. For example, given
the following statements:
Host -re "www\.(.+)"
Header -icase "^Content-Type: *(.*)"
Path "^/static(/.*)?"
'$1' refers to the subexpression of 'Path', '$1(1)' to that of 'Header',
and '$1(2)' to that of 'Host'.
String arguments to 'Set' statements can also contain "request
accessors" - special constructs that are expanded to particular values
from the request. Syntactically, a request accessor is '%[NAME]', where
NAME denotes the request part to access. For example, '%[url]' expands
to entire URL, '%[path]' to the path part of the URL, etc.
Using request accessors, the above example of path modification can
be rewritten as:
Path "\\.(jpg|gif)$"
SetPath "/images%[path]"
*Note Request Accessors::, for a detailed discussions of available
accessors.
4.3 Conditional branches
========================
Conditional request modifications can be organized in logical branches,
each branch being applied only if the request matches certain condition.
The 'Rewrite' section encloses a set of request matching rules followed
by one or more request modification statements, which will be applied if
the former match the request. Optional 'Else' sub-section, which in
turn contains request matching rules and modification statements, will
be tried if those rules don't match. Any number of 'Else' sub-sections
is allowed, each one being tried if the previous ones don't match.
The example below illustrates this concept. This configuration
snippet sets different paths depending on the file type and URL used:
Service
Rewrite
Header "Content-Type:[[:space:]]+image/.*"
SetPath "/images%[path]"
Else
Match AND
Host "example.org"
Path "\\.[^.]+$"
End
SetPath "/static%[path]"
Else
Path "\\.[^.]+$"
SetPath "/assets%[path]"
End
...
End
4.4 Modifying responses
=======================
The 'rewrite' statement can also be used to modify responses received
from backends before passing them back to the querying party. To
indicate this intent, the 'Rewrite' statement must be followed by the
'response' keyword:
Rewrite response
SetHeader "X-Been-There: pound"
End
When modifying responses, only two request modification statements
are allowed: 'SetHeader' and 'DeleteHeader'. The list of request
matching rules is limited as well: 'Header' and 'StringMatch', plus
'Match' and 'Not' conditionals. Notice that these conditionals operate
on the response, and not on the request, as in previous chapters. For
example:
Rewrite response
Header "Content-Type:[[:space:]]+text/(.*)"
SetHeader "X-Text-Type: $1"
End
This will insert an additional 'X-Text-Type' header into the
response. It will contain the subtype value from the 'Content-Type'
header of the original response.
4.5 Authentication
==================
Along with access control lists, introduced above (*note ACL::),
authentication provides another way to limit access to certain services.
'Pound' supports "basic authentication", as defined in RFC 7617.
This authentication method relies on the presence of the
'Authorization' header in the HTTP request. If the header is present,
its value specifies the 'Basic' authorization method and contains
credentials (username and password) that match one of the users from the
server user database, the request is accepted. Otherwise a 401
('Authentication Required') or 407 ('Proxy Authentication Required')
response is returned with the 'WWW-Authenticate' header requesting basic
authentication.
The 'BasicAuth' request matching statement verifies if the
'Authorization' header is present and provides correct credentials. The
statement matches the request if so.
The 'BasicAuth' statement takes a single argument, specifying the
name of a file containing "user database". This is a plain-text file
created with 'htpasswd' 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:
* Password in plain text.
* Hash created by the system 'crypt'(3) function.
* Password hashed using SHA1 algorithm and encoded in BASE64. This
hash must be prefixed by '{SHA}'.
* 'Apache'-style 'APR1' hash.
Password file is read on the first authorization attempt, after which
its contents is stored in memory. 'Pound' will re-read it if it notices
that the file's modification file has changed, so you need not restart
the daemon if you do any changes to the file.
Thus, if you put the 'BasicAuth' statement in each service that must
be accessible to authorized users only, that would do the first and
principal part of the basic authentication scheme: access control.
There remains second part: returning properly formatted 401 response if
the request did not pass authorization. That can be done using a
combination of the 'Error' internal backend (*note Error responses::)
and response modification techniques described in the previous section.
However, instead of using 'BasicAuth' in each service requiring
limited access and placing a service generating the 401 response in the
end, it is simpler and less error-prone to use the following approach:
Create a service with the following content:
Service
Not BasicAuth "pound/htpasswd"
Rewrite response
SetHeader "WWW-Authenticate: Basic realm=\"Restricted access\""
End
Error 401
End
Replace the file name ('pound/htpasswd') and realm name ('Restricted
access') with the actual values.
Make sure that all services that need to be protected by basic
authentication are declared after that service. This way, any request
that does not convey an 'Authentication' header with credentials
matching an entry from your password file will match this service, and
will be replied to with a properly formatted 401 response, which will
prompt the remote user to authenticate themselves. On the other hand,
authorized requests will not match this service and will eventually be
handled by one of the services declared after it.
4.6 Redirects
=============
Apart from regular backends introduced in previous sections, 'pound'
provides also several "special" or "internal" backends. As their name
implies, such backends handle requests and generate responses
internally, without forwarding them to any external entities.
One of such internal backends is 'Redirect'. It generates responses
redirecting the client to another location. The statement takes two
arguments: a three-digit HTTP status code to return, and the URL to
redirect to:
Service
Redirect 301 "https://www.gnu.org"
End
Allowed values for the status code are 301, 302, 303, 307 and 308.
This argument is optional: if omitted, 302 is used.
If the URL argument has no path component (as in the example above),
then the path (and query, if present) components from the original
request will be appended to it. For example, if the original URL were
'http://example.com/software', the service above would redirect it
'https://www.gnu.org/software'.
Otherwise, if the path component is present in the URL argument (even
if it is a mere '/'), then the URL is used as is. For example, the
following will drop any path and query components from the URL when
redirecting:
Redirect 301 "https://www.gnu.org/"
The URL argument is subject to backreference expansion and request
accessor interpretation (*note Request modifications::). If any of
these are actually used, the above logic is disabled.
String expansions make it possible to implement complex redirects.
For example, the following redirect swaps the first two path components
of the original URL:
Service
URL "^/([^/]+)/([^/]+)(/.*)?"
Redirect "http://%[host]/$2/$1$3"
End
The following is a standard paradigm for redirecting requests from
HTTP to HTTPS:
Service
Redirect 301 "https://%[host]%[url]"
End
4.7 Error responses
===================
Another type of internal backends is 'Error', a backend that generates
error responses. It is useful, for instance, to provide a custom error
status and/or message when no service matches the request. Normally,
for such cases 'pound' generates a standard 503 response ('Service
Unavailable') with the built-in error page. You can customize this
behavior by using as the last service a 'Service' section with 'Error'
backend. For example:
Service
Error 404 "pound/404.html"
End
The first argument specifies the HTTP status code to return. *Note
Error backend::, for more info.
The second argument is optional. It supplies the name of a file with
the error page to return along with the response. The name may be
absolute or relative. In the latter case, the file will be looked up in
the "include directory", a special directory for storing pound-specific
files. *Note include directory::. The file will be read only once, at
program startup. If you modify the file and want 'pound' to notice
changes, you will have to restart it.
Unless the file begins with a newline or '<' character, its initial
portion up to first empty line (inclusive) supplies headers that will be
sent with the response. The following defaults will be used, unless
already defined in the file:
Content-Type: text/html
Expires: now
Pragma: no-cache
Cache-control: no-cache,no-store
If the second argument is not supplied, the error text is determined
by the 'ErrorFile CODE' statement in the enclosing listener (where CODE
is the HTTP code in question). If it is not supplied, the built-in
default text is used. *Note Error definitions::.
5 HTTPS
*******
In the previous chapter we have described basic proxying techniques
using plain HTTP listener as an example. Now we will discuss how to use
HTTPS both for listeners and backends.
To accept HTTPS requests you need to declare 'ListenerHTTPS'
listener. It is similar to plain 'ListenerHTTP' described above, except
that it requires a "certificate" to be declared. For example:
ListenHTTPS
Address 0.0.0.0
Port 443
Cert "/etc/ssl/priv/example.pem"
Disable TLSv1
Ciphers "HIGH:@STRENGTH:!RSA"
End
The 'Cert' statement supplies the name of the certificate file in PEM
format. The file must contain the certificate, intermediate
certificates (if necessary), and certificate private key, in that order.
The 'Cert' argument can also specify a directory, in which case
'pound' will scan that directory, trying to read the certificate from
each regular file encountered. It will report an error if unable to
load the file, so this directory should contain only certificate files.
The order in which certificate files are read is not specified.
Multiple 'Cert' statements are allowed. When trying to find the
matching certificate, 'pound' will stop at the first one whose 'CN'
matches the requested host name. Thus, the ordering of 'Cert'
statements is important. Normally they should be placed in
most-specific to least-specific order, with wildcard certificates
appearing after host-specific ones.
'Cert' directives must precede all other SSL-specific directives.
Another important directive is 'Disable'. It disables the use of the
specified TLS protocol as well as all protocols older than it. Usually
it is used to disable obsolete protocols. For example, the 'Disable'
statement in the example above disables 'TLSv1', 'SSLv3', and 'SSLv2'.
To further tune the strength of your encryption use the 'Ciphers'
directive. Its argument is a colon-delimited list of OpenSSL ciphers,
as described in *Note (ciphers(1))ciphers::. The cipher selection shown
in the example above provides for excellent encryption strength.
5.1 ACME
========
Automatic Certificate Management Environment ("ACME"), is a protocol for
automated deployment of HTTPS certificates. It is perhaps the most
often used method for obtaining SSL certificates nowadays. In order to
issue certificate for a domain or domains, the protocol verifies that
the web server that is requesting a certificate actually owns these
domains. This process is based on various "challenge types".
'Pound' supports HTTP-01(1) challenge type. When issuing a
certificate using this challenge type, the ACME client (a program
responsible for periodic certificate re-issuing) obtains from the
authority a challenge file, and stores it in a predefined "challenge
directory". The authority will then request this file from the
webserver using a predefined URL. It is supposed that the server will
serve it from the file that has been just written by the agent. If the
server returns the file, its claim to own the domain is proved and the
certificate is issued.
Configuring 'pound' to reply to challenge requests is as simple as
putting an 'ACME' statement to the 'ListenHTTP' section of its
configuration file. The statement takes a single argument - name of the
challenge directory:
ListenHTTP
Address 0.0.0.0
Port 80
ACME "/var/lib/pound/.well-known/acme-challenge"
End
Needless to say, your ACME agent and 'pound' must agree on this
directory location. Configuration of various ACME agents is beyond the
scope of this document. Please refer to the documentation of your agent
for further details.
---------- Footnotes ----------
(1) <https://letsencrypt.org/docs/challenge-types/#http-01-challenge>
5.2 Redirect HTTP to HTTPS
==========================
Nowadays it is common to redirect all plain HTTP requests to HTTPS on
the same URL. The method of doing so was described in *note HTTP to
HTTPS: Redirects. As an example, this section shows a working HTTPS
configuration with such redirect.
ListenHTTP
Address 0.0.0.0
Port 80
Service
Redirect 301 "https://%[host]%[url]"
End
End
ListenHTTPS
Address 0.0.0.0
Port 443
Cert "/etc/ssl/priv/example.pem"
Disable TLSv1
Service
Backend
Address 127.0.0.1
Port 8080
End
End
End
5.3 HTTPS backends
==================
Backends can use HTTPS as well. To inform 'pound' that communication
with the backend goes over an encrypted channel, use the 'HTTPS'
keyword. The typical usage is:
Backend
Address 192.0.2.1
Port 443
HTTPS
End
Notice, that unlike other statements, 'HTTPS' is used without
arguments.
Additional directives are available for fine-tuning the connection.
If used, they must appear after the 'HTTPS' directive,
The 'Cert' directive specify the client certificate to use when
connecting. Use it if the backend requires client authentication.
The 'Disable' and 'Ciphers' directives are similar to those described
when discussing 'ListenHTTPS': the former disables the given TLS
protocol and all protocols prior to it, and the latter configures the
list of OpenSSL ciphers which the client wishes to use. The actual
cipher to use will be selected from this list during negotiation with
the backend.
The example below illustrates the use of these directives:
Backend
Address 192.0.2.1
Port 443
HTTPS
Disable TLSv1_1
Cert "/etc/pound/crt/b1.pem"
Ciphers "HIGH:!RSA"
End
6 Request balancing
*******************
When several backends are defined in a service, incoming requests will
be distributed among them. This process is called "balancing". By
default, requests are distributed equally. This can be changed by
assigning them a "priority" - a positive integer which assigns a
relative weight of the given backend in the distribution algorithm. The
greater the priority is, the more requests this backend gets from the
total flow.
The distribution algorithm is defined by "balancing strategy". As of
version 4.16.90, 'pound' supports two strategies: "weighted random
balancing" and "interleaved weighted round robin balancing".
"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
proportionally 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
priority 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.
Overall, the share of requests a given backend receives can be
estimated as:
P_{i} / S(P)
where P_{i} is the priority of the backend with index i, and S(P) is the
sum of all priorities.
Weighted random balancing is used by default. Each backend gets the
default priority 5, unless another value is expressly assigned using the
'Priority' statement, e.g.:
Service
Backend
Address 192.168.0.1
Port 80
Priority 1
End
Backend
Address 192.168.0.2
Port 80
Priority 9
End
End
In this example, backend '192.168.0.2' will receive roughly 9 times
more requests than backend '192.168.0.1'.
The balancing strategy to use is defined by the 'Balancer' keyword,
which can appear either in the global scope or within a 'Service'
section. Its argument can be one of:
'random'
Use weighted random balancing (default).
'iwrr'
Use interleaved weighted round robin balancing.
The 'Balancer' statement appearing in the global scope defines
balancing strategy for all services that don't have 'Balancer' statement
on their own.
6.1 Sessions
============
Some web applications attempt to introduce state persistence into the
stateless HTTP protocol, by defining "sessions" using various
mechanisms, such as specially defined headers, cookies, etc. For such
applications it is critical that all requests that belong to a single
"session" be directed to the same server, i.e. backend. Clearly, this
disrupts the balancer logic, and requires that the proxy be able to
understand the backend's notion of session.
'Pound' is able to detect and track sessions identified by client
address, Basic authentication (user id/password), URL parameter, cookie,
HTTP parameter, and HTTP header value.
Session tracking is enabled on a per-service basis by a 'Session'
section. The section must contain at least the 'Type' directive, which
specifies what type of session tracking to use, and the 'TTL' directive,
supplying session idle timeout in seconds.
Session types are case-insensitive. They are summarized in the table
below:
'IP'
The 'IP' session tracking type instructs 'pound' to forward all
requests from the same client IP address to the same backend
server:
Session
Type IP
TTL 300
End
'Basic'
Using this session tracking type, 'pound' parses the
'Authentication' header of each request. If the header is present,
and specifies the 'Basic' authentication type, user ID is extracted
from it. Requests with the same user ID are forwarded to the same
backend server.
Session
Type Basic
TTL 300
End
'URL'
This tracking scheme uses the value of URL query parameter to
define a session. The parameter name is supplied using the 'ID'
directive:
Session
Type URL
TTL 300
ID "sess"
End
In this example, sessions are identified by the 'sess' parameter,
The request URL might look like 'http://example.org?sess=123'.
'Cookie'
The 'Cookie' tracking type use a certain cookie to identify
sessions. The cookie name is given by the 'ID' directive:
Session
Type Cookie
TTL 300
ID "sess"
End
'Header'
Sessions are identified by the value of HTTP header whose name is
given by the 'ID' directive, e.g.:
Session
Type Header
ID "X-Session"
TTL 300
End
'Parm'
This is the least useful scheme. Sessions are identified by HTTP
parameter - a string that appears after a semicolon in the URL,
such as 'bar' in 'http://foo.com;bar'
Session
Type PARM
TTL 300
End
6.2 Balancer groups
===================
Backends within each service 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 backends 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. Backends declared using the 'Emergency' keyword (*note
Emergency::) are assigned to the balancer group 65535. These backends
form a pull of "high availability" backends, which will be used if all
of the normal backends fail.
More backend groups can be added using dynamic backends, discussed in
the next section.
6.3 Dynamic backends
====================
Normally, when a backend is declared in configuration file, the value
supplied with its 'Address' statement is resolved at once and the
resulting IP is associated with the backend. Such backends are
"static". You can also instruct 'pound' to resolve the hostname and
create as many backends as are the IP addresses it resolves to. Such
backends are called "dynamic".(1) When a dynamic backend is requested,
the 'Backend' statement defines a "matrix" which will be used as a
template to generate actual backends from the data in DNS. The TTL value
of the DNS record (or records) defines minimum time to live of the
generated backends. When it expires, DNS will be queried again and
backends recreated according to the changes in its responses(2).
In the simplest case, a dynamic backend can be created using 'A' or
'AAAA' DNS records. If several records correspond to the hostname
defined in the 'Address' statement, 'pound' can either create a single
backend for each of them, or select one of them in round-robin fashion
and use it to create a backend. Rest of backend parameters (port value,
priority, etc.) will be taken from its matrix declaration.
A more advanced way to create dynamic backends is using 'SRV'
records. Each 'SRV' record has four associated parameters: priority,
weight, target and port. The "priority" value defines the 'pound'
balancer group where to put generated backends. "Weight" is assigned as
the priority for each generated backend(3). Finally, "target" is used
as hostname to obtain IP addresses for the backends. For example,
suppose the following DNS records are defined:
$ORIGIN _tcp.example.org.
; _srv TTL SRV prio weight port target.
_proxy 60 SRV 10 40 8081 be0.example.org.
_proxy 60 SRV 10 70 8082 be1.example.org.
_proxy 60 SRV 20 10 8081 ha1.example.org.
_proxy 60 SRV 20 10 8081 ha2.example.org.
Assuming each of the target hostnames resolves to one IP address,
these records will produce two balancer groups of two backends each, and
will be roughly equivalent to the following statements:
Backend
Address "be0.example.org"
Port 8081
Priority 40
End
Backend
Address "be1.example.org"
Port 8082
Priority 70
End
Emergency
Address "ha1.example.org"
Port 8081
Priority 10
End
Emergency
Address "ha2.example.org"
Port 8081
Priority 10
End
_Notice_, that an SRV record can have a weight of 0. This will
translate to 'pound' backend priority 0, which is normally not allowed
(*note Balancer::). According to RFC 2782, this is the preferred way of
defining weights where "there isn't any server selection to do", whereas
"[i]n the presence of records containing weights greater than 0, records
with weight 0 should have a very small chance of being selected".
'Pound' handles this as follows: if all 'SRV' records have zero weight,
priority of the resulting backends is set to 1. This makes sure the
backend selection algorithm works and gives each backend equal chance of
being selected. This translation does not take place, however, if at
least one of 'SRV' records has a weight greater than 0. Another way to
handle such records is using the 'IgnoreSRVWeight' configuration
statement, which is discussed below.
To declare backend as dynamic, use a symbolic host name in its
'Address' statement and add the 'Resolve' statement with one of the
following values:
-- Dynamic Resolve: first
Resolve the symbolic host name and use first IP from the DNS
response as the address of the created dynamic backend. Thus, this
type will produce at most one dynamic backend.
-- Dynamic Resolve: all
Resolve the symbolic host name and create one backend for each
address from the DNS response. This enables load balancing between
created backends. Each backend will be assigned the same priority.
-- Dynamic Resolve: srv
Obtain 'SRV' records for the host name and use them to generate
dynamic backends. Each record produces new dynamic backend of
'Resolve all' type, which creates regular backends as described
above. The weight field of the 'SRV' record is mapped to the
priority field of each generated backend. The priority field
determines the balancer group where the backend will be hosted.
When resolving hostnames, both IPv4 and IPv6 addresses are looked
for. You can select the specific address family using the 'Family'
statement. Its allowed values are:
'any'
Use all address families available. This is the default.
'inet'
Use only IPv4 addresses ('A' DNS records).
'inet6'
Use only IPv6 addresses ('AAAA' DNS records).
For example:
Backend
Address "_proxy._tcp.example.org"
Resolve srv
Family any
End
Notice, that you need not supply 'Port' statement for dynamic
backends of 'srv' resolve type. Normally, you don't need to supply
'Priority', either. However, you may do so, if you wish to override the
weight settings from 'SRV' records. In that case, inform 'pound' about
your decision using the following statement in 'Backend' section:
IgnoreSRVWeight true
There are several possible scenarios when this may be needed. One of
them is when all 'SRV' records have weight of 0 (see above) and your
configuration defines one or more regular backends in the same balancer
group as backends generated by those records. In that case, the default
priority assigned by 'pound' to those generated backends (1) may prove
to be too low for adequate balancing. Using 'IgnoreSRVWeight' allows
you to fix that. For example:
Service
Backend
Address 192.0.2.15
Port 80
Priority 8
End
Backend
Address "_proxy._tcp.example.org"
Resolve srv
Family any
IgnoreSRVWeight true
Priority 5
End
End
In this example, backends generated by 'SRV' records for domain
'_proxy._tcp.example.org' will be assigned priority 5, no matter what
the actual value of 'SRV' weight field.
Dynamic backends will be updated periodically, when the TTL of the
corresponding DNS records expires. If the hostname cannot be resolved
or a DNS failure occurs, next update will be scheduled in 600 seconds
after the failure. This interval can be configured using the
'RetryInterval' statement in the 'Backend' section, or globally, in the
'Resolver' section (*note resolver::).
---------- Footnotes ----------
(1) Support for dynamic backends is enabled at compile time and
requires the GNU adns library (http://www.gnu.org/software/adns). If
unsure whether your 'pound' binary includes it, inspect the 'pound -V'
output.
(2) If necessary, the TTL value can be changed using the
'OverrideTTL' configuration directive. *Note OverrideTTL: Backend.
(3) Notice, that the 'SRV' terminology differs from what 'pound'
uses. What is called priority in 'SRV' defines the "weight" of the
backend group for 'pound', whereas what is called weight in 'SRV'
defines the "priority" of a backend within a group. This confusion is
due to historical reasons, and it would be hard to avoid it without
breaking backward compatibility.
7 Worker model
**************
Each incoming request is processed by a specific "worker", i.e. a
thread in the running program. Total number of running workers is
controlled by three configuration parameters. 'WorkerMinCount' defines
the minimum number of workers that should always be running (5, by
default). Another parameter, 'WorkerMaxCount' sets the upper limit on
the number of running workers (it defaults to 128).
At each given moment, a worker can be in one of two states: "idle" or
"active" (processing a request). If an incoming request arrives when
all running workers are active, and total number of workers is less than
'WorkerMaxCount', a new thread is started and the new request is handed
to it. If the number of active workers has already reached maximum, the
new request is added to the "request queue", where it will wait for a
worker to become available to process it.
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'), this idle worker is terminated.
8 Logging
*********
'Pound' can send its diagnostic messages to standard error, syslog, or
to both.
Upon startup, while the configuration file is being parsed, the
diagnostics goes to the standard error. Once it switches to the
operation mode and starts serving requests, diagnostic output is
switched to syslog. The syslog facility to use is configured via the
'LogFacility' configuration directive. By default, 'daemon' is used.
When running in foreground mode, the '-e' command line option
instructs 'pound' to use standard error for logging, thus overriding the
settings from the configuration file.
Normally, 'pound' is not very loquacious in logging: only errors are
reported. Logging of each incoming request can be configured using the
'LogLevel' directive. It can be used either in listener scope, in which
case it affects only this particular listener, or in global scope, where
it affects all listeners that don't configure it on their own. The
value of this directive can be either an integer number in range 0
through 5 (inclusive), or a quoted string. Numeric value requests one
of the "built-in log formats". String value refers either to a built-in
format name, or to a user-defined format name.
The built-in formats are:
0
null
No request logging at all.
1
regular
For each request, its source address, request line and response
status are logged.
2
extended
In addition to the above, the selected service and backend are
shown.
3
vhost_combined
Detailed request logging using Apache-style "Combined" log format.
4
combined
Same as above, but without virtual host information.
5
detailed
Same as 'combined', with additional information about the selected
service and backend.
If the string argument to 'LogLevel' is not one of the above, it must
refer to the name of a "custom format", defined earlier using the
'LogFormat' statement. This statement takes two string arguments: the
name to be assigned to the new format, and its definition.
"Format definition" 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 conversion
character.
The following conversion characters are defined:
-- Format specifier: %%
Replaced with the percent sign.
-- Format specifier: %a
Originator IP address of the request. If the request contains
'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' is not present, or 'TrustedIP' is not defined,
or the above algorithm does not return an IP address, '%a' expands
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 a
'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, *note
ACL::),
TrustedIP
"CIDR0"
"CIDR1"
...
End
defines the list of trusted IPs in place, and
TrustedIP -file "FILENAME"
TrustedIP -filewatch "FILENAME"
reads CIDR definitions from file FILENAME.
If needed, the 'ForwardedHeader' statement may be used to declare
the name of the header to use instead of 'X-Forwarded-For'. As
'TrustedIP', this statement can appear in global, listener, or in
service scope.
-- Format specifier: %A
Local IP address of the listener.
-- Format specifier: %B
Size of response in bytes, excluding headers.
-- Format specifier: %b
Same as '%B', but in "CLF" format, i.e. a dash is used when
response size is zero.
-- Format specifier: %D
The time taken to serve the request, in microseconds.
-- Format specifier: %h
Client IP address of the request.
-- Format specifier: %H
The request protocol.
-- Format specifier: %{HDR}i
The contents of 'HDR:' header line in the request. Changes made by
header modification directives affect this.
-- Format specifier: %{HDR}I
Same as '%i', except that if no such header is present in the
request, a dash is substituted.
-- Format specifier: %{OBJ}L
Location of the 'pound' object that is involved in handling the
request. Valid values for OBJ are: 'listener', 'service', and
'backend'.
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 line
and column where the object definition begins, LN2 and COL2 are
line and column where it ends. Line and column numbers start with
1.
-- Format specifier: %m
The request method.
-- Format specifier: %{OBJ}N
Name of 'pound' object that is involved in handling the request.
Valid values for OBJ are: 'listener', 'service', and 'backend'.
-- Format specifier: %P
Thread ID of the serving thread.
-- Format specifier: %q
The query string (prepended with a '?') if it exists, otherwise an
empty string.
-- Format specifier: %r
First line of request.
-- Format specifier: %s
Response status code.
-- Format specifier: %>s
First line of the response.
-- Format specifier: %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 specifier: %{FORMAT}t
Time the request was received, in the format specified by the
argument (*note Time and Date Formats::). 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' 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.
-- Format specifier: %T
The time taken to process the request, in seconds.
-- Format specifier: %{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 seconds, 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'.
-- Format specifier: %u
Remote user if the request was authenticated.
-- Format specifier: %U
The URL path requested. This is affected by request modification
directives.
-- Format specifier: %v
The listener name.
The table below describes the built-in formats in terms of format
definitions:
0
null
""
1
regular
"%a %r - %>s"
2
extended
"%a %r - %>s (%{Host}i/%{service}N -> %{backend}N) %{f}T sec"
3
vhost_combined
"%{Host}I %a - %u %t \"%r\" %s %b \"%{Referer}i\" \"%{User-Agent}i\""
4
combined
"%a - %u %t \"%r\" %s %b \"%{Referer}i\" \"%{User-Agent}i\""
5
detailed
(Split in two lines for readability)
"%{Host}I %a - %u %t \"%r\" %s %b \"%{Referer}i\" \"%{User-Agent}i\"
(%{service}N -> %{backend}N) %{f}T sec"
9 Configuration
***************
A configuration file provides 'pound' with the information necessary for
performing its tasks. Some configuration file statements can be
overridden from the command line.
9.1 Lexical structure
=====================
Lexically, the file contains tokens of three types: keywords, values,
and separators. Blanks, tabs, newlines and comments, collectively
called "white space" are ignored except as they serve to separate
tokens. Some white space is required to separate otherwise adjacent
keywords and values.
"Comments" may appear anywhere where white space may appear in the
configuration file. A comment begins with a hash sign ('#') and
continues to the end of the line.
A "keyword" is a sequence of ASCII letters, digits and underscores
that begins with an ASCII letter or underscore. Keywords are always
case-insensitive.
There are three kinds of "values": numeric values (or "numbers"),
boolean values, quoted strings, and IP addresses.
"Numbers"
A "numeric value" is a sequence of decimal digits.
"Booleans"
A "boolean" is one of the following: 'yes', 'true', 'on' or '1',
meaning "true", and 'no', 'false', 'off', '0' meaning "false".
"Strings"
A "quoted string" or "string", for short, is a sequence of
characters enclosed in a pair of double quotes. A backslash ('\')
appearing within a string acts as an "escape character": if it is
followed by a double-quote or another backslash, it forces the
character that follows it to be treated as an ordinary one. For
example:
"string with \" character"
A backslash followed by any character other than '"' or '\' is
removed and a warning to that effect is output. For example, the
following statement:
user "r\oot"
appearing at line 1 of file 'pound.cfg' will result in the
following message:
pound.cfg:1.8: unrecognized escape character
and will be treated as
user "root"
"IP addresses"
IP addresses are IPv4 or IPv6 addresses in numeric form, or
hostnames.
9.2 Syntax
==========
Syntactically, 'pound' configuration is a sequence of statements of two
kinds: simple and compound.
A "simple statement" or "directive" consists of a keyword followed by
a value, located on a single line. For example:
user "proxy"
There are some simple statements that don't take any value and thus
consist only of a keyword, e.g.
HTTPS
A "compound statement" or "section" encloses one or more other
statements (both simple or compound). It begins with a keyword,
optionally followed by a value, both located on a single line (similar
to simple directives), followed by any number of subordinate statements,
and ends with a keyword 'End' on a line by itself. For example:
Control
Socket "/run/pound.sock"
Mode 660
ChangeOwner true
End
Unless specified otherwise, directives may appear in any order.
9.3 String Expansions
=====================
String arguments to some configuration statements undergo several
"expansions" before use. The "backreference expansion" replaces special
notations in the string called "backreferences" with corresponding parts
of the request recently matched against a regular expression. The
"request accessor interpretation" inserts some fragments of the request
URL into the string.
These expansions are discussed in detail below.
9.3.1 Backreference expansion
-----------------------------
Backreference is a construct that refers to a "parenthesized group"
within a regular expression matched by one of service matching
directives (*note Service Selection Statements::). During backreference
expansion, each occurrence of such construct is replaced with the actual
value of that parenthesized group.
Syntactically, backreferences can take two forms. The construct
'$N', where N is a decimal number, refers to Nth parenthesized
subexpression of the most recently matched statement, and the construct
'$N(M)' refers to Nth parenthesized subexpression in the Mth recently
matched statement. Numbering of subexpressions starts at 1 ('$0' refers
to entire matching string). Numbering of matches starts at 0.
For example, given the following statements
Host -re "www\\.(.+)"
Header -re -icase "^Content-Type: *(.*)"
Path "^/static(/.*)?"
'$1' refers to the subgroup of 'Path', '$1(1)' refers to that of
'Header', and '$1(2)' 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 the string, use '$$' or
'$%', correspondingly.
9.3.2 Request Accessor Interpretation
-------------------------------------
"Request accessor" is a syntactical construct of the form:
%[NAME]
where NAME denotes a part of the incoming request to access and square
brackets are part of the construct. Accessors are interpreted and
replaced with the value of the corresponding part of the request. Some
accessors take an argument, which is specified after accessor name and
is delimited from it by one or more whitespace characters.
The following accessors are defined:
-- Accessor: url
Request URL.
-- Accessor: path
Request path.
-- Accessor: query
Query part.
-- Accessor: param NAME
The value of the query parameter NAME.
-- Accessor: header NAME
The value of HTTP header NAME.
-- Accessor: host
Hostname part of the HOST header. If the latter does not include
port number, it is equivalent to '%[header host]'.
-- Accessor: port
If the value of the 'Host' header includes port number, '%[port]'
expands to port number with the leading colon character.
Otherwise, it expands to empty string.
9.4 Global directives
=====================
Global directives configure the program operation as a whole. They may
appear anywhere at the global scope of the configuration file, although
it is customary for them to be at its start.
9.4.1 Runtime directives
------------------------
-- Global directive: Daemon BOOL
When set to 'true' (the default), 'pound' will detach itself from
the controlling terminal after successful parsing of the
configuration file and continue operating in the background.
When set to 'false', 'pound' will continue operating in the
foreground.
This setting can be overridden by the '-F' and '-e' command line
options.
-- Global directive: Group "GROUP_NAME"
Sets the group 'pound' will run as. If not set, the primary group
of the user (as set by the 'User' directive) will be used.
-- Global directive: PIDFile "FILENAME"
Sets the name of the file where to store program PID. This can be
also be set from command line, using '-p' command line option
(*note Usage::).
Notice the following:
1. When running with a supervisor, this file holds PID of the
supervisor process. Otherwise, it holds PID of the main This
means it is always suitable for signalling the program using
the traditional 'kill `cat filename`' technique.
2. Before shutting down, 'pound' removes this file. However, it
may fail to do so if it switches to privileges of another user
after startup (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.
-- Global directive: Supervisor BOOL
When running in daemon mode, start a "supervisor" process. This
process, in turn, will start main 'pound' process and will further
monitor it, restarting it if it fails.
The default is 'true'.
-- Global directive: RootJail "DIRECTORY"
If this directive is present, 'pound' will use the system 'chroot'
call to set the root directory of the process to that specified by
DIRECTORY. After that, the program won't be able to access any
files outside that directory.
Before chrooting, 'pound' makes the necessary preparations to be
able to access the files it needs during operation, in particular
user databases supplied with the 'BasicAuth' statements (*note
Authentication::), and static file directories (*Note ACME::, and
*note SendFile::).
-- Global directive: User "USER_NAME"
Configures the user 'pound' will run as.
9.4.2 Worker Settings
---------------------
-- Global directive: WorkerMinCount N
Sets minimum number of worker threads that must always be running.
The default is 5. *Note Worker model::.
-- Global directive: WorkerMaxCount N
Sets maximum number of worker threads. The default is 128. *Note
Worker model::.
-- Global directive: WorkerIdleTimeout N
Sets idle timeout for a worker thread, in seconds. Default is 30
seconds. *Note Worker model::.
-- Global directive: Threads N
This statement, retained for backward compatibility with previous
versions of pound, is equivalent to:
WorkerMinCount N
WorkerMaxCount N
9.4.3 Proxy Tuning Directives
-----------------------------
-- Global directive: BackendStats BOOL
Whether to enable backend statistics collection. Backend
statistics consists of the following values:
1. Total number of requests processed by this backend.
2. Average time per request.
3. Standard deviation of the average time per request.
If enabled, these values are made available via 'poundctl' (*note
poundctl list::) and telemetry output (*note Metrics::).
-- Global directive: Balancer ALGO
Sets the request balancing algorithm to use. Allowed values for
ALGO are:
random
Use weighted random balancing algorithm.
iwrr
Use interleaved weighted round robin balancing.
*Note Balancer::, for a detailed discussion of these algorithms.
The 'Balancer' statement in global scope applies to all 'Service'
definitions in the file that don't contain 'Balancer' definitions
of their own.
-- Global directive: HeaderOption OPT ...
Sets default header addition options. One or more arguments are
allowed, each being one of:
'off'
Disable additional headers.
'forwarded'
Add 'X-For-warded-For', 'X-Forwarded-Proto', and
'X-Forwarded-Port' headers.
'ssl'
Pass information about SSL certificates in a set of 'X-SSL-*'
headers. This will add the following headers:
X-SSL-Cipher
SSL version followed by a slash and active cipher
algorithm.
X-SSL-Certificate
The full client certificate (multi-line).
X-SSL-Issuer
Information about the certificate issuer (CA).
X-SSL-Subject
Information about the certificate owner.
X-SSL-notAfter
End of validity date for the certificate.
X-SSL-notBefore
Start of validity date for the certificate.
X-SSL-serial
Certificate serial number (in decimal).
The default is:
HeaderOption forwarded ssl
This setting can be overridden for a particular listener using the
'HeadOption' within it.
-- Global directive: CombineHeaders
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 specifies that such fields can be combined in a single
header line, by appending each subsequent field value to the
combined field value in order, separated by a comma.
The 'CombineHeaders' statement declares names of the headers to
which 'pound' is to apply this operation. Each header name should
be listed on a separate line, enclosed in double-quotes. The
keyword 'End' on a line by itself ends the statement. E.g.:
CombineHeaders
"Accept"
"Allow"
"Cache-Control"
End
The 'include' statement (*note File inclusion::) can be used in
'CombineHeaders' statement.
'Pound' distribution includes file 'mvh.inc', which declares all
known multiple-value headers in a form suitable for inclusion to
'pound.cfg'. This file is installed in the package data directory,
so that in order to use it, it suffices to add the following to the
configuration file:
CombineHeaders
Include "mvh.inc"
End
9.4.4 SSL Settings
------------------
-- Global directive: SSLEngine "NAME"
Use an OpenSSL hardware acceleration card called NAME. Available
only if OpenSSL-engine is installed on your system.
-- Global directive: ECDHcurve "NAME"
Use the named curve for elliptical curve encryption.
9.4.5 Regular Expression Settings
---------------------------------
-- Global directive: RegexType TYPE
Sets the type of regular expressions to use in request matching
statements. Allowed values for TYPE are: 'posix' and 'pcre' (or
'perl'), case-insensitive. The latter requires compilation time
support.
The selected regular expression type remains in effect for all
request matching directives that follow this statement, until next
'RegexType' statement or end of the configuration file, whichever
occurs first.
Regular expression type can be set individually for a directive,
using the '-pcre' or '-posix' option (*note Table 9.2:
conditional-option.).
*Note Regular Expressions::, for a detailed discussion.
-- Global directive: IgnoreCase BOOL
Ignore case when doing regex matching (default: 'false'). This
directive sets the default for the following service matching
directives: '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 matching
directive instead (*note Table 9.2: conditional-option.).
9.4.6 ACL Definition
--------------------
-- Global directive: ACL "NAME"
Define a "named access control list". An "ACL" is a list of
network addresses in CIDR notation. Once defined, the ACL can be
used in 'Service' statements to limit access to resources (*note
ACL reference::).
The statement has two forms: immediate and file reference ACL. In
"immediate" form, the CIDR list follows the 'ACL' line and is
terminated with an 'End' directive on a line by itself. Each
non-empty line contains a CIDR enclosed in double quotes. Comments
and 'Include' statements are allowed. For example:
ACL "secure"
"192.0.2.0/26"
"203.0.113.0/24"
End
The syntax of named "file reference" ACL is:
ACL "NAME" -file "FILENAME"
or
ACL "NAME" -filewatch "FILENAME"
If FILENAME is relative, it is looked up in the *note include
directory::. The syntax of the file is similar to the described
above, except that CIDRs need not be quoted and 'Include'
statements are not allowed. The form with '-file' reads the file
contents once, at the program startup. The one with '-filewatch'
reads it and then monitors that file for changes. Any change to
the file causes it to be read again, thus the ACLs are updated
automatically without the need to restart the program. *Note File
reference ACL::, for a detailed discussion of this feature.
9.5 File inclusion
==================
-- Global directive: Include "FILE"
Include FILE as if it were part of the configuration file. If FILE
is a relative file name, it will be looked in the "include
directory" (see below).
This directive is allowed both at topmost level and in any
subsections of the configuration file.
-- Global directive: IncludeDir "DIR"
Set the "include directory", i.e. the directory where 'pound'
looks for relative file names that appear in other configuration
directives: 'Include', 'BasicAuth', 'ErrorFile' (or 'Err400'
through 'Err503'), as well as in the argument to '-file' option in
service matching directives (*note -file::).
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 command line using the '-W
include-dir=DIR' command line option or reset to the current
working directory using the '-W no-include-dir' option (*note
Usage::).
9.6 Logging configuration
=========================
-- Global directive: LogFacility NAME
-- Global directive: LogFacility -
Sets the 'syslog' facility to use for logging. Allowed names are:
'auth', 'authpriv', 'cron', 'daemon', 'ftp', 'kern', 'lpr'.
'mail', 'news', 'user'. 'uucp', and 'local0' through 'local7'.
The second form configures "default log destination". If 'pound'
runs in foreground, log messages with priority 'LOG_DEBUG' and
'LOG_INFO' go to stdout, and messages with the remaining priorities
are printed to stderr. If 'pound' runs as a daemon, log messages
go to the syslog facility 'daemon'.
-- Global directive: LogFormat "NAME" "FORMAT_DEF"
Define request logging format. NAME is a string uniquely
identifying this format, and FORMAT_DEF is the format string
definition. *Note Logging::, for a detailed description of format
definition syntax.
-- Global directive: LogLevel "NAME"
-- Global directive: LogLevel N
Specify the format to use to log HTTP requests. NAME is a name of
a custom format, defined earlier using the 'LogFormat' directive,
or one of six built-in format names.
If numeric argument is used, it refers to a built-in format by its
number (0 through 5).
*Note Logging::, for a detailed description of HTTP request
logging.
-- Global directive: LogTag "STRING"
Sets the string to tag syslog messages with. By default, it is the
name of the program (more precisely, the name which was used to
start it).
-- Global directive: ForwardedHeader "NAME"
Defines the name of the HTTP header that carries the list of
proxies the request has passed through. Default value is
'X-Forwarded-For'. This header is used to determine the originator
IP address for logging. *Note %a::, for details.
-- Global directive: TrustedIP
Defines a list of "trusted proxy" IP addresses, which is used to
determine the originator IP. *Note %a::, for details.
This statement is a special form of 'ACL' statement, described in
*note ACL::. It can have in three forms: "anonymous ACL", "file
reference", or "ACL reference".
Examples:
1. TrustedIP
"127.0.0.1/8"
"10.16.0.0/16"
End
2. TrustedIP -filewatch "/etc/pound/trustip.acl"
3. TrustedIP "proxy_addresses"
-- Global directive: Anonymise
-- Global directive: Anonymize
When logging, replace the last byte of client IP addresses with 0.
Default: log the client address in full.
9.7 Management Interface
========================
'Pound' provides a management interface, which allows one to obtain
information about the running instance, change state of configured
listeners, services, and backends, etc. These requests are normally
issued by the poundctl utility (*note poundctl::).
The management interface is usually made available via a UNIX socket.
Properties of this "control socket" are configured via the 'Control'
statement. It has two forms: "directive" and "section".
-- Global directive: Control "FILENAME"
Create a UNIX socket FILENAME and listen on it for management
requests. The file will be owned by the user that started 'pound'
(normally 'root') and have mode 0600.
In section form, the 'Control' statement allows for specifying file
mode and, to certain extent, socket file ownership. The section can
contain the following statements:
-- Control statement: Socket "FILENAME"
Specifies the name of the socket file to use. This is the only
mandatory statement in the section form.
-- Control statement: Mode OCTAL
Sets the mode of the socket file.
-- Control statement: 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.
An example of using the 'Control' section:
Control
Socket "/run/pound.sock"
Mode 660
ChangeOwner true
End
9.7.1 Remote Access to Management Interface
-------------------------------------------
To make the management interface available remotely, use the 'Control'
statement in a 'Service' section:
ListenHTTP
Address 192.0.2.1
Port 80
Service
Control
End
End
This configuration makes management interface accessible via
'http://192.0.2.1/'. Due to obvious security implications, you'd be
better off protecting the 'Control' endpoint using HTTPS, ACLs and/or
basic authorization. The example below illustrates all these
techniques:
ListenHTTPS
Address 192.0.2.1
Port 443
Cert "/etc/ssl/priv/example.pem"
Disable TLSv1
Service
Not BasicAuth "pound/htpasswd"
Rewrite response
SetHeader "WWW-Authenticate: Basic realm=\"Restricted access\""
End
Error 401
End
Service
ACL "secure"
Control
End
End
*Note Authentication::, for a discussion of 'BasicAuth' statement,
and see *note ACL:: for a discussion of access control lists (this
example assumes that the ACL 'secure' is defined elsewhere in the
configuration file).
If you wish to make management interface available under a special
path, make sure the path prefix is stripped off, e.g.:
Service
URL -re "^/control(/.+)"
SetURL "$1"
Control
End
*Note Service Request and Response Modification::, for details about
'SetURL' statement and request modification in general.
9.8 Timeouts
============
Directives discussed in this section set various timeout values. Their
argument is an integer expressing the value in seconds.
-- Global directive: Alive N
Specify how often should 'pound' check for the status of backend
servers marked as "dead" (i.e. inaccessible). 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.
Default is 30 seconds.
-- Global directive: Client N
Specify for how long 'pound' will wait for a client request
(default: 10 seconds). It will drop the connection if client
doesn't send any data within this interval.
This value can be overridden for specific listeners.
-- Global directive: TimeOut N
Specify for how long 'pound' will wait for the backend to respond
(default: 15 seconds).
This value can be overridden for specific backends.
-- Global directive: ConnTO N
Specify for how long 'pound' will wait for a connection to a
backend to be established. Default is the same as the 'TimeOut'
value.
This value can be overridden for specific backends.
-- Global directive: WatcherTTL N
If file reference ACLs are used on a system that doesn't support
'inotify' API, this directive defines the interval between two
successive checks of file modification times. *Note ACL
filewatch::, for a detailed discussion of this feature and
situations when this setting might be useful.
The default value is 180 seconds.
-- Global directive: WSTimeOut N
Specify for how long 'pound' will wait for data from either backend
or client in a connection upgraded to WebSocket protocol. Default
is 600 seconds.
This value can be overridden for specific backends.
-- Global directive: Grace N
How long should 'pound' continue to answer existing connections
after a receiving a 'INT' or 'HUP' signal (default: 30 seconds).
The configured listeners are closed immediately. You can bypass
this behaviour by stopping 'pound' with a 'TERM' or 'QUIT' signal,
in which case the program exits without any delay.
9.9 ListenHTTP
==============
The 'ListenHTTP' section declares a listener operating in plaintext HTTP
mode. The section declaration begins with the keyword 'ListenHTTP'
optionally followed by a string supplying symbolic name for that
listener, e.g.:
ListenHTTP "main"
...
End
The symbolic name can be used in log messages (*note '%{OBJ}N': log
format.) and in 'poundctl' (*note poundctl::) requests to identify that
listener. If the name is not supplied, the listener can be identified
by its ordinal number (0-based) in the configuration file.
9.9.1 Listener address
----------------------
-- ListenHTTP directive: Address ADDRESS
The IP address that 'pound' will listen on. This can be a numeric
IPv4 or IPv6 address, or a full pathname of a UNIX socket. To
listen on all available interfaces, use '0.0.0.0' (for IPv4), or
'::0' (for both IPv4 and IPv6).
If neither 'Address' or 'SocketFrom' are supplied, '::0' is
assumed.
-- ListenHTTP directive: Port N
The port number or service name (as per '/etc/services' that this
listener will listen on.
If this directive is not given, the default port number is assumed
(80 for 'ListenHTTP' and 443 for 'ListenHTTPS').
-- ListenHTTP directive: SocketFrom "PATHNAME"
Read the socket to listen on from the UNIX socket supplied by
PATHNAME. If this parameter is supplied, neither 'Address' nor
'Port' may be used. This parameter is intended for use in 'pound'
testsuite.
9.9.2 Listener-specific limits
------------------------------
-- ListenHTTP directive: Client N
Specify for how long 'pound' will wait for a client request
(default: 10 seconds). It will drop the connection if client
doesn't send any data within this interval.
This statement overrides the global timeout value (*note
Timeouts::) for this particular listener.
-- ListenHTTP directive: MaxRequest N
Limits the maximum allowed size of incoming requests. A request
bigger than that will be responded with status 413.
By default, there is no limit on the request size.
-- ListenHTTP directive: MaxURI N
Limits the maximum allowed length of incoming request URI. A
request with an URI longer than that will be responded with status
414.
By default, there is no limit on the URI length.
-- ListenHTTP directive: CheckURL "PATTERN"
Define a pattern that must be matched by each request sent to this
listener. A request that does not match will be returned a 501
status.
-- ListenHTTP directive: xHTTP N
Defines which HTTP method are accepted. The possible values are:
0
Accept only standard HTTP methods: 'GET', 'POST', 'HEAD'.
This is the default.
1
Allow also extended HTTP methods: 'PUT', 'PATCH', 'DELETE'.
2
Additionally allow standard WebDAV methods: 'LOCK', 'UNLOCK',
'PROPFIND', 'PROPPATCH', 'SEARCH', 'MKCOL', 'MOVE', 'COPY',
'OPTIONS', 'TRACE', 'MKACTIVITY', 'CHECKOUT', 'MERGE',
'REPORT'.
3
Additionally allow MS extension WebDAV methods: 'SUBSCRIBE',
'UNSUBSCRIBE', 'NOTIFY', 'BPROPFIND', 'BPROPPATCH', 'POLL',
'BMOVE', 'BCOPY', 'BDELETE', 'CONNECT'.
9.9.3 Error definitions
-----------------------
When 'pound' returns an error status, it uses built-in error-specific
description code and status page template. These values can be
customized using the 'ErrorFile' statement.
-- ListenHTTP directive: ErrorFile CODE "FILENAME"
Read HTML page for HTTP status code CODE from file FILENAME.
The CODE argument is a three-digit HTTP response status, and
FILENAME is the name of a file which supplies contents (and,
optionally, HTTP headers) of the error response. *Note Error
responses::, for details about the file and its usage.
For compatibility with 'pound' versions up to 4.11, the following
statement is also recognized:
ErrNNN "FILENAME"
where NNN is a three-digit HTTP status code. This statement is entirely
equivalent to
ErrorFile NNN "FILENAME"
'Pound' produces only a subset of all possible status codes, so not
all NNN codes are allowed. The discussion below lists available HTTP
codes, along with the error description and default error page text.
-- HTTP status: 400
'Bad Request'
Your browser (or proxy) sent a request that this server could
not understand.
-- HTTP status: 401
'Unauthorized'
This server could not verify that you are authorized to access
the document requested. Either you supplied the wrong
credentials (e.g., bad password), or your browser doesn't
understand how to supply the credentials required.
-- HTTP status: 403
'Forbidden'
You don't have permission to access this resource. It is
either read-protected or not readable by the server.
-- HTTP status: 404
'Not Found'
The requested URL was not found on this server.
-- HTTP status: 405
'Method Not Allowed'
The request method is not supported for the requested
resource.
-- HTTP status: 413
'Payload Too Large'
The request content is larger than the proxy server is able to
process.
-- HTTP status: 414
'URI Too Long'
The length of the requested URL exceeds the capacity limit for
this server.
-- HTTP status: 500
'Internal Server Error'
The server encountered an internal error and was unable to
complete your request.
-- HTTP status: 501
'Not Implemented'
The server does not support the action requested.
-- HTTP status: 503
'Service Unavailable'
The server is temporarily unable to service your request due
to maintenance downtime or capacity problems. Please try
again later.
9.9.4 Listener logging
----------------------
Following statements are similar to the ones described in *note Logging
configuration::, but apply only to the listener they appear in.
-- ListenHTTP directive: LogLevel "NAME"
-- ListenHTTP directive: LogLevel N
Specify the format to use to log HTTP requests. NAME is a name of
a custom format, defined earlier using the 'LogFormat' directive,
or one of six built-in format names.
If numeric argument is used, it refers to a built-in format by its
number (0 through 5).
*Note Logging::, for a detailed description of HTTP request
logging.
-- ListenHTTP directive: ForwardedHeader "NAME"
Defines the name of the HTTP header that carries the list of
proxies the request has passed through. Default value is
'X-Forwarded-For'. This header is used to determine the originator
IP address for logging. *Note %a::, for details.
-- ListenerHTTP directive: TrustedIP
Defines a list of "trusted proxy" IP addresses, which is used to
determine the originator IP. *Note %a::, for details.
9.9.5 Request Modification
--------------------------
The statements discussed in this subsection modify incoming requests
prior to passing them to the backend. These same set of statements can
also be used in 'Service' section (*note Service::). When appearing in
both sections, the directive from 'ListenHTTP' ('ListenHTTPS') section
are applied first, followed by directives from the 'Service' section.
Directives from the same section are applied in order of their
appearance.
-- ListenerHTTP directive: RewriteDestination BOOL
If set to 'true', the 'Destination:' request header will be changed
to point to the backend with the correct protocol.
-- ListenerHTTP directive: SetURL "URL"
Set the URL of the incoming request to URL.
-- ListenerHTTP directive: SetPath "VALUE"
Set the path part of the URL to the given string.
-- ListenerHTTP directive: 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
percent encoding.
-- ListenerHTTP directive: SetQueryParam "NAME" "VALUE"
Set the query parameter NAME to the VALUE. Value must be properly
encoded if it contains reserved characters.
-- ListenerHTTP directive: SetHeader "NAME: VALUE"
-- ListenerHTTP directive: HeaderAdd "NAME: VALUE"
-- ListenerHTTP directive: AddHeader "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.
The 'HeaderAdd' and 'AddHeader' forms are retained for backward
compatibility with earlier 'pound' versions. You are advised
against using them.
-- ListenerHTTP directive: DeleteHeader [OPTIONS] "PATTERN"
Remove from the request all headers matching PATTERN. The
'HeaderRemove' and 'HeadRemove' forms are retained for backward
compatibility with earlier 'pound' versions. You are advised
against using them.
By default, PATTERN is treated as extended POSIX regular
expression. The OPTIONS argument can be used to alter this. It
consists of zero or more option flags from the following list:
Flag Meaning
--------------------------------------------------------------------------
'-beg' Exact match at the beginning of string (prefix
match).
'-case' Case-sensitive comparison.
'-contain' Delete each header where "PATTERN" is a
substring.
'-end' Exact match at the end of string (suffix match).
'-exact' Use exact string match.
'-icase' Case-insensitive comparison.
'-pcre' Use Perl-compatible regular expression.
*note Regular Expressions::.
'-perl' Same as '-pcre'.
'-posix' Use POSIX extended regular expression.
*note Regular Expressions::.
'-re' Use regular expression match. This assumes the
default regular expression type, as set by the
'RegexType' directive
(*note Regular Expressions::).
Table 9.1: Header matching flags for 'DeleteHeader' directive
The following options are mutually exclusive: '-beg', '-contain',
'-end', '-exact', '-pcre' ('-perl'), '-posix', '-re'. If more than
one of these are used, the last one takes effect.
-- ListenerHTTP directive: HeaderRemove "PATTERN"
-- ListenerHTTP directive: HeadRemove "PATTERN"
These are obsolete keywords, equivalent to
DeleteHeader -icase "PATTERN"
9.9.5.1 The 'rewrite' statement
...............................
The 'Rewrite' block statement associates one or more header modification
directives discussed above with "request matching directives", so that
request modification takes place only when the request matches certain
conditions.
Syntactically, a 'Rewrite' section is:
Rewrite [ request ]
CONDITIONAL_DIRECTIVES...
MODIFICATION_DIRECTIVES...
[ Else
CONDITIONAL_DIRECTIVES...
MODIFICATION_DIRECTIVES... ]
End
where CONDITIONAL_DIRECTIVES represents one or more "request
conditionals" described below and MODIFICATION_DIRECTIVES stands for one
or more header modification directives. The 'Else' part is optional;
any number of 'Else' blocks can be supplied, thus providing for
conditional branching.
The 'Rewrite' statement is processed sequentially until a branch is
found whose CONDITIONAL_DIRECTIVES yield 'true', or 'End' is
encountered. If a matching branch is found, its MODIFICATION_DIRECTIVES
are applied to the request.
"Request matching directives" or "request conditionals" are special
statements that, being applied to a HTTP request, yield 'true' or
'false' depending on whether the request satisfies the condition
described in the directive. The following conditionals are available:
-- Request Conditional: ACL "NAME"
Returns 'true' if the source IP matches one of the CIDRs from the
named access control list NAME. The ACL itself must have been
defined earlier (*note ACL definition::).
*Note ACL::, for a detailed discussion.
-- Request Conditional: ACL
This statement defines an unnamed ACL to match the source IP
against. This line must be followed by one or more lines defining
CIDRs, as described in *note ACL definition::. The ACL definition
is finished with an 'End' keyword on a line by itself.
Semantically, this statement is equivalent to the named ACL
reference described above.
*Note ACL::, for a detailed discussion.
-- Request Conditional: ACL -file "FILENAME"
-- Request Conditional: ACL -filewatch "FILENAME"
Defines an unnamed ACL to match the source IP against. The ACL
definition is read from the file FILENAME, one CIDR per line.
Empty lines and comments are allowed. If FILENAME is relative, it
is looked up in the *note include directory::. The form with
'-file' reads the file contents once, at the program startup. The
one with '-filewatch' reads it and then monitors that file for
changes. Any change to the file causes it to be read again, thus
the ACLs are updated automatically without the need to restart the
program.
*Note File reference ACL::, for a detailed discussion of this
feature.
-- Request Conditional: BasicAuth "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' or similar utility. Unless the name starts with a
slash, it is taken relative to the 'IncludeDir' directory (*note
include directory::). The file is cached in the memory on the
first authorization attempt, so that further authorizations do not
result in disk operations. The file will be re-scanned if 'pound'
notices that its modification time has changed.
*Note Authentication::.
-- Request Conditional: Header [OPTIONS] "PATTERN"
Yields 'true', if the request contains at least one header matching
the given PATTERN. By default, PATTERN is treated as
case-insensitive POSIX extended regular expression. This can be
changed by OPTIONS, described below.
-- Request Conditional: Host [OPTIONS] "HOSTNAME"
Evaluates to 'true', if the 'Host' header matches HOSTNAME. In the
absence of OPTIONS, case-insensitive exact match is assumed, i.e.
this construct is equivalent to
Header "Host:[[:space:]]*QHOST"
where QHOST is the HOSTNAME argument in quoted form, i.e. with all
characters that have special meaning in regular expressions
escaped.
*Note Table 9.2: conditional-option, for a detailed discussion of
OPTIONS and their effect on matching.
This statement is provided to facilitate handling of "virtual
hosts". *Note Service selection::, for details.
-- Request Conditional: Path [OPTIONS] "PATTERN"
Returns 'true', if the path part of the incoming request matches
PATTERN.
-- Request Conditional: Query [OPTIONS] "PATTERN"
Returns 'true', if the query part of the incoming request matches
PATTERN. The argument must be properly percent-encoded, if it
contains whitespace or other non-printable characters.
-- Request Conditional: QueryParam "NAME" [OPTIONS] "PATTERN"
Returns 'true', if the value of the query parameter NAME matches
PATTERN.
*Note Table 9.2: conditional-option, for a detailed discussion of
OPTIONS and their effect on matching.
-- Request Conditional: StringMatch "STRING" [OPTIONS] "PATTERN"
Expands STRING as described in *note String Expansions:: and
matches the resulting value against PATTERN.
-- Request Conditional: URL [OPTIONS] "PATTERN"
Matches URL of the request. PATTERN is treated as case-sensitive
extended regular expression, unless instructed otherwise by OPTIONS
(see below).
In these directives, OPTIONS is a whitespace-delimited list of zero
or more flags from the following table:
Flag Meaning
--------------------------------------------------------------------------
'-beg' Exact match at the beginning of string (prefix
match).
'-case' Case-sensitive comparison.
'-contain' Match if PATTERN is a substring of the original
value.
'-end' Exact match at the end of string (suffix match).
'-exact' Use 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 *note include directory::.
Patterns are read from the file line by line.
Leading and trailing whitespace is removed.
Empty lines and comments (lines starting with
'#') are ignored.
'-icase' Case-insensitive comparison.
'-pcre' Use Perl-compatible regular expression.
*note Regular Expressions::.
'-perl' Same as '-pcre'.
'-posix' Use POSIX extended regular expression.
*note Regular Expressions::.
'-re' Use regular expression match. This assumes the
default regular expression type, as set by the
'RegexType' directive
(*note Regular Expressions::).
Table 9.2: Conditional directive flags
The following options are mutually exclusive: '-beg', '-contain',
'-end', '-exact', '-pcre' ('-perl'), '-posix', '-re'. If more than one
of these are used, the last one takes effect.
Placing the keyword 'Not' before a header matching directive reverts
its meaning. For example, the following will match any request whose
URL does not begin with '/static/':
Not URL -beg "/static/"
The 'Match' block statement can be used to join multiple header
matching directives. Its syntax is:
Match OP
...
End
where ... stands for any number of matching directives, and OP is a
boolean operation: 'AND' or 'OR' (case-insensitive). For example, the
statement
Match OR
Host "www.example.net"
Path -beg "/ssl"
End
will match if the request 'Host' header has the value 'www.example.net',
or the path part of its URL starts with '/ssl'. In contrast, the
statement below:
Match AND
Host "www.example.net"
Path -beg "/ssl"
End
will match only if both these conditions are met. As a syntactical
short-cut, two or more matching statements appearing outside of 'Match'
are joined by an implicit logical 'AND', so that the latter example is
equivalent to:
Host "www.example.net"
Path -beg "/ssl"
The 'Match' statement, like any other matching directive, can be
prefixed with 'Not', which reverts its meaning.
9.9.6 Response Modification
---------------------------
-- ListenerHTTP directive: RewriteLocation N
This statement controls whether 'Location:' and 'Content-location:'
headers in HTTP responses are modified before sending them back to
the client.
If N is 0, both headers are left intact.
If N is 1, the headers are changed as follows. If they point to
the backend itself or to the listener (but with the wrong
protocol), the request host name will be used instead. This is the
default.
If N is 2, do the same, but compare only the backend address; this
is useful for redirecting a request to an HTTPS listener on the
same server as the HTTP listener.
To check whether the location points to the listener or to the
backend, its hostname part is resolved and the obtained IP address
(or addresses) are compared with that of listener or backend. This
process is affected by the 'dns' feature setting (*note dns::). If
it is disabled ('-W no-dns' option is given), no resolving takes
place. In this case the location is deemed to point to the
listener if its hostname part matches that of the incoming request.
For backends, the hostname is compared with the value of the
'ServerName' setting of that backend (*note ServerName::), if any.
9.9.6.1 The 'Rewrite response' statement.
.........................................
A special form of the 'Rewrite' statement is provided for modifying
headers in the response obtained from a regular backend or generated
with a 'Error' backend, before sending them back to the requesting
server:
Rewrite response
CONDITIONAL_DIRECTIVES...
MODIFICATION_DIRECTIVES...
[ Else
CONDITIONAL_DIRECTIVES...
MODIFICATION_DIRECTIVES... ]
End
The conditional directives allowed for use in this statement are:
-- Rewrite response conditional: Header [OPTIONS] "PATTERN"
Returns 'true', if the response contains at least one header
matching the given PATTERN.
-- Rewrite response conditional: StringMatch "STRING" [OPTIONS]
"PATTERN"
Expands STRING as described in *note String Expansions::, and
matches the resulting value against PATTERN.
Both conditionals treat their PATTERN argument as case-insensitive
POSIX extended regular expression. *Note Table 9.2: conditional-option,
for a discussion of available OPTIONS.
The following "response modification" directives are defined:
-- Response modification: DeleteHeader [OPTIONS] "PATTERN"
Remove matching headers from the response. By default, PATTERN is
treated as extended POSIX regular expression. Use OPTIONS to alter
this behavior. *Note Table 9.1: deleteheader-option, for a list of
available options.
-- Response modification: SetHeader "NAME: VALUE"
Sets the HTTP response header. Argument undergoes string expansion
(*Note String Expansions::). If the header NAME already exists, it
will be overwritten. Otherwise, new header will be added to the
end of the header list.
9.9.7 Rewriting error responses
-------------------------------
When a regular backend responds with an error, the content (body) of
that response can be replaced with an arbitrary custom page. For this
to work, the following conditions should be met:
1. Response status code is one of error codes that 'pound' itself can
return. These are listed in *note Error definitions::.
2. A custom error page is defined for that status code using the
'ErrorFile' statement.
3. Error response rewriting is explicitly enabled for the service that
contains the backend from which the response is obtained, or for
the listener where that service is located. To do so use the
following statement:
-- ListenerHTTP directive: RewriteErrors BOOL
Enables or disables error response rewriting for that listener.
The same statement is available for use within a service (see
below). The 'RewriteErrors' setting of a service overrides that of
the listener.
9.9.8 Service definitions
-------------------------
The 'Service' section defines rules that decide to which backend to
route requests received by that listener. Any number of 'Service'
sections can be present. When a request is received, the listener
iterates over all services in the order of their appearance in the
configuration and applies the section rules to the request. If the
rules match the request, the request is forwarded to the backend defined
in that section.
*Note Service::, for a detailed discussion of the 'Service'
statement.
-- ListenHTTP statement: ACME DIR
This statement defines a special service with a built-in backend
for handling 'ACME' challenge requests. *Note ACME::, for a
detailed discussion of its use.
The DIR argument defines the directory where to look for challenge
files.
9.10 ListenHTTPS
================
The 'ListenHTTPS' section defines a listener that operates in HTTPS. The
section declaration begins with the keyword 'ListenHTTPS' optionally
followed by a string supplying symbolic name for that listener:
ListenHTTPS "main"
...
End
The purpose of the symbolic name is the same as in 'ListenHTTP'
statement. All keywords defined for 'ListenHTTP' can be used for
'ListenHTTPS' as well. *Note ListenHTTP::, for a detailed discussion of
these.
Statements specific for this section are:
-- ListenHTTPS: Cert "FILENAME"
Specifies the server "certificate". FILENAME is either a
certificate file name, or the name of a directory containing
certificate files.
A "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 within 'ListenHTTPS'.
Multiple 'Cert' directives are allowed. If multiple directives are
used, the first one is the default certificate, with additional
certificates used if the client requests them.
The ordering of the directives is important: the first certificate
where the CN matches the client request will be used, so put your
directives in the most-specific-to-least specific order (i.e.
wildcard certificates after host-specific certificates).
'Cert' directives must precede all other SSL-specific directives.
-- ListenHTTPS: ClientCert MODE DEPTH
Specifies whether the listener must ask for the client's HTTPS
certificate. Allowed values for MODE are:
0. Never ask for the certificate (the default).
1. Ask for the client certificate.
2. Ask and fail, if no certificate was presented.
3. Ask but do not verify.
DEPTH is the depth of verification for a client certificate (up to
9). The default depth limit is 9, allowing for the peer
certificate and additional 9 CA certificates that must be verified.
-- ListenHTTPS: Disable PROTO
Disable the SSL protocol PROTO and all lower protocols as well.
Allowed values for PROTO are: 'SSLv2', 'SSLv3', 'TLSv1', 'TLSv1_1',
'TLSv1_2'.
For example:
Disable TLSv1
This disables SSLv2, SSLv3 and TLSv1, thus allowing only TLSv1_1
and TLSv1_2.
-- ListenHTTPS: Ciphers "CIPHER_LIST"
This is the list of ciphers that will be accepted by the SSL
connection; it is a string in the same format as in 'OpenSSL'
'ciphers' and 'SSL_CTX_set_cipher_list' functions.
-- ListenHTTPS: SSLHonorCipherOrder BOOL
If set 'true', the server will broadcast a preference to use
ciphers in the order supplied in the 'Ciphers' directive. If the
value is 'false', the server will accept any cipher from the
'Ciphers' list. Default value is 'false'.
-- ListenHTTPS: SSLAllowClientRenegotiation MODE
If MODE is 0, client initiated renegotiation will be disabled.
This will mitigate DoS exploits based on client renegotiation,
regardless of the patch status of clients and servers related to
"Secure renegotiation". If MODE is 1, secure renegotiation is
supported. If MODE value is 2, insecure renegotiation is
supported.
The default value is 0.
-- ListenHTTPS: 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 (in PEM
format). The names of the defined CA certificates will be sent to
the client on connection.
-- ListenHTTPS: VerifyList "FILENAME"
Set the certificate authority list. The FILENAME is the name of a
file with CA root certificates, in PEM format.
_Please note_, that 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.
-- ListenHTTPS: CRLlist "FILENAME"
Set the "Certificate Revocation List" file. FILENAME is the name
of a file that contains the CRLs (in PEM format).
-- ListenHTTPS: NoHTTPS11 MODE
Behave like an 'HTTP/1.0' server for HTTPS clients. If MODE is 0,
always conform to HTTPS/1.1. If it is 1, do not allow multiple
requests on SSL connections. If the value is 2 (default), disable
multiple requests on SSL connections only for MSIE clients.
9.11 Service
============
The 'Service' statements define backends to use and conditions a request
should satisfy in order to be routed to these backends. These
statements can appear both within 'ListenHTTP' ('ListenHTTPS') sections
and outside of them. When processing an incoming request, the listener
will first try to match it against services defined within it. If none
of these services matches the request, it will try to match it against
services defined in the top level. If a matching service is found, it
will be used to process the request. Otherwise a 503 ("Service
Unavailable") response will be returned.
A service is defined by a section statement that begins with the
'Section' keyword, followed by service definition statements and
terminated by 'End' on a line by itself:
Service "NAME"
...
End
Optional NAME argument assigns a symbolic name to the service. That
name is used to identify the service in diagnostic and access log
messages (*note '%{OBJ}N': log format.), metric output (*note
Metrics::), and in 'poundctl' requests (*note poundctl::). In the
absence of an assigned NAME, the ordinal number of the service in the
enclosing section is used as its identifier. Service numbers start at
0.
Following subsections discuss statements that can be used in
'Service' sections.
9.11.1 Service Selection Statements
-----------------------------------
Service selection statements define conditions an incoming request must
satisfy in order to be handled by this service.
-- Service Conditional: ACL "NAME"
Returns 'true' if the source IP of the request matches one of the
CIDRs from the named access control list NAME. The ACL itself must
have been defined earlier (*note ACL definition::).
*Note ACL::, for a detailed discussion.
-- Service Conditional: ACL
This statement defines an unnamed ACL to match the source IP
against. This line must be followed by one or more lines defining
CIDRs, as described in *note ACL definition::. The ACL definition
is finished with an 'End' keyword on a line by itself.
Semantically, this statement is equivalent to the named ACL
reference described above.
*Note ACL::, for a detailed discussion.
-- Service Conditional: BasicAuth "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' or similar utility. Unless the name starts with a
slash, it is taken relative to the 'IncludeDir' directory (*note
include directory::). The file is cached in the memory on the
first authorization attempt, so that further authorizations do not
result in disk operations. The file will be rescanned if 'pound'
notices that its modification time has changed.
*Note Authentication::.
-- Service Conditional: ClientCert "FILENAME"
Evaluates to 'true' if the client presents the certificate matching
that from the file FILENAME (PEM format).
This conditional cannot be used in standalone services (i.e.
services that are defined in global scope). It also cannot be used
if the 'ListenHTTPS' section that hosts the service has the
'ClientCert' statement on its own.
-- Service Conditional: Header [OPTIONS] "PATTERN"
Yields 'true', if the request contains at least one header matching
the given PATTERN. By default, PATTERN is treated as
case-insensitive POSIX extended regular expression. This can be
changed by OPTIONS, described below.
-- Service Conditional: Host [OPTIONS] "HOSTNAME"
Evaluates to 'true', if the 'Host' header matches HOSTNAME. In the
absence of OPTIONS, case-insensitive exact match is assumed, i.e.
this construct is equivalent to
Header "Host:[[:space:]]*QHOST"
where QHOST is the HOSTNAME argument in quoted form, i.e. with all
characters that have special meaning in regular expressions
escaped.
*Note Table 9.2: conditional-option, for a detailed discussion of
OPTIONS and their effect on matching.
This statement is provided to facilitate handling of "virtual
hosts". *Note Service selection::, for details.
-- Service Conditional: Path [OPTIONS] "PATTERN"
Returns 'true', if the path part of the incoming request matches
PATTERN.
-- Service Conditional: Query [OPTIONS] "PATTERN"
Returns 'true', if the query part of the incoming request matches
PATTERN. The argument must be properly percent-encoded, if it
contains whitespace or other non-printable characters.
-- Service Conditional: QueryParam "NAME" [OPTIONS] "PATTERN"
Returns 'true', if the value of the query parameter NAME matches
PATTERN.
*Note Table 9.2: conditional-option, for a detailed discussion of
OPTIONS and their effect on matching.
-- Service Conditional: StringMatch "STRING" [OPTIONS] "PATTERN"
Expands STRING as described in *note String Expansions::, and
matches the resulting value against PATTERN.
-- Service Conditional: URL [OPTIONS] "PATTERN"
Matches URL of the request. PATTERN is treated as case-sensitive
extended regular expression, unless instructed otherwise by OPTIONS
(see below).
The OPTIONS argument in the directives discussed above defines the
comparison algorithm used. It consists of one or more flags described
in *note Table 9.2: conditional-option.
Placing the keyword 'Not' before a header matching directive reverts
its meaning. For example, the following will match any request whose
URL does not begin with '/static/':
Not URL -beg "/static/"
The 'Match' block statement can be used to join multiple header
matching directives. Its syntax is:
Match OP
...
End
where ... stands for any number of matching directives, and OP is a
boolean operation: 'AND' or 'OR' (case-insensitive). *Note Match in
service statement::, for a detailed discussion with examples.
9.11.2 Request and Response Modification
----------------------------------------
These statements modify incoming requests prior to passing them to the
backend. A similar set of statements can be used in listeners (*note
Request Modification::). In case both the listener and service contain
request modification statements, those from the listener are applied
first, followed by the ones from the service.
-- Service directive: SetURL "URL"
Set the URL of the incoming request to URL.
-- Service directive: SetPath "VALUE"
Set the path part of the URL to the given string.
-- Service directive: 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
percent encoding.
-- Service directive: SetQueryParam "NAME" "VALUE"
Set the query parameter NAME to the VALUE. The value must be
properly encoded if it contains reserved characters.
-- Service directive: SetHeader "NAME: VALUE"
-- Service directive: HeaderAdd "NAME: VALUE"
-- Service directive: AddHeader "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.
The 'HeaderAdd' and 'AddHeader' forms are retained for backward
compatibility with earlier 'pound' versions. You are advised
against using them.
-- Service directive: DeleteHeader [OPTIONS] "PATTERN"
-- Service directive: HeaderRemove [OPTIONS] "PATTERN"
-- Service directive: HeadRemove [OPTIONS] "PATTERN"
Remove from the request all headers matching PATTERN. The
'HeaderRemove' and 'HeadRemove' forms are retained for backward
compatibility with earlier 'pound' versions. You are advised
against using them.
By default, PATTERN is treated as extended POSIX regular
expression. The OPTIONS argument can be used to alter this. It
consists of zero or more option flags, described in *note Table
9.1: deleteheader-option.
-- Service statement: Rewrite [ request | response ] ... End
This block statement associates one or more header modification
directives discussed above with "request matching directives", so
that request modification takes place only when the request matches
certain conditions.
By default 'Rewrite' statements apply to incoming requests. The
subject of rewriting can also be specified explicitly after the
'Rewrite' keyword.
*Note Rewrite::, for a detailed discussion of this statement.
*Note Conditional branches::, for an in-depth discussion with
examples.
*Note Modifying responses::, for a discussion of the use of this
statement to modify responses.
-- Service directive: RewriteErrors BOOL
Enables or disables error response rewriting for that service.
*Note Error response rewriting::, for a detailed discussion.
9.11.3 Service Logging
----------------------
-- Service directive: ForwardedHeader "NAME"
Defines the name of the HTTP header that carries the list of
proxies the request has passed through. Default value is
'X-Forwarded-For'. This header is used to determine the originator
IP address for logging. *Note %a::, for details.
-- Service directive: TrustedIP
Defines a list of "trusted proxy" IP addresses, which is used to
determine the originator IP.
*Note %a::, for a detailed discussion.
This statement is a special form of 'ACL' statement, described in
*note ACL::. It can appear in three forms: "anonymous ACL", "file
reference", or "ACL reference". Examples:
1. TrustedIP
"127.0.0.1/8"
"10.16.0.0/16"
End
2. TrustedIP -filewatch "/etc/pound/trustip.acl"
3. TrustedIP "proxy_addresses"
-- Service directive: LogSuppress CLASS [CLASS...]
Suppresses HTTP logging for requests that resulted in status codes
from the specified classes. Valid classes are:
info
1
'1xx' response codes.
success
2
'2xx' response codes.
redirect
3
'3xx' response codes.
clterr
4
'4xx' response codes.
srverr
5
'5xx' response codes.
all
All response codes.
This statement is designed for services that receive a constant
stream of similar HTTP requests from a controlled set of IP
addresses, such as e.g. Openmetric services. *Note Metrics::, for
an example.
9.11.4 Backends
---------------
9.11.4.1 Backend
................
The 'Backend' section defines a regular backend. The overall syntax, as
for any section statement, is:
Backend [ "NAME" ]
...
End
Optional NAME argument assigns a symbolic name to the service. That
name is used to identify the backend in diagnostic and access log
messages (*note '%{OBJ}N': log format.), metric output (*note
Metrics::), and in 'poundctl' requests (*note poundctl::). In the
absence of an assigned NAME, the ordinal (0-based) number of the backend
in the enclosing 'Service' is used as its identifier.
The following statements can be used in a 'Backend' section:
-- Backend directive: Address IP
IP address or host name of the backend server. If the name cannot
be resolved to a valid address, 'pound' will assume that it
represents a path to a Unix-domain socket.
This directive is mandatory.
-- Backend directive: Disabled BOOL
Mark this backend as disabled.
Backends can be enabled or disabled at runtime using the 'poundctl'
utility (*note enable: poundctl commands.).
_Note:_ not to be confused with the 'Disable' statement, described
below.
-- Backend directive: Port N
Sets the port number to connect to. This directive must be present
if the 'Address' statement contains an IP address.
-- Backend directive: Priority N
Sets numeric priority for this backend. Priorities are used to
control probability of receiving a request for handling in case of
multiple backends. *Note Balancer::, for a detailed discussion.
Allowed values for N are 1 to 65535.
Following directives configure "dynamic backends". *note Dynamic
backends::, for a detailed discussion:
-- Backend directive: Family NAME
Defines the address family to look for when resolving hostnames:
'any'
Use all address families available. This is the default.
'inet'
Use only IPv4 addresses.
'inet6'
Use only IPv6 addresses.
-- Backend directive: IgnoreSRVWeight BOOL
When using 'SRV' records, ignore their weight fields. Instead,
copy priority of the producing backend to generated backends.
This directive is valid when used together with 'Resolve srv' (see
below).
-- Backend directive: OverrideTTL N
This directive configures update interval (in seconds) for dynamic
backends (*note Dynamic backends::). At the end of each update
interval, the DNS be queried and dynamic backends reconfigured (if
needed) according to its responses. By default, the TTL value
obtained from previous DNS response is used.
To configure the interval to retry failed DNS lookups, see
'RetryInterval', below.
-- Backend directive: Resolve TYPE
Declares a dynamic backend. Valid values for TYPE are
'first'
Resolve the symbolic host name and use first IP from the DNS
response as the address of the created dynamic backend. Thus,
this type will produce at most one dynamic backend.
'all'
Resolve the symbolic host name and create one backend for each
address from the DNS response. This enables load balancing
between created backends. Each backend will be assigned the
same priority.
'srv'
Obtain 'SRV' records for the host name and use them to
generate dynamic backends. Each record produces new dynamic
backend of 'Resolve all' type, which creates regular backends
as described above. The weight field of the 'SRV' record is
mapped to the priority field of each generated backend. The
priority field determines the balancer group where the backend
will be hosted.
-- Backend directive: RetryInterval N
Retry failed DNS lookups in N seconds. Default is 600.
See also the 'RetryInterval' statement in 'Resolver' section (*note
resolver::).
The following three directives set various timeout parameters for
backend operations:
-- Backend directive: ConnTO N
Sets "connection timeout", i.e. time to wait for establishing
connection with the backend (in seconds).
-- Backend directive: TimeOut N
Sets the "response timeout", i.e. time to wait for a response from
the backend (in seconds). Default is 15.
-- Backend directive: WSTimeOut N
Idle timeout for WebSocket operations, in seconds. Default value:
600 (10 minutes).
Backend servers can use HTTPS as well as plaintext HTTP. The
following directives configure HTTPS backends:
-- Backend directive: HTTPS
This directive indicates that the remote server speaks HTTPS.
-- Backend directive: Cert "FILENAME"
This specifies the certificate that 'pound' will use as a client.
The FILENAME is the name of a file containing the certificate,
possibly a certificate chain and the signature.
-- Backend directive: Ciphers "CIPHERLIST"
This is the list of ciphers that will be accepted by the SSL
connection with the backend (for HTTPS backends); it is a string in
the same format as used by the OpenSSL functions 'ciphers' and
'SSL_CTX_set_cipher_list'.
-- Backend directive: Disable PROTO
Disable the SSL protocol PROTO and all earlier protocols. Allowed
values for PROTO are: 'SSLv2', 'SSLv3', 'TLSv1', 'TLSv1_1',
'TLSv1_2'.
_Note:_ not to be confused with the 'Disabled' statement, described
above.
-- Backend directive: ServerName "NAME"
This directive specifies the name to use for server name
identification ("SNI"). It also rewrites the 'Host:' header for
this particular backend. This means you don't have to use
'SetHeader' in addition to it.
9.11.4.2 Globally Defined Backends
..................................
The 'Backend' section described above can also be used at the topmost
level of the configuration file. Use this if you plan to use same
backend in several different services.
When used globally the 'Backend' keyword must always be followed by
the backend name in double-quotes. The assigned name must be unique
among all global backends.
To include a globally defined backend in a service, use 'UseBackend'
or 'Backend' keywords.
-- Service directive: UseBackend "NAME"
Use globally-defined backend NAME in this service. The backend
itself may be defined in global scope before or after the 'Service'
section that uses it.
The 'UseBackend' keyword adds the backend to the service exactly as
it was defined. However, it may sometimes be necessary to alter its
priority and state. To do so, use the 'Backend' section. If the name
argument specifies a globally-defined backend, the 'Backend' section can
contain only the 'Priority' and 'Disable' statements.
9.11.4.3 Special Backends
.........................
Special backends are backends that don't rely on an external server to
handle the response, but instead are served by 'pound' itself.
-- Service directive: Error STATUS [FILE]
Return a particular HTTP status.
The STATUS argument supplies the HTTP status code to return.
Optional FILE argument is the name of a disk file with the error
page content. If not supplied, the text is determined as usual:
first the 'ErrorFile STATUS' statement from the enclosing listener
is consulted. If it is not present, the default error page is
used.
This directive is useful in a catch-all service, which outputs an
error page if no service matching the incoming request was found.
*Note Error responses::, for a discussion.
-- Service directive: Redirect [CODE] "URL"
Declares a special backend that responds to each request with a
redirect response.
Optional CODE can be one of: 301, 302 (the default), 303, 307, or
308.
The URL argument specifies the URL to redirect the request to.
Before use it is expanded as described in *note String
Expansions::.
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 that host, with the original request path appended.
If the URL does contain a path (even if it is just a '/'), then the
request path is ignored.
*Note Redirects::, for a detailed discussion of this backend and
its use.
-- Service directive: SendFile DIR
Defines a special backend that serves static files from directory
DIR. Name of the file to serve is supplied by the request path,
after applying usual request modifications (*note Request
Modification::). By default, the response bears 'Content-Type:
text/plain' header. To change this, use 'SetHeader' statement in
response rewriting (*note rewrite response::).
The following example defines a service which will serve requests
to paths beginning with '/about/' from directory
'/var/lib/pound/static'. Name of the file to serve is obtained by
removing the '/about/' prefix from the request pathname. Content
type is set to 'text/html':
Service
Path -re "/about/(.+)"
SetPath "$1"
Rewrite response
SetHeader "Content-Type: text/html"
End
SendFile "/var/lib/pound/static"
End
-- Service directive: Control
Defines a special backend that serves "pound management interface".
*Note Service Control::, for a detailed discussion of this feature.
-- Service directive: Metrics
This directive defines a special backend that generates Openmetric
telemetry output on the given URL. Example usage:
Service
URL "/metrics"
Metrics
End
To control access to the telemetry endpoint, use the 'ACL'
statement (*note ACL::).
The 'LogSuppress' directive (*note LogSuppress::) is often used in
openmetric services to suppress logging of served HTTP requests:
Service
URL "/metrics"
Metrics
ACL "secure"
LogSuppress success
End
The metrics output is discussed in *note Metric Families::.
-- Service directive: Emergency ... End
Defines an "emergency backend", which will be used only if all
other backends become unavailable. *Note Backend::, for a
discussion of directives that can be used within 'Emergency'
section.
If multiple 'Emergency' sections are defined, an emergency backend
to use will be selected using the usual balancing technique (*note
Balancer::).
9.11.5 Session
--------------
-- Service directive: Session ... End
Defines how a service deals with possible HTTP sessions. Once a
session is identified, 'pound' will attempt to send all requests
within that session to the same backend server.
*Note Sessions::, for a detailed discussion of HTTP sessions and
their handling.
The following directives are available for use in 'Session' section.
-- Session directive: Type TYPE
Defines the expected type of sessions to handle. Allowed values
for TYPE are:
'IP'
A session is defined by the source IP. All requests coming
from the same IP are considered to be in the same session.
The IP address is defined by the 'ID' statement (see below).
'BASIC'
A session is defined by the 'Authentication' HTTP header. If
the header is present, and specifies the 'Basic'
authentication type, user ID is extracted from it.
'URL'
A session is identified by the value of a particular query
parameter. The name of the parameter is given by the 'ID'
statement.
'PARM'
Sessions are identified by HTTP parameter - a string that
appears after a semicolon in the URL, such as 'bar' in
'http://foo.com;bar'.
'COOKIE'
Sessions are identified by the value of an HTTP cookie, whose
name is given by the 'ID' directive.
'HEADER'
Sessions are identified by the value of HTTP header whose name
is given by the 'ID' directive.
-- Session directive: ID "NAME"
Specifies the "session identifier": IP address (for 'Type IP'),
query parameter name (for 'Type URL'), cookie name (for 'Type
COOKIE'), or header name (for 'Type HEADER').
-- Session directive: TTL N
How long can a session be idle (in seconds). A session that has
been idle for longer than the specified number of seconds will be
discarded. This directive is mandatory.
9.11.6 Other Statements
-----------------------
-- Service directive: Disabled BOOL
If 'true', mark this service as disabled. Disabled services are
not used for request processing. A service can be enabled or
disabled at runtime using the 'poundctl' utility (*note enable:
poundctl commands.).
-- Service directive: Balancer ALGO
Sets the request balancing algorithm to use. Allowed values for
ALGO are:
random
Use weighted random balancing algorithm.
iwrr
Use interleaved weighted round robin balancing.
*Note Balancer::, for a detailed discussion of these algorithms.
This statement overrides the global 'Balancer' statement (*note
Balancer: Global directives.).
-- Service directive: IgnoreCase BOOL
Ignore case when doing regex matching (default: 'false'). This
directive sets the default for the following service matching
directives: 'URL', 'Path', 'QueryParam', 'Query', 'StringMatch', as
well as for the 'DeleteHeader' modification directive.
This statement is deprecated and will be removed in future
versions. Please, use the '-icase' option to the matching
directive instead (*note Table 9.2: conditional-option.).
9.12 Resolver
=============
The 'Resolver' section controls DNS lookups for dynamic backend
generation (*note Dynamic backends::). It can contain the following
directives:
-- Resolver: 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 occurs sometimes in the wild. By default,
'pound' does not accept CNAME chains. If you work with nameservers
that declare such chains, set this statement to a small integer
value, defining maximum number of CNAME records in the chain that
'pound' will accept. The value of 2 or 3 should suffice in most
cases.
-- Resolver: ConfigFile FILE
Read resolver configuration from FILE. Default is
'/etc/resolv.conf'.
-- Resolver: ConfigText ... End
The material within this section is read verbatim and used as the
content of the resolver configuration file. E.g.:
Resolver
ConfigText
domain example.org
nameserver 192.0.2.1
nameserver 192.0.2.4
End
End
If both 'ConfigFile' and 'ConfigText' are used, the last statement
used wins.
-- Resolver: Debug BOOL
If set to 'true', enables DNS debugging info.
-- Resolver: 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.
10 poundctl
***********
The 'poundctl' command displays status of various objects of the running
instance and allows you to change some of them.
The program communicates with the running 'pound' daemon via a UNIX
socket or remotely, via HTTP or HTTPS. The URL of the communication
socket can be given explicitly by the '-s' command line option, or
obtained from 'poundctl' or 'pound' configuration files.
If the '.poundctl' exists in the home directory, the configuration
will be obtained from it. Otherwise, if 'poundctl' runs on the same
machine as the 'pound' daemon and communicates with it via the UNIX
socket, the program will scan the 'pound.cfg' file for the 'Control'
statement (*note Control statement::) and read the socket file name from
it. These ways of configuring 'poundctl' are discussed below, in *note
poundctl config::. In examples below, it is assumed that the socket URL
is obtained from one of configuration files.
The program invocation syntax is:
poundctl [OPTIONS] COMMAND OBJECT [ARG]
Here, OPTIONS are command line options, COMMAND is a command verb that
instructs 'poundctl' what to do, OBJECT identifies the 'pound' object to
operate upon (*note objects::), and optional ARG supplies argument to
the command verb.
Pound objects identifiers are formed in a path-like fashion:
/LISTENER/SERVICE/BACKEND
where:
LISTENER
Symbolic name of the listener or its ordinal number in the
configuration. If referring to a globally-defined service, or to a
backend in such a service, a dash is used.
SERVICE
Symbolic name or ordinal number of the service located in that
listener.
BACKEND
Ordinal number of backend in the service.
Depending on the command, either '/BACKEND' or both
'/SERVICE/BACKEND' may be omitted.
For example, the following command will disable backend 2 in service
1 of listener 0:
poundctl disable /0/1/2
Assuming listener 0 is named 'web', this example can also be written
as:
poundctl disable /web/1/2
The following command disables the listener 0 itself:
poundctl disable /0
A dash in place of LISTENER refers to the global scope. Thus, the
following disables service 1 defined in the global scope of 'pound.cfg':
poundctl disable /-/1
10.1 'poundctl' commands
========================
-- poundctl: list /L/S/B
-- poundctl: list /L/S
-- poundctl: list /L
-- poundctl: list
Lists status of the given object and its subordinates. Without
argument, shows all listeners and underlying objects.
-- poundctl: enable /L/S/B
-- poundctl: enable /L/S
-- poundctl: enable /L
-- poundctl: on /L/S/B
-- poundctl: on /L/S
-- poundctl: on /L
Enables listener, service, or backend.
-- poundctl: disable /L/S/B
-- poundctl: disable /L/S
-- poundctl: disable /L
-- poundctl: off /L/S/B
-- poundctl: off /L/S
-- poundctl: off /L
Disables listener, service, or backend.
-- poundctl: delete /L/S KEY
Delete the session with the given key. Notice that backend may not
be specified.
-- poundctl: add /L/S/B KEY
Add a session with the given KEY.
10.2 Using 'poundctl' for remote access
=======================================
Starting from version 4.14, 'pound' is able to provide its management
interface via HTTP (*note Service Control::). To use remote management
interface, supply its URL with the '-s' command line option. The URL
syntax is:
SCHEME://[USER[:PASSWORD]@]HOSTNAME[:PORT][/PATH]
where '[]' denote optional parts. Valid SCHEME values are 'http' and
'https'. Use USER and PASSWORD if the interface is protected by basic
authentication (*note Authentication::).
When using 'https' protocol, you may need to supply the "certificate
authority" file using the '-C FILE' option, where FILE is the name of
the file in PEM format. This option can also take a directory name as
its argument. In this case all PEM files from that directory will be
loaded.
To disable peer certificate verification, use the '-k' option.
If 'pound' configuration requires the client to send its certificate
for authentication (*Note ClientCert::, or *note ClientCert
conditional::), use the '-K FILE' option to supply it. Its argument,
FILE, is the name of the file with the certificate and key in PEM
format.
10.3 Configuring 'poundctl'
===========================
Upon startup, the program checks if the file '.poundctl' exists in the
user's home directory. If so, it reads its configuration from it. The
location of the configuration file can be changed using the environment
variable 'POUNDCTL_CONF'. If it is defined and has a non-empty value,
its value is taken as the alternative file name to use. It can be
either absolute file name, or a file name relative to the home
directory. Setting 'POUNDCTL_CONF' to an empty value disables reading
the configuration.
If the program cannot determine the socket URL from '.poundctl', it
will attempt to scan 'pound' configuration file, on the assumption that
it runs on the same machine as the daemon and that its 'pound.cfg' file
contains a 'Control' statement (*note Control statement::). If so, the
socket name is determined from it.
Otherwise, the control URL has to be given explicitly using the '-s'
command line option.
The '.poundctl' file has the same syntax as 'pound.cfg': it is a
sequence of "statements" and "sections", separated by arbitrary amount
of empty lines and comments. A "simple statement" occupies a single
line and consists of a keyword ("directive") and one or more values
separated by whitespace. A "section" is a compound statement that
encloses other statements and sections. Sections begin with a keyword,
optionally followed by arguments, and end with a word 'End' on a line by
itself. All keywords are case-insensitive.
The following keywords are available in the global scope:
-- poundctl config: URL "URL"
Sets the URL of the 'pound' management socket. The value is either
the file name of the UNIX socket file, or a remote URL, as
described in *note poundctl remote::.
-- poundctl config: CAFile "FILE"
Name of the certificate authority file. See also the '-C' option,
below.
-- poundctl config: CAPath "DIR"
Read certificate authority files from the directory DIR.
-- poundctl config: ClientCert "FILE"
Supplies the name of the file with client certificate and private
key, for client authentication. See also the '-K' option, below.
-- poundctl config: Verify BOOL
Enables or disables peer certificate verification. The default is
'on'. See also the '-k' command line option.
-- poundctl config: TemplateFile "FILE"
Name of the template file (*note poundctl template::).
-- poundctl config: TemplatePath "FILE"
Search path for template files (*note poundctl template::).
-- poundctl config: TemplateName "NAME"
Name of the template to use (*note poundctl template::).
10.3.1 Multiple Servers Configuration
-------------------------------------
The 'Server' section provides a way to organize management of multiple
'pound' servers. The idea is that you define the configuration for each
particular 'pound' installation in a separate 'Server' section, and then
use the name of that section to identify the server of interest in the
command line, using the '-S' option:
poundctl -S web list
The syntax of the 'Server' section is:
Server "NAME"
...
End
where NAME is a unique name assigned to that server. It will be used as
argument to the '-S' option to identify it. The ellipsis denotes one or
more of the following statements:
-- poundctl Server: URL URL
Sets the URL of the 'pound' management socket for that server. The
value is either the file name of the UNIX socket file, or a remote
URL, as described in *note poundctl remote::.
-- poundctl Server: CAFile FILE
Name of the certificate authority file.
-- poundctl Server: CAPath DIR
Read certificate authority files from the directory DIR.
-- poundctl Server: ClientCert FILE
Supplies the name of the file with client certificate and private
key, for client authentication to that server.
-- poundctl Server: Verify BOOL
Enables or disables peer certificate verification. The default is
'on'.
10.4 'poundctl' options
=======================
The following options are understood by 'poundctl':
'-C FILE'
'-C DIR'
Read certificate authority files from FILE or from files in DIR.
*Note poundctl remote::. This overrides the 'CAFile' or 'CAPath'
configuration settings (*note poundctl config::).
'-f FILE'
Read 'pound' configuration from FILE, instead of the default
configuration file.
'-i N'
Sets indentation level for JSON output to N columns.
'-j'
Use JSON output format.
'-K FILE'
Read client certificate and private key from FILE. *Note poundctl
remote::. This option overrides the 'ClientCert' configuration
setting (*note poundctl config::).
'-k'
Disable peer certificate verification. *Note poundctl remote::.
This overrides the 'Verify' configuration setting (*note poundctl
config::).
'-h'
Shows a short help output and exits.
'-S NAME'
Operate on server defined by 'Section "NAME"' in the '.poundctl'
file. *Note multiple servers::, for a detailed discussion.
'-s SOCKET'
'-s URL'
Sets pathname of the control socket, or its URL (for remote access,
*note poundctl remote::). This overrides the 'URL' configuration
setting (*note poundctl config::).
'-T FILE'
Sets the name of the template file to use. Overrides the
'TemplateFile' configuration setting (*note poundctl config::).
'-t NAME'
Defines the name of the template to use, instead of the 'default'.
This overrides the 'TemplateName' configuration setting (*note
poundctl config::).
'-V'
Prints program version, compilation settings, and exits.
'-v'
Increases output verbosity level.
10.5 'poundctl' template
========================
Information received from the 'pound' daemon is formatted as a JSON
object. To produce human-readable output, 'poundctl' uses a "template",
i.e. a text written in a domain-specific language expressly designed
for that purpose. The template language complies, in general, with the
specification in <https://pkg.go.dev/text/template>. *Note Template
syntax::, for a detailed description.
Templates are stored in template files, which are looked up in the
template search path. The path is a column-delimited list of
directories or file names. To locate the template file, the path is
scanned left-to right. If an element is a regular file name (or a hard
or symbolic link to a regular file), 'poundctl' tries to open that file.
If an element is a directory name, the program tries to open the file
'poundctl.tmpl' in that directory. If opening succeeds, further
scanning stops and templates are read from that file.
The default template path is
~/.poundctl.tmpl:DATADIR/pound
where DATADIR stands for the program data directory(1). That is, the
file '.poundctl.tmpl' in the user home directory is searched first, then
the file 'poundctl.tmpl' (without the leading dot) is looked up in the
program data directory.
The default search path can be changed in the configuration file,
using the 'TemplatePath' statement (*note poundctl config::), or by
setting the environment variable 'POUND_TMPL_PATH'.
To examine the default value of the search path, use the '-V' command
line option.
The template file to use can be requested from the command line using
the '-t' option (or 'TemplateFile' configuration setting). In this
case, template search path in not searched and the supplied file is used
verbatim.
Unless instructed otherwise, 'poundctl' uses the template 'default'.
You can request another template name using the 'TemplateName'
configuration setting or the '-T' command line option.
The default 'poundctl.tmpl' file defines two templates: 'default' and
'xml'.
---------- Footnotes ----------
(1) It is determined at compile time. Normally it is
'/usr/share/pound' or '/usr/local/share/pound'.
10.5.1 Template syntax
----------------------
The syntax of 'poundctl' templates is modelled after and mostly
conforming to the specifications of the 'golang' template module(1).
Templates are executed by applying them to a JSON object.
Annotations in a template refer to attributes of the object to control
execution and derive values to be displayed. Execution of the template
walks the structure and sets the cursor, represented by a period (called
"dot"), to the value at the current location in the object as execution
proceeds.
The input text for a template is as ASCII text is arbitrary format.
Actions (data evaluations or control structures) are delimited by
'{{' and '}}'; all text outside actions is copied to the output
verbatim.
To aid in formatting template source code, if '{{' is followed
immediately by a minus sign and white space, all trailing white space is
trimmed from the immediately preceding text. Similarly, if '}}' is
preceded by white space and a minus sign, all leading white space is
trimmed from the immediately following text. Notice that the presence
of the whitespace in these trim markers is mandatory: '{{- 3}}' trims
the immediately preceding text and outputs '3', while "'{{-3}}' parses
as an action containing the number '-3'.
---------- Footnotes ----------
(1) <https://pkg.go.dev/text/template>
10.5.1.1 Actions
................
Here is the list of actions. "Arguments" and "pipelines" are
evaluations of data, defined in detail in the sections that follow.
'{{ }}'
Empty action is discarded. It may be useful to trim the preceding
or following whitespace, as in
{{- -}}
'{{/* a comment */}}'
Comments are discarded. They may span multiple lines of text.
Comments do not nest and must start immediately after the opening
delimiter (with optional dash and whitespace in between). A
comment may be followed by any action described below.
Comments may be used to control trailing and leading whitespace as
well:
{{- a comment trimming the surrounding whitespace -}}
'{{ PIPELINE }}'
The PIPELINE is evaluated, and the default textual representation
of its value is copied to the output.
'{{if PIPELINE }} T1 {{end}}'
If the value of the PIPELINE is empty, no output is generated;
otherwise, T1 is executed. The empty values are 'null', 'false',
numeric 0, empty string ('""'), array ('[]'), or object ('{}').
Dot is unaffected.
'{{if PIPELINE }} T1 {{else}} T0 {{end}}'
If the value of the pipeline is empty, T0 is executed; otherwise,
T1 is executed. Dot is unaffected.
'{{if PIPELINE }} T1 {{else if PIPELINE }} T2 {{else}} T0 {{end}}'
A shortcut to simplify writing the if-else chains. Equivalent to
(newlines added for readability):
{{if PIPELINE }}
T1
{{else -}}
{{if PIPELINE }}
T2
{{else}}
T0
{{end}}
{{end}}
'{{range PIPELINE }} T1 {{end}}'
The value of PIPELINE must be an object or array. If it is of
length zero, nothing is output. Otherwise, dot is set to the
successive elements of the array or object and T1 is executed. For
objects, the elements will be visited in sorted key order.
'{{range PIPELINE }} T1 {{else}} T0 {{end}}'
Same as above, except that if the value of the PIPELINE is of
length zero, T0 is executed with dot unaffected.
Within the '{{range}}' action, the following two keywords may
appear:
'{{break}}'
The innermost '{{range PIPELINE}}' loop is ended early,
stopping the current iteration and bypassing all remaining
iterations.
'{{continue}}'
The current iteration of the innermost '{{range PIPELINE}}'
loop is stopped, and the loop starts the next iteration.
'{{define "NAME"}} TEXT {{end}}'
The TEXT is collected and stored for the further use as template
with the given NAME. It can be invoked using the '{{template}}'
action (see below).
'{{template "NAME"}}'
The template with the specified NAME (see the '{{define}}' above)
is executed with dot set to 'null'.
'{{template "NAME" VALUE }}'
The template with the specified NAME (see the '{{define}}' above)
is executed with dot set to VALUE.
'{{block "NAME" PIPELINE }} T1 {{end}}'
A block is shorthand for defining a template and then executing it
in place:
{{define "NAME"}} T1 {{end}}
{{template "NAME" PIPELINE}}
'{{with PIPELINE }} T1 {{end}}'
If the value of the PIPELINE is empty, no output is generated;
otherwise, dot is set to the value of the PIPELINE and T1 is
executed.
'{{with PIPELINE }} T1 {{else}} T0 {{end}}'
Same as above, but if the value of the PIPELINE is empty, T0 is
executed with dot unchanged.
10.5.1.2 Arguments
..................
An "argument" is a simple value, i.e. any of the following:
* Numeric value (integer or floating point)
* Boolean value: 'true' or 'false'.
* Quoted string.
* A dot ('.') This represents the cursor value.
* Attribute: '.ATTR' This is the value of the attribute ATTR in the
current value (dot). Attribute references can be nested, as in
'.Attr.Xattr.Yattr'.
* A variable reference: '$VAR'. Here, VAR is the name of the
variable defined in the 'range' action. *Note Variables::, below.
* Function call in parentheses, for grouping.
10.5.2 Pipelines
----------------
A "pipeline" is a series of one or more "commands" delimited by pipe
sign ('|'). Each "command" is either an argument or a "function call",
in form:
FUNC ARG1 ARG2...
where FUNC is the name of one of the built-in functions discussed below.
Pipelines are executed from left to right, with the result of the
previous command implicitly added to the list of arguments of each
subsequent command. For example, the pipeline
.attr | eq $x
is equivalent to
eq $x .attr
i.e. it calls the built-in function 'eq' with two arguments: the value
of the variable 'x' and attribute 'attr' of the cursor value.
The following built-in functions are defined:
-- Template built-in: and A1 A2
Evaluates to 'true' if pipelines A1 and A2 both evaluate to 'true'.
Notice, that there is no boolean shortcut evaluation: both
pipelines are evaluated prior to calling 'and'.
-- Template built-in: or A1 A2
Evaluates to 'true' if at least one of the pipelines A1 and A2
evaluates to 'true'. Notice, that there is no boolean shortcut
evaluation: both pipelines are evaluated prior to calling 'or'.
-- Template built-in: index A1 A2...
Returns the result of indexing its first argument by the following
arguments. Thus, if '.' is an array, then:
index . 5
evaluates to its fifth element ('.[5]').
-- Template built-in: len A1
Returns the integer length of its argument.
-- Template built-in: not A1
Returns 'true' if its argument evaluates to 'false'.
-- Template built-in: eq A1 A2
Returns 'true' if both its arguments are equal. This applies only
if both A1 and A2 are numeric or if they both are strings.
-- Template built-in: ne A1 A2
Returns 'true' if its arguments (both must be numeric or strings)
are not equal.
-- Template built-in: lt A1 A2
Returns 'true' if A1 is numerically less than A2.
-- Template built-in: le A1 A2
Returns 'true' if A1 is numerically less than or equal to A2.
-- Template built-in: gt A1 A2
Returns 'true' if A1 is numerically greater than A2.
-- Template built-in: ge A1 A2
Returns 'true' if A1 is numerically greater than or equal to A2.
-- Template built-in: even A1
Returns 'true' if A1, which must evaluate to an integer value, is
divisible by 2.
-- Template built-in: printf FMT A1...
Implements the 'printf' function. FMT must evaluate to string.
Rest of arguments is interpreted according to the conversion
specifications in FMT. The result is a formatted string.
In addition to the standard conversion specifications, the '%v'
specifier is implemented: it formats its argument in the best way,
depending on its actual type.
-- Template built-in: typeof A1
Evaluates to the type of its argument, one of: 'null', 'bool',
'number', 'integer', 'string', 'array', and 'object'.
-- Template built-in: exists A1 A2
A1 must evaluate to an object and A2 to string. The function
evaluates to 'true' if the attribute A2 is present in A1.
-- Template built-in: add A1 A2...
Returns the sum of its arguments.
-- Template built-in: sub A1 A2
Returns the difference 'A1 - A2'.
-- Template built-in: mul A1 A2
Multiplies A1 by A2.
-- Template built-in: div A1 A2
Divides A1 by A2.
10.5.3 Variables
----------------
Variables (referred to as '$NAME') can be defined in 'range' and 'with'
actions. For 'range', the syntax is:
{{range $INDEX, $ELEMENT = PIPELINE }} T1 {{end}}
where INDEX and ELEMENT are arbitrary variable names. When executing
this action, during each iteration $INDEX and $ELEMENT are set to the
index (attribute name) and value of each successive element. Dot
remains unaffected.
For 'with', the syntax is:
{{with $VAR = PIPELINE }} T1 {{end}}
PIPELINE is evaluated, its result is assigned to $VAR and the T1
block is executed with dot unchanged.
A variable's scope extends to the 'end' action of the control
structure ('with' or 'range') in which it is declared. This includes
any nested statements that may appear in between.
10.5.4 Input object
-------------------
Depending on the request issued by 'poundctl', the invoked template can
receive as its argument ("dot") an object of the following types: "full
listing", "listener", "service", or "backend".
Since there is no explicit indication of the object type being
passed, templates normally use heuristics based on the presence or
absence of certain attribute to deduce the object type in question. The
recommended approach is described in the following pseudo-code fragment:
{{if exists . "listeners" }}
{{/* This is a full listing, as requested by poundctl list. */}}
...
{{else if exists . "services"}}
{{/* Single listener, as requested by poundctl list /L.
Notice that this attribute is present in the full listing as
well, so presence of "listeners" should be checked first. */}}
...
{{else if exists . "backends"}}
{{/* Single service, as requested by poundctl list /L/S. */}}
...
{{else}}
{{/* Backend listing (poundctl list /L/I/B) */}}
...
{{end}}
Structures of each object are discussed in subsections that follow.
10.5.4.1 Full listing
.....................
A full listing contains the following attributes:
'listeners'
An array of "listener" objects. See below for a description.
'services'
An array of "service" objects, representing services defined in the
global scope of the 'pound' configuration file.
'pid'
PID of the running 'pound' daemon.
'version'
'Pound' version number (string).
'workers'
Workers statistics. This is a JSON object with the following
attributes:
'active'
Number of active threads.
'count'
Number of threads currently running.
'max'
Maximum number of threads.
'min'
Minimum number of threads.
'timeout'
Thread idle timeout.
'queue_len'
Number of incoming HTTP requests in the queue (integer).
'timestamp'
Current time on the server, formatted as ISO 8601 date-time with
microsecond precision, e.g.: '2023-01-05T22:43:18.071559'.
10.5.4.2 Listener
.................
A "listener" object represents a single HTTP or HTTPS listener in
'pound' configuration. It has the following attributes:
'address'
Address of this listener. A string formatted as 'IP:PORT'. for
IPv4 and IPv6 addresses or containing a socket file name, for UNIX
sockets.
'protocol'
Protocol used: either 'http' or 'https'.
'services'
Array of "service" objects representing services defined in this
listener. See below for the definition of a "service" object.
'enabled'
Boolean. Whether this listener is enabled or not.
'nohttps11'
Value of the 'NoHTTPS11' configuration statement for this listener
(*note NoHTTPS11: ListenHTTPS.). One of: 0, 1, 2.
10.5.4.3 Service
................
A "service" object describes a single service.
'name'
Symbolic name of this service.
'enabled'
Boolean. Whether this service is enabled or not.
'session_type'
Name of the session handling algorithm for this service. One of:
'IP', 'BASIC', 'URL', 'PARM', 'COOKIE', 'HEADER'.
'sessions'
List of active sessions in this service. Each session is
represented as object with the following attributes:
'key'
Session key (string).
'backend'
Ordinal number of the backend assigned to handle requests with
this session.
'expire'
Expiration time of this session, formatted as
'1970-01-01T00:00:00.000000' (with microsecond precision).
'backends'
List of "backends" defined for this service.
'emergency'
Emergency "backend" object, or 'null' if no such backend is
defined.
10.5.4.4 Backend
................
The following attributes are always present in each "backend" object:
'alive'
Whether or not this backend is alive.
'conn_to'
Connection timeout for this backend (seconds).
'enabled'
Whether or not this backend is enabled.
'io_to'
I/O timeout for this backend (seconds).
'priority'
Priority value assigned to this backend.
'protocol'
Protocol used by this backend: either 'http' or 'https'.
'type'
Backend type. One of: 'acme', 'backend', 'control', 'redirect'.
'ws_to'
Websocket timeout (seconds).
Depending on the backend type, the following attributes may be
present:
'acme'
An object of the following structure:
'path'
Directory where ACME challenges are stored.
'backend'
Object:
'address'
Backend address.
'redirect'
Object:
'url'
URL to redirect to.
'code'
HTTP code for redirection responses. One of: 301, 302, 307.
'redir_req'
Boolean: whether to append the original request path to the
resulting location.
If backend statistics is enabled (*note BackendStats::), the 'stats'
object will be present, with the following attributes:
'request_count'
Total number of requests processed by this backend.
'request_time_avg'
Average time per request, in nanoseconds.
'request_time_stddev'
Standard deviation of the above.
Appendix A Metric Families
**************************
This appendix describes metric families returned in the output of
"openmetrics" 'pound' backends (*note Metrics::).
-- Metric family: gauge pound_workers
Number of pound workers (*note Worker model::). Indexed by types:
'active'
Number of workers currently active.
'count'
Number of workers running (both idle and active).
'min'
Minimum number of workers as set by the 'WorkerMinCount'
configuration directive (*note WorkerMinCount: Global
directives.).
'max'
Maximum number of workers as set by the 'WorkerMaxCount'
configuration directive (*note WorkerMaxCount: Global
directives.).
Example:
pound_workers{type="active"} 2
pound_workers{type="count"} 5
pound_workers{type="max"} 128
pound_workers{type="min"} 5
-- Metric family: stateset pound_listener_enabled
State of a listener: enabled/disabled. Indexed by the listener
ordinal number.
pound_listener_enabled{listener="0"} 1
pound_listener_enabled{listener="1"} 0
pound_listener_enabled{listener="2"} 1
-- Metric family: info pound_listener_info
Description of a listener. Each instance contains the following
indices:
'listener'
Listener ordinal number.
'name'
Listener name, as set in the 'ListenHTTP' or 'ListenHTTPS'
statement (*note ListenHTTP::).
'address'
Listener address. For INET family, it is formatted as
'IP:PORT', for UNIX sockets, it is the pathname of the socket.
'protocol'
Either 'http' or 'https'.
The value of this metrics is always '1'.
pound_listener_info{listener="0",name="",address="/run/pound.sock",protocol="http"} 1
pound_listener_info{listener="1",name="plain",address="0.0.0.0:80",protocol="http"} 1
pound_listener_info{listener="2",name="tls",address="0.0.0.0:443",protocol="https"} 1
-- Metric family: info pound_service_info
Description of a service. Indices:
'listener'
Listener ordinal number. This index is absent for globally
defined services.
'service'
Index of the service in listener (or in global configuration,
for globally defined services).
'name'
Service name as set in the 'Service' definition (*note
Service::).
pound_service_info{listener="0",service="0",name=""} 1
pound_service_info{listener="1",service="0",name=""} 1
pound_service_info{listener="1",service="1",name="redirect"} 1
pound_service_info{listener="2",service="0",name="metrics"} 1
pound_service_info{listener="2",service="1",name="web"} 1
pound_service_info{service="0",name="fallback"} 1
-- Metric family: stateset pound_service_enabled
State of a particular service.
pound_service_enabled{listener="0",service="0"} 1
pound_service_enabled{listener="1",service="0"} 1
pound_service_enabled{listener="2",service="0"} 1
pound_service_enabled{service="0"} 1
-- Metric family: gauge pound_backends
Number of backends per service: total, alive, enabled, and active
(both alive and enabled). Indices:
'listener'
Listener ordinal number. This index is absent for globally
defined services.
'service'
Index of the service in listener (or in global configuration,
for globally defined services).
'state'
Backend state: 'total', 'alive', 'enabled', or 'active'.
Example:
pound_backends{listener="0",service="0",state="total"} 5
pound_backends{listener="0",service="0",state="enabled"} 3
pound_backends{listener="0",service="0",state="alive"} 3
pound_backends{service="0",state="total"} 1
pound_backends{service="0",state="enabled"} 1
pound_backends{service="0",state="alive"} 1
-- Metric family: stateset pound_backend_state
State of each backend. Indices:
'listener'
Listener ordinal number. This index is absent for globally
defined services.
'service'
Index of the service in listener (or in global configuration,
for globally defined services).
'backend'
Index of the backend in service.
'state'
'enabled': whether the backend is enabled or not.
'alive': whether the backend is alive or not.
Example:
pound_backend_state{listener="0",service="0",backend="0",state="alive"} 1
pound_backend_state{listener="0",service="0",backend="0",state="enabled"} 1
pound_backend_state{listener="0",service="0",backend="1",state="alive"} 1
pound_backend_state{listener="0",service="0",backend="1",state="enabled"} 0
-- Metric family: gauge pound_backend_requests
Number of requests processed by backend. This metrics is available
only if backend statistics is enabled (*note BackendStats::).
Example:
pound_backend_requests{listener="0",service="0",backend="0"} 40587
pound_backend_requests{listener="1",service="0",backend="0"} 13858
-- Metric family: gauge pound_backend_request_time_avg_nanoseconds
Average time per request spent in backend (nanoseconds). This
metrics is available only if backend statistics is enabled (*note
BackendStats::).
pound_backend_request_time_avg_nanoseconds{listener="0",service="0",backend="0"} 156254
pound_backend_request_time_avg_nanoseconds{listener="1",service="2",backend="0"} 26147
-- Metric family: gauge pound_backend_request_stddev_nanoseconds
Standard deviation of the average time per request. This metrics
is available only if backend statistics is enabled (*note
BackendStats::).
pound_backend_request_stddev_nanoseconds{listener="0",service="0",backend="0"} 0
pound_backend_request_stddev_nanoseconds{listener="1",service="2",backend="0"} 59
Appendix B Time and Date Formats
********************************
This appendix documents the time format specifications understood by the
'%{FORMAT}t' log format conversion. Essentially, it is a reproduction
of the man page for GNU 'strftime' function.
Ordinary characters placed in the format string are reproduced
without conversion. Conversion specifiers are introduced by a '%'
character, and are replaced as follows:
%a The abbreviated weekday name according to the
current locale.
%A The full weekday name according to the current
locale.
%b The abbreviated month name according to the
current locale.
%B The full month name according to the current
locale.
%c The preferred date and time representation for
the current locale.
%C The century number (year/100) as a 2-digit
integer.
%d The day of the month as a decimal number (range
01 to 31).
%D Equivalent to '%m/%d/%y'.
%e Like '%d', the day of the month as a decimal
number, but a leading zero is replaced by a
space.
%E Modifier: use alternative format, see below
(*note conversion specs::).
%F Equivalent to '%Y-%m-%d' (the ISO 8601 date
format).
%G The ISO 8601 year with century as a decimal
number. The 4-digit year corresponding to the
ISO week number (see '%V'). This has the same
format and value as '%y', except that if the ISO
week number belongs to the previous or next
year, that year is used instead.
%g Like '%G', but without century, i.e., with a
2-digit year (00-99).
%h Equivalent to '%b'.
%H The hour as a decimal number using a 24-hour
clock (range 00 to 23).
%I The hour as a decimal number using a 12-hour
clock (range 01 to 12).
%j The day of the year as a decimal number (range
001 to 366).
%k The hour (24-hour clock) as a decimal number
(range 0 to 23); single digits are preceded by a
blank. (See also '%H'.)
%l The hour (12-hour clock) as a decimal number
(range 1 to 12); single digits are preceded by a
blank. (See also '%I'.)
%m The month as a decimal number (range 01 to 12).
%M The minute as a decimal number (range 00 to 59).
%n A newline character.
%O Modifier: use alternative format, see below
(*note conversion specs::).
%p Either 'AM' or 'PM' according to the given time
value, or the corresponding strings for the
current locale. Noon is treated as 'pm' and
midnight as 'am'.
%P Like '%p' but in lowercase: 'am' or 'pm' or a
corresponding string for the current locale.
%r The time in 'a.m.' or 'p.m.' notation. In the
POSIX locale this is equivalent to '%I:%M:%S
%p'.
%R The time in 24-hour notation ('%H:%M'). For a
version including the seconds, see '%T' below.
%s The number of seconds since the Epoch, i.e.,
since 1970-01-01 00:00:00 UTC.
%S The second as a decimal number (range 00 to 61).
%t A tab character.
%T The time in 24-hour notation ('%H:%M:%S').
%u The day of the week as a decimal, range 1 to 7,
Monday being 1. See also '%w'.
%U The week number of the current year as a decimal
number, range 00 to 53, starting with the first
Sunday as the first day of week 01. See also
'%V' and '%W'.
%V The ISO 8601:1988 week number of the current
year as a decimal number, range 01 to 53, where
week 1 is the first week that has at least 4
days in the current year, and with Monday as the
first day of the week. See also '%U' and '%W'.
%w The day of the week as a decimal, range 0 to 6,
Sunday being 0. See also '%u'.
%W The week number of the current year as a decimal
number, range 00 to 53, starting with the first
Monday as the first day of week 01.
%x The preferred date representation for the
current locale without the time.
%X The preferred time representation for the
current locale without the date.
%y The year as a decimal number without a century
(range 00 to 99).
%Y The year as a decimal number including the
century.
%z The time-zone as hour offset from GMT. Required
to emit RFC822-conformant dates (using '%a, %d
%b %Y %H:%M:%S %z')
%Z The time zone or name or abbreviation.
%+ The date and time in 'date(1)' format.
%% A literal '%' character.
Some conversion specifiers can be modified by preceding them by the
'E' or 'O' modifier to indicate that an alternative format should be
used. If the alternative format or specification does not exist for the
current locale, the behaviour will be as if the unmodified conversion
specification were used. The Single Unix Specification mentions '%Ec',
'%EC', '%Ex', '%EX', '%Ry', '%EY', '%Od', '%Oe', '%OH', '%OI', '%Om',
'%OM', '%OS', '%Ou', '%OU', '%OV', '%Ow', '%OW', '%Oy', where the effect
of the 'O' modifier is to use alternative numeric symbols (say, roman
numerals), and that of the 'E' modifier is to use a locale-dependent
alternative representation.
Appendix C GNU Free Documentation License
*****************************************
Version 1.3, 3 November 2008
Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
<https://fsf.org/>
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
0. PREAMBLE
The purpose of this License is to make a manual, textbook, or other
functional and useful document "free" in the sense of freedom: to
assure everyone the effective freedom to copy and redistribute it,
with or without modifying it, either commercially or
noncommercially. Secondarily, this License preserves for the
author and publisher a way to get credit for their work, while not
being considered responsible for modifications made by others.
This License is a kind of "copyleft", which means that derivative
works of the document must themselves be free in the same sense.
It complements the GNU General Public License, which is a copyleft
license designed for free software.
We have designed this License in order to use it for manuals for
free software, because free software needs free documentation: a
free program should come with manuals providing the same freedoms
that the software does. But this License is not limited to
software manuals; it can be used for any textual work, regardless
of subject matter or whether it is published as a printed book. We
recommend this License principally for works whose purpose is
instruction or reference.
1. APPLICABILITY AND DEFINITIONS
This License applies to any manual or other work, in any medium,
that contains a notice placed by the copyright holder saying it can
be distributed under the terms of this License. Such a notice
grants a world-wide, royalty-free license, unlimited in duration,
to use that work under the conditions stated herein. The
"Document", below, refers to any such manual or work. Any member
of the public is a licensee, and is addressed as "you". You accept
the license if you copy, modify or distribute the work in a way
requiring permission under copyright law.
A "Modified Version" of the Document means any work containing the
Document or a portion of it, either copied verbatim, or with
modifications and/or translated into another language.
A "Secondary Section" is a named appendix or a front-matter section
of the Document that deals exclusively with the relationship of the
publishers or authors of the Document to the Document's overall
subject (or to related matters) and contains nothing that could
fall directly within that overall subject. (Thus, if the Document
is in part a textbook of mathematics, a Secondary Section may not
explain any mathematics.) The relationship could be a matter of
historical connection with the subject or with related matters, or
of legal, commercial, philosophical, ethical or political position
regarding them.
The "Invariant Sections" are certain Secondary Sections whose
titles are designated, as being those of Invariant Sections, in the
notice that says that the Document is released under this License.
If a section does not fit the above definition of Secondary then it
is not allowed to be designated as Invariant. The Document may
contain zero Invariant Sections. If the Document does not identify
any Invariant Sections then there are none.
The "Cover Texts" are certain short passages of text that are
listed, as Front-Cover Texts or Back-Cover Texts, in the notice
that says that the Document is released under this License. A
Front-Cover Text may be at most 5 words, and a Back-Cover Text may
be at most 25 words.
A "Transparent" copy of the Document means a machine-readable copy,
represented in a format whose specification is available to the
general public, that is suitable for revising the document
straightforwardly with generic text editors or (for images composed
of pixels) generic paint programs or (for drawings) some widely
available drawing editor, and that is suitable for input to text
formatters or for automatic translation to a variety of formats
suitable for input to text formatters. A copy made in an otherwise
Transparent file format whose markup, or absence of markup, has
been arranged to thwart or discourage subsequent modification by
readers is not Transparent. An image format is not Transparent if
used for any substantial amount of text. A copy that is not
"Transparent" is called "Opaque".
Examples of suitable formats for Transparent copies include plain
ASCII without markup, Texinfo input format, LaTeX input format,
SGML or XML using a publicly available DTD, and standard-conforming
simple HTML, PostScript or PDF designed for human modification.
Examples of transparent image formats include PNG, XCF and JPG.
Opaque formats include proprietary formats that can be read and
edited only by proprietary word processors, SGML or XML for which
the DTD and/or processing tools are not generally available, and
the machine-generated HTML, PostScript or PDF produced by some word
processors for output purposes only.
The "Title Page" means, for a printed book, the title page itself,
plus such following pages as are needed to hold, legibly, the
material this License requires to appear in the title page. For
works in formats which do not have any title page as such, "Title
Page" means the text near the most prominent appearance of the
work's title, preceding the beginning of the body of the text.
The "publisher" means any person or entity that distributes copies
of the Document to the public.
A section "Entitled XYZ" means a named subunit of the Document
whose title either is precisely XYZ or contains XYZ in parentheses
following text that translates XYZ in another language. (Here XYZ
stands for a specific section name mentioned below, such as
"Acknowledgements", "Dedications", "Endorsements", or "History".)
To "Preserve the Title" of such a section when you modify the
Document means that it remains a section "Entitled XYZ" according
to this definition.
The Document may include Warranty Disclaimers next to the notice
which states that this License applies to the Document. These
Warranty Disclaimers are considered to be included by reference in
this License, but only as regards disclaiming warranties: any other
implication that these Warranty Disclaimers may have is void and
has no effect on the meaning of this License.
2. VERBATIM COPYING
You may copy and distribute the Document in any medium, either
commercially or noncommercially, provided that this License, the
copyright notices, and the license notice saying this License
applies to the Document are reproduced in all copies, and that you
add no other conditions whatsoever to those of this License. You
may not use technical measures to obstruct or control the reading
or further copying of the copies you make or distribute. However,
you may accept compensation in exchange for copies. If you
distribute a large enough number of copies you must also follow the
conditions in section 3.
You may also lend copies, under the same conditions stated above,
and you may publicly display copies.
3. COPYING IN QUANTITY
If you publish printed copies (or copies in media that commonly
have printed covers) of the Document, numbering more than 100, and
the Document's license notice requires Cover Texts, you must
enclose the copies in covers that carry, clearly and legibly, all
these Cover Texts: Front-Cover Texts on the front cover, and
Back-Cover Texts on the back cover. Both covers must also clearly
and legibly identify you as the publisher of these copies. The
front cover must present the full title with all words of the title
equally prominent and visible. You may add other material on the
covers in addition. Copying with changes limited to the covers, as
long as they preserve the title of the Document and satisfy these
conditions, can be treated as verbatim copying in other respects.
If the required texts for either cover are too voluminous to fit
legibly, you should put the first ones listed (as many as fit
reasonably) on the actual cover, and continue the rest onto
adjacent pages.
If you publish or distribute Opaque copies of the Document
numbering more than 100, you must either include a machine-readable
Transparent copy along with each Opaque copy, or state in or with
each Opaque copy a computer-network location from which the general
network-using public has access to download using public-standard
network protocols a complete Transparent copy of the Document, free
of added material. If you use the latter option, you must take
reasonably prudent steps, when you begin distribution of Opaque
copies in quantity, to ensure that this Transparent copy will
remain thus accessible at the stated location until at least one
year after the last time you distribute an Opaque copy (directly or
through your agents or retailers) of that edition to the public.
It is requested, but not required, that you contact the authors of
the Document well before redistributing any large number of copies,
to give them a chance to provide you with an updated version of the
Document.
4. MODIFICATIONS
You may copy and distribute a Modified Version of the Document
under the conditions of sections 2 and 3 above, provided that you
release the Modified Version under precisely this License, with the
Modified Version filling the role of the Document, thus licensing
distribution and modification of the Modified Version to whoever
possesses a copy of it. In addition, you must do these things in
the Modified Version:
A. Use in the Title Page (and on the covers, if any) a title
distinct from that of the Document, and from those of previous
versions (which should, if there were any, be listed in the
History section of the Document). You may use the same title
as a previous version if the original publisher of that
version gives permission.
B. List on the Title Page, as authors, one or more persons or
entities responsible for authorship of the modifications in
the Modified Version, together with at least five of the
principal authors of the Document (all of its principal
authors, if it has fewer than five), unless they release you
from this requirement.
C. State on the Title page the name of the publisher of the
Modified Version, as the publisher.
D. Preserve all the copyright notices of the Document.
E. Add an appropriate copyright notice for your modifications
adjacent to the other copyright notices.
F. Include, immediately after the copyright notices, a license
notice giving the public permission to use the Modified
Version under the terms of this License, in the form shown in
the Addendum below.
G. Preserve in that license notice the full lists of Invariant
Sections and required Cover Texts given in the Document's
license notice.
H. Include an unaltered copy of this License.
I. Preserve the section Entitled "History", Preserve its Title,
and add to it an item stating at least the title, year, new
authors, and publisher of the Modified Version as given on the
Title Page. If there is no section Entitled "History" in the
Document, create one stating the title, year, authors, and
publisher of the Document as given on its Title Page, then add
an item describing the Modified Version as stated in the
previous sentence.
J. Preserve the network location, if any, given in the Document
for public access to a Transparent copy of the Document, and
likewise the network locations given in the Document for
previous versions it was based on. These may be placed in the
"History" section. You may omit a network location for a work
that was published at least four years before the Document
itself, or if the original publisher of the version it refers
to gives permission.
K. For any section Entitled "Acknowledgements" or "Dedications",
Preserve the Title of the section, and preserve in the section
all the substance and tone of each of the contributor
acknowledgements and/or dedications given therein.
L. Preserve all the Invariant Sections of the Document, unaltered
in their text and in their titles. Section numbers or the
equivalent are not considered part of the section titles.
M. Delete any section Entitled "Endorsements". Such a section
may not be included in the Modified Version.
N. Do not retitle any existing section to be Entitled
"Endorsements" or to conflict in title with any Invariant
Section.
O. Preserve any Warranty Disclaimers.
If the Modified Version includes new front-matter sections or
appendices that qualify as Secondary Sections and contain no
material copied from the Document, you may at your option designate
some or all of these sections as invariant. To do this, add their
titles to the list of Invariant Sections in the Modified Version's
license notice. These titles must be distinct from any other
section titles.
You may add a section Entitled "Endorsements", provided it contains
nothing but endorsements of your Modified Version by various
parties--for example, statements of peer review or that the text
has been approved by an organization as the authoritative
definition of a standard.
You may add a passage of up to five words as a Front-Cover Text,
and a passage of up to 25 words as a Back-Cover Text, to the end of
the list of Cover Texts in the Modified Version. Only one passage
of Front-Cover Text and one of Back-Cover Text may be added by (or
through arrangements made by) any one entity. If the Document
already includes a cover text for the same cover, previously added
by you or by arrangement made by the same entity you are acting on
behalf of, you may not add another; but you may replace the old
one, on explicit permission from the previous publisher that added
the old one.
The author(s) and publisher(s) of the Document do not by this
License give permission to use their names for publicity for or to
assert or imply endorsement of any Modified Version.
5. COMBINING DOCUMENTS
You may combine the Document with other documents released under
this License, under the terms defined in section 4 above for
modified versions, provided that you include in the combination all
of the Invariant Sections of all of the original documents,
unmodified, and list them all as Invariant Sections of your
combined work in its license notice, and that you preserve all
their Warranty Disclaimers.
The combined work need only contain one copy of this License, and
multiple identical Invariant Sections may be replaced with a single
copy. If there are multiple Invariant Sections with the same name
but different contents, make the title of each such section unique
by adding at the end of it, in parentheses, the name of the
original author or publisher of that section if known, or else a
unique number. Make the same adjustment to the section titles in
the list of Invariant Sections in the license notice of the
combined work.
In the combination, you must combine any sections Entitled
"History" in the various original documents, forming one section
Entitled "History"; likewise combine any sections Entitled
"Acknowledgements", and any sections Entitled "Dedications". You
must delete all sections Entitled "Endorsements."
6. COLLECTIONS OF DOCUMENTS
You may make a collection consisting of the Document and other
documents released under this License, and replace the individual
copies of this License in the various documents with a single copy
that is included in the collection, provided that you follow the
rules of this License for verbatim copying of each of the documents
in all other respects.
You may extract a single document from such a collection, and
distribute it individually under this License, provided you insert
a copy of this License into the extracted document, and follow this
License in all other respects regarding verbatim copying of that
document.
7. AGGREGATION WITH INDEPENDENT WORKS
A compilation of the Document or its derivatives with other
separate and independent documents or works, in or on a volume of a
storage or distribution medium, is called an "aggregate" if the
copyright resulting from the compilation is not used to limit the
legal rights of the compilation's users beyond what the individual
works permit. When the Document is included in an aggregate, this
License does not apply to the other works in the aggregate which
are not themselves derivative works of the Document.
If the Cover Text requirement of section 3 is applicable to these
copies of the Document, then if the Document is less than one half
of the entire aggregate, the Document's Cover Texts may be placed
on covers that bracket the Document within the aggregate, or the
electronic equivalent of covers if the Document is in electronic
form. Otherwise they must appear on printed covers that bracket
the whole aggregate.
8. TRANSLATION
Translation is considered a kind of modification, so you may
distribute translations of the Document under the terms of section
4. Replacing Invariant Sections with translations requires special
permission from their copyright holders, but you may include
translations of some or all Invariant Sections in addition to the
original versions of these Invariant Sections. You may include a
translation of this License, and all the license notices in the
Document, and any Warranty Disclaimers, provided that you also
include the original English version of this License and the
original versions of those notices and disclaimers. In case of a
disagreement between the translation and the original version of
this License or a notice or disclaimer, the original version will
prevail.
If a section in the Document is Entitled "Acknowledgements",
"Dedications", or "History", the requirement (section 4) to
Preserve its Title (section 1) will typically require changing the
actual title.
9. TERMINATION
You may not copy, modify, sublicense, or distribute the Document
except as expressly provided under this License. Any attempt
otherwise to copy, modify, sublicense, or distribute it is void,
and will automatically terminate your rights under this License.
However, if you cease all violation of this License, then your
license from a particular copyright holder is reinstated (a)
provisionally, unless and until the copyright holder explicitly and
finally terminates your license, and (b) permanently, if the
copyright holder fails to notify you of the violation by some
reasonable means prior to 60 days after the cessation.
Moreover, your license from a particular copyright holder is
reinstated permanently if the copyright holder notifies you of the
violation by some reasonable means, this is the first time you have
received notice of violation of this License (for any work) from
that copyright holder, and you cure the violation prior to 30 days
after your receipt of the notice.
Termination of your rights under this section does not terminate
the licenses of parties who have received copies or rights from you
under this License. If your rights have been terminated and not
permanently reinstated, receipt of a copy of some or all of the
same material does not give you any rights to use it.
10. FUTURE REVISIONS OF THIS LICENSE
The Free Software Foundation may publish new, revised versions of
the GNU Free Documentation License from time to time. Such new
versions will be similar in spirit to the present version, but may
differ in detail to address new problems or concerns. See
<https://www.gnu.org/licenses/>.
Each version of the License is given a distinguishing version
number. If the Document specifies that a particular numbered
version of this License "or any later version" applies to it, you
have the option of following the terms and conditions either of
that specified version or of any later version that has been
published (not as a draft) by the Free Software Foundation. If the
Document does not specify a version number of this License, you may
choose any version ever published (not as a draft) by the Free
Software Foundation. If the Document specifies that a proxy can
decide which future versions of this License can be used, that
proxy's public statement of acceptance of a version permanently
authorizes you to choose that version for the Document.
11. RELICENSING
"Massive Multiauthor Collaboration Site" (or "MMC Site") means any
World Wide Web server that publishes copyrightable works and also
provides prominent facilities for anybody to edit those works. A
public wiki that anybody can edit is an example of such a server.
A "Massive Multiauthor Collaboration" (or "MMC") contained in the
site means any set of copyrightable works thus published on the MMC
site.
"CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0
license published by Creative Commons Corporation, a not-for-profit
corporation with a principal place of business in San Francisco,
California, as well as future copyleft versions of that license
published by that same organization.
"Incorporate" means to publish or republish a Document, in whole or
in part, as part of another Document.
An MMC is "eligible for relicensing" if it is licensed under this
License, and if all works that were first published under this
License somewhere other than this MMC, and subsequently
incorporated in whole or in part into the MMC, (1) had no cover
texts or invariant sections, and (2) were thus incorporated prior
to November 1, 2008.
The operator of an MMC Site may republish an MMC contained in the
site under CC-BY-SA on the same site at any time before August 1,
2009, provided the MMC is eligible for relicensing.
ADDENDUM: How to use this License for your documents
====================================================
To use this License in a document you have written, include a copy of
the License in the document and put the following copyright and license
notices just after the title page:
Copyright (C) YEAR YOUR NAME.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
Texts. A copy of the license is included in the section entitled ``GNU
Free Documentation License''.
If you have Invariant Sections, Front-Cover Texts and Back-Cover
Texts, replace the "with...Texts." line with this:
with the Invariant Sections being LIST THEIR TITLES, with
the Front-Cover Texts being LIST, and with the Back-Cover Texts
being LIST.
If you have Invariant Sections without Cover Texts, or some other
combination of the three, merge those two alternatives to suit the
situation.
If your document contains nontrivial examples of program code, we
recommend releasing these examples in parallel under your choice of free
software license, such as the GNU General Public License, to permit
their use in free software.
Index
*****
* Menu:
* %%: Logging. (line 1618)
* %>s: Logging. (line 1727)
* %a: Logging. (line 1621)
* %A: Logging. (line 1665)
* %B: Logging. (line 1668)
* %b: Logging. (line 1671)
* %D: Logging. (line 1675)
* %h: Logging. (line 1678)
* %H: Logging. (line 1681)
* %m: Logging. (line 1707)
* %P: Logging. (line 1714)
* %q: Logging. (line 1717)
* %r: Logging. (line 1721)
* %s: Logging. (line 1724)
* %t: Logging. (line 1730)
* %T: Logging. (line 1754)
* %u: Logging. (line 1764)
* %U: Logging. (line 1767)
* %v: Logging. (line 1771)
* %{FORMAT}t: Logging. (line 1734)
* %{HDR}i: Logging. (line 1684)
* %{HDR}I: Logging. (line 1688)
* %{OBJ}L: Logging. (line 1692)
* %{OBJ}N: Logging. (line 1710)
* %{UNIT}T: Logging. (line 1757)
* -beg, DeleteHeader option: Request Modification.
(line 2755)
* -beg, header matching flag: Rewrite. (line 2929)
* -c: Usage. (line 260)
* -C, poundctl: poundctl options. (line 4173)
* -case, DeleteHeader option: Request Modification.
(line 2759)
* -case, header matching flag: Rewrite. (line 2933)
* -contain, DeleteHeader option: Request Modification.
(line 2761)
* -contain, header matching flag: Rewrite. (line 2935)
* -e: Usage. (line 264)
* -end, DeleteHeader option: Request Modification.
(line 2764)
* -end, header matching flag: Rewrite. (line 2938)
* -exact, DeleteHeader option: Request Modification.
(line 2766)
* -exact, header matching flag: Rewrite. (line 2940)
* -F: Usage. (line 270)
* -f: Usage. (line 277)
* -f, poundctl: poundctl options. (line 4179)
* -file: ACL. (line 588)
* -file, header matching flag: Rewrite. (line 2942)
* -filewatch: ACL. (line 607)
* -h: Usage. (line 281)
* -h, poundctl: poundctl options. (line 4199)
* -i, poundctl: poundctl options. (line 4183)
* -icase, DeleteHeader option: Request Modification.
(line 2768)
* -icase, header matching flag: Rewrite. (line 2951)
* -j, poundctl: poundctl options. (line 4186)
* -k: poundctl options. (line 4194)
* -K, poundctl: poundctl options. (line 4189)
* -p: Usage. (line 284)
* -pcre, DeleteHeader option: Request Modification.
(line 2770)
* -pcre, header matching flag: Rewrite. (line 2953)
* -perl, DeleteHeader option: Request Modification.
(line 2773)
* -perl, header matching flag: Rewrite. (line 2956)
* -posix, DeleteHeader option: Request Modification.
(line 2775)
* -posix, header matching flag: Rewrite. (line 2958)
* -re, DeleteHeader option: Request Modification.
(line 2778)
* -re, header matching flag: Rewrite. (line 2961)
* -S, poundctl: poundctl options. (line 4202)
* -s, poundctl: poundctl options. (line 4206)
* -S, poundctl option: multiple servers. (line 4131)
* -T, poundctl: poundctl options. (line 4212)
* -t, poundctl: poundctl options. (line 4216)
* -v: Usage. (line 289)
* -V: Usage. (line 300)
* -V, poundctl: poundctl options. (line 4221)
* -v, poundctl: poundctl options. (line 4224)
* -W: Usage. (line 306)
* .poundctl: poundctl config. (line 4070)
* /etc/services: Listener address. (line 2531)
* 400: Error definitions. (line 2622)
* 401: Error definitions. (line 2627)
* 403: Error definitions. (line 2634)
* 404: Error definitions. (line 2639)
* 405: Error definitions. (line 2643)
* 413: Error definitions. (line 2648)
* 414: Error definitions. (line 2653)
* 500: Error definitions. (line 2658)
* 501: Error definitions. (line 2663)
* 503: Error definitions. (line 2667)
* A record, DNS: Dynamic backends. (line 1359)
* AAAA record, DNS: Dynamic backends. (line 1359)
* ACL: ACL. (line 567)
* ACL <1>: ACL definition. (line 2219)
* ACL <2>: Rewrite. (line 2829)
* ACL <3>: Rewrite. (line 2836)
* ACL <4>: Rewrite. (line 2847)
* ACL <5>: Rewrite. (line 2848)
* ACL <6>: Service Selection Statements.
(line 3283)
* ACL <7>: Service Selection Statements.
(line 3290)
* ACME: Service definitions.
(line 3125)
* add: poundctl commands. (line 4036)
* add <1>: Pipelines. (line 4521)
* AddHeader: Request Modification.
(line 2733)
* AddHeader <1>: Service Request and Response Modification.
(line 3418)
* Address: Listener address. (line 2521)
* Address <1>: Backend. (line 3542)
* Alive: Timeouts. (line 2450)
* all: Dynamic backends. (line 1430)
* all, log suppression: Service Logging. (line 3512)
* and: Pipelines. (line 4456)
* and, logical: Service selection. (line 517)
* Anonymise: Logging configuration.
(line 2340)
* Anonymize: Logging configuration.
(line 2341)
* any: Dynamic backends. (line 1448)
* Apsis: Overview. (line 116)
* authentication, basic: Authentication. (line 836)
* backend: Introduction. (line 188)
* Backend: Backend. (line 3526)
* backend, external: Redirects. (line 907)
* backend, regular: Introduction. (line 188)
* backend, special: Redirects. (line 907)
* backends, dynamic: Dynamic backends. (line 1347)
* BackendStats: Proxy Tuning. (line 2070)
* backreference expansion: Request modifications.
(line 715)
* Balancer: Balancer. (line 1218)
* Balancer <1>: Proxy Tuning. (line 2081)
* Balancer <2>: Other Statements. (line 3868)
* balancer group: Balancer groups. (line 1324)
* balancing: Balancer. (line 1158)
* balancing strategy: Balancer. (line 1166)
* basic authentication: Authentication. (line 836)
* BASIC, session type: Session. (line 3826)
* BasicAuth: Authentication. (line 849)
* BasicAuth <1>: Rewrite. (line 2862)
* BasicAuth <2>: Service Selection Statements.
(line 3301)
* boolean value, configuration file: Lexical structure. (line 1833)
* CAFile: poundctl config. (line 4104)
* CAFile <1>: multiple servers. (line 4154)
* CAlist: ListenHTTPS. (line 3219)
* CAPath: poundctl config. (line 4108)
* CAPath <1>: multiple servers. (line 4157)
* case insensitive match, DeleteHeader: Request Modification.
(line 2759)
* case insensitive match, headers: Rewrite. (line 2933)
* case sensitive match, DeleteHeader: Request Modification.
(line 2768)
* case sensitive match, headers: Rewrite. (line 2951)
* Cert: ListenHTTPS. (line 3151)
* Cert <1>: Backend. (line 3651)
* challenge directory, ACME: ACME. (line 1056)
* challenges, ACME: ACME. (line 1049)
* ChangeOwner: Management interface.
(line 2374)
* CheckURL: Listener-specific limits.
(line 2567)
* Ciphers: ListenHTTPS. (line 3198)
* Ciphers <1>: Backend. (line 3656)
* Client: Timeouts. (line 2458)
* Client <1>: Listener-specific limits.
(line 2546)
* ClientCert: ListenHTTPS. (line 3173)
* ClientCert <1>: Service Selection Statements.
(line 3314)
* ClientCert <2>: poundctl config. (line 4111)
* ClientCert <3>: multiple servers. (line 4160)
* clterr, log suppression: Service Logging. (line 3504)
* CNAME chains: resolver. (line 3901)
* CNAMEChain: resolver. (line 3900)
* combined: Logging. (line 1594)
* combined, built-in format: Logging. (line 1795)
* CombineHeaders: Proxy Tuning. (line 2141)
* comments, configuration file: Lexical structure. (line 1819)
* compound statement: Syntax. (line 1882)
* conditions, joining: Service selection. (line 492)
* ConfigFile: resolver. (line 3910)
* ConfigText: resolver. (line 3914)
* conjunction, implicit: Service selection. (line 492)
* conjunction, logical: Service selection. (line 517)
* ConnTO: Timeouts. (line 2471)
* ConnTO <1>: Backend. (line 3633)
* Control: Service Control. (line 2390)
* Control <1>: Management interface.
(line 2358)
* Control <2>: Special Backends. (line 3766)
* control socket: Management interface.
(line 2354)
* COOKIE, session type: Session. (line 3841)
* CRLlist: ListenHTTPS. (line 3235)
* custom log format: Logging. (line 1601)
* Daemon: Runtime directives. (line 1990)
* Debug: resolver. (line 3929)
* delete: poundctl commands. (line 4032)
* DeleteHeader: Request Modification.
(line 2742)
* DeleteHeader <1>: rewrite response. (line 3076)
* DeleteHeader <2>: Service Request and Response Modification.
(line 3427)
* detailed: Logging. (line 1598)
* detailed, built-in format: Logging. (line 1799)
* directive: Syntax. (line 1872)
* Disable: ListenHTTPS. (line 3186)
* Disable <1>: Backend. (line 3662)
* disable: poundctl commands. (line 4024)
* disable <1>: poundctl commands. (line 4025)
* disable <2>: poundctl commands. (line 4026)
* Disabled: Backend. (line 3549)
* Disabled <1>: Other Statements. (line 3862)
* disjunction, logical: Service selection. (line 509)
* div: Pipelines. (line 4530)
* dns: Usage. (line 317)
* dynamic backends: Dynamic backends. (line 1347)
* ECDHcurve: SSL Settings. (line 2182)
* Emergency: Special Backends. (line 3794)
* enable: poundctl commands. (line 4016)
* enable <1>: poundctl commands. (line 4017)
* enable <2>: poundctl commands. (line 4018)
* eq: Pipelines. (line 4480)
* Err400: Error definitions. (line 2608)
* Err401: Error definitions. (line 2608)
* Err403: Error definitions. (line 2608)
* Err404: Error definitions. (line 2608)
* Err413: Error definitions. (line 2608)
* Err414: Error definitions. (line 2608)
* Err500: Error definitions. (line 2608)
* Err501: Error definitions. (line 2608)
* Err503: Error definitions. (line 2608)
* Error: Special Backends. (line 3707)
* ErrorFile: Error definitions. (line 2600)
* escape character: Lexical structure. (line 1837)
* even: Pipelines. (line 4500)
* exact match, DeleteHeader: Request Modification.
(line 2766)
* exact match, headers: Rewrite. (line 2940)
* exists: Pipelines. (line 4517)
* expansion, backreference: Request modifications.
(line 715)
* extended: Logging. (line 1585)
* extended, built-in format: Logging. (line 1787)
* Family: Dynamic backends. (line 1443)
* Family <1>: Backend. (line 3572)
* file lookup, headers: Rewrite. (line 2942)
* first: Dynamic backends. (line 1425)
* ForwardedHeader: Logging configuration.
(line 2317)
* ForwardedHeader <1>: Listener logging. (line 2691)
* ForwardedHeader <2>: Service Logging. (line 3465)
* Frank Schmirler: Overview. (line 116)
* ge: Pipelines. (line 4497)
* Grace: Timeouts. (line 2494)
* Group: Runtime directives. (line 2001)
* gt: Pipelines. (line 4494)
* header: Request Accessors. (line 1968)
* Header: Rewrite. (line 2875)
* Header <1>: rewrite response. (line 3061)
* Header <2>: Service Selection Statements.
(line 3323)
* HEADER, session type: Session. (line 3845)
* HeaderAdd: Request Modification.
(line 2732)
* HeaderAdd <1>: Service Request and Response Modification.
(line 3417)
* HeaderOption: Proxy Tuning. (line 2097)
* HeaderRemove: Request Modification.
(line 2789)
* HeaderRemove <1>: Service Request and Response Modification.
(line 3428)
* HeadRemove: Request Modification.
(line 2790)
* HeadRemove <1>: Service Request and Response Modification.
(line 3429)
* high availability: Balancer groups. (line 1334)
* Host: Service selection. (line 404)
* host: Request Accessors. (line 1971)
* Host <1>: Rewrite. (line 2881)
* Host <2>: Service Selection Statements.
(line 3329)
* HTTPS: Backend. (line 3648)
* ID: Session. (line 3849)
* IgnoreCase: Regexp Settings. (line 2205)
* IgnoreCase <1>: Other Statements. (line 3883)
* IgnoreSRVWeight: Dynamic backends. (line 1464)
* IgnoreSRVWeight <1>: Backend. (line 3584)
* Include: File inclusion. (line 2257)
* include-dir=DIR: Usage. (line 329)
* IncludeDir: File inclusion. (line 2265)
* index: Pipelines. (line 4466)
* inet: Dynamic backends. (line 1451)
* inet6: Dynamic backends. (line 1454)
* info, log suppression: Service Logging. (line 3492)
* Interleaved weighted round robin balancing: Balancer. (line 1178)
* internal backend: Redirects. (line 907)
* IP address: Lexical structure. (line 1862)
* IP, session type: Session. (line 3821)
* iwrr: Balancer. (line 1225)
* keywords, configuration file: Lexical structure. (line 1823)
* le: Pipelines. (line 4491)
* len: Pipelines. (line 4474)
* LetsEncrypt: ACME. (line 1049)
* lexical structure of the configuration file: Lexical structure.
(line 1813)
* list: poundctl commands. (line 4009)
* list <1>: poundctl commands. (line 4010)
* list <2>: poundctl commands. (line 4011)
* list <3>: poundctl commands. (line 4012)
* listener: Introduction. (line 164)
* ListenHTTP: ListenHTTP. (line 2504)
* ListenHTTPS: ListenHTTPS. (line 3136)
* load balancing: Balancer. (line 1158)
* log format, user-defined: Logging. (line 1601)
* LogFacility: Logging. (line 1552)
* LogFacility <1>: Logging configuration.
(line 2282)
* LogFacility <2>: Logging configuration.
(line 2283)
* LogFormat: Logging. (line 1601)
* LogFormat <1>: Logging configuration.
(line 2294)
* logical and: Service selection. (line 517)
* logical and, explicit: Service selection. (line 517)
* logical and, implicit: Service selection. (line 492)
* logical conjunction, explicit: Service selection. (line 517)
* logical disjunction: Service selection. (line 509)
* logical or: Service selection. (line 509)
* LogLevel: Logging. (line 1562)
* LogLevel <1>: Logging configuration.
(line 2300)
* LogLevel <2>: Logging configuration.
(line 2301)
* LogLevel <3>: Listener logging. (line 2679)
* LogLevel <4>: Listener logging. (line 2680)
* LogSuppress: Service Logging. (line 3488)
* LogTag: Logging configuration.
(line 2312)
* lt: Pipelines. (line 4488)
* Match: Service selection. (line 509)
* Match <1>: Rewrite. (line 2978)
* Match <2>: Service Selection Statements.
(line 3381)
* matching rules: Service selection. (line 391)
* matching rules, joining: Service selection. (line 492)
* MaxRequest: Listener-specific limits.
(line 2554)
* MaxURI: Listener-specific limits.
(line 2560)
* Metrics: Special Backends. (line 3770)
* Mode: Management interface.
(line 2371)
* mul: Pipelines. (line 4527)
* multiple matching rules: Service selection. (line 492)
* mvh.inc: Proxy Tuning. (line 2165)
* ne: Pipelines. (line 4484)
* no-include-dir: Usage. (line 330)
* NoHTTPS11: ListenHTTPS. (line 3239)
* Not: Rewrite. (line 2972)
* Not <1>: Service Selection Statements.
(line 3375)
* not: Pipelines. (line 4477)
* null: Logging. (line 1576)
* null, built-in format: Logging. (line 1779)
* numbers, configuration file: Lexical structure. (line 1830)
* O'Sullivan, Rick: Overview. (line 116)
* off: poundctl commands. (line 4027)
* off <1>: poundctl commands. (line 4028)
* off <2>: poundctl commands. (line 4029)
* on: poundctl commands. (line 4019)
* on <1>: poundctl commands. (line 4020)
* on <2>: poundctl commands. (line 4021)
* or: Pipelines. (line 4461)
* or, logical: Service selection. (line 509)
* OverrideTTL: Backend. (line 3591)
* param: Request Accessors. (line 1965)
* PARAM, session type: Session. (line 3836)
* parenthesized subexpression: Request modifications.
(line 715)
* path: Request Accessors. (line 1959)
* Path: Rewrite. (line 2898)
* Path <1>: Service Selection Statements.
(line 3346)
* PCRE match, DeleteHeader: Request Modification.
(line 2770)
* PCRE match, DeleteHeader <1>: Request Modification.
(line 2773)
* PCRE match, headers: Rewrite. (line 2953)
* PCRE match, headers <1>: Rewrite. (line 2956)
* Perl-compatible regular expression match, DeleteHeader: Request Modification.
(line 2770)
* Perl-compatible regular expression match, DeleteHeader <1>: Request Modification.
(line 2773)
* Perl-compatible regular expression match, headers: Rewrite.
(line 2953)
* Perl-compatible regular expression match, headers <1>: Rewrite.
(line 2956)
* Perl-compatible regular expressions: Regular Expressions.
(line 540)
* PIDFile: Runtime directives. (line 2005)
* port: Request Accessors. (line 1975)
* Port: Listener address. (line 2530)
* Port <1>: Backend. (line 3558)
* posix regular expression match, DeleteHeader: Request Modification.
(line 2775)
* posix regular expression match, headers: Rewrite. (line 2958)
* POSIX regular expressions: Service selection. (line 415)
* pound.cfg: Introduction. (line 148)
* poundctl.tmpl: poundctl template. (line 4237)
* POUNDCTL_CONF: poundctl config. (line 4070)
* pound_backends: Metric Families. (line 4847)
* pound_backend_requests: Metric Families. (line 4896)
* pound_backend_request_stddev_nanoseconds: Metric Families. (line 4913)
* pound_backend_request_time_avg_nanoseconds: Metric Families.
(line 4905)
* pound_backend_state: Metric Families. (line 4871)
* pound_listener_enabled: Metric Families. (line 4785)
* pound_listener_info: Metric Families. (line 4793)
* pound_service_enabled: Metric Families. (line 4839)
* pound_service_info: Metric Families. (line 4817)
* POUND_TMPL_PATH: poundctl template. (line 4255)
* pound_workers: Metric Families. (line 4762)
* prefix match, DeleteHeader: Request Modification.
(line 2755)
* prefix match, headers: Rewrite. (line 2929)
* printf: Pipelines. (line 4504)
* Priority: Backend. (line 3562)
* priority, SRV record: Dynamic backends. (line 1366)
* query: Request Accessors. (line 1962)
* Query: Rewrite. (line 2902)
* Query <1>: Service Selection Statements.
(line 3350)
* QueryParam: Rewrite. (line 2907)
* QueryParam <1>: Service Selection Statements.
(line 3355)
* quoted string: Lexical structure. (line 1837)
* random: Balancer. (line 1222)
* redirect: Redirects. (line 912)
* Redirect: Special Backends. (line 3722)
* redirect, log suppression: Service Logging. (line 3500)
* RegexType: Regular Expressions.
(line 545)
* RegexType <1>: Regexp Settings. (line 2188)
* regular: Logging. (line 1580)
* regular backend: Introduction. (line 188)
* regular expression match, DeleteHeader: Request Modification.
(line 2778)
* regular expression match, headers: Rewrite. (line 2961)
* regular expressions, PCRE: Regular Expressions.
(line 540)
* regular expressions, Perl-compatible: Regular Expressions.
(line 540)
* regular expressions, POSIX: Service selection. (line 415)
* regular, built-in format: Logging. (line 1783)
* request accessor: Request modifications.
(line 758)
* request balancing: Balancer. (line 1158)
* request matching rules: Service selection. (line 391)
* resolv.conf: resolver. (line 3911)
* Resolve: Dynamic backends. (line 1421)
* Resolve <1>: Backend. (line 3601)
* Resolver: resolver. (line 3896)
* RetryInterval: Dynamic backends. (line 1499)
* RetryInterval <1>: Backend. (line 3624)
* RetryInterval <2>: resolver. (line 3932)
* rewrite: Conditional branches.
(line 776)
* Rewrite: Rewrite. (line 2798)
* Rewrite <1>: Service Request and Response Modification.
(line 3440)
* RewriteDestination: Request Modification.
(line 2712)
* RewriteErrors: Error response rewriting.
(line 3104)
* RewriteErrors <1>: Service Request and Response Modification.
(line 3458)
* RewriteLocation: Response Modification.
(line 3017)
* RFC 7617: Authentication. (line 836)
* Rick O'Sullivan: Overview. (line 116)
* Robert Segall: Overview. (line 116)
* RootJail: Runtime directives. (line 2030)
* Schmirler, Frank: Overview. (line 116)
* search path, templates: poundctl template. (line 4237)
* section: Syntax. (line 1882)
* Segall, Robert: Overview. (line 116)
* SendFile: Special Backends. (line 3743)
* Server, poundctl configuration: multiple servers. (line 4131)
* ServerName: Backend. (line 3670)
* service: Introduction. (line 170)
* Service definitions: Service definitions.
(line 3114)
* session: Sessions. (line 1247)
* Session: Session. (line 3807)
* SetHeader: Request Modification.
(line 2731)
* SetHeader <1>: rewrite response. (line 3082)
* SetHeader <2>: Service Request and Response Modification.
(line 3416)
* SetPath: Request Modification.
(line 2719)
* SetPath <1>: Service Request and Response Modification.
(line 3404)
* SetQuery: Request Modification.
(line 2722)
* SetQuery <1>: Service Request and Response Modification.
(line 3407)
* SetQueryParam: Request Modification.
(line 2727)
* SetQueryParam <1>: Service Request and Response Modification.
(line 3412)
* SetURL: Request Modification.
(line 2716)
* SetURL <1>: Service Request and Response Modification.
(line 3401)
* simple statement: Syntax. (line 1872)
* Socket: Management interface.
(line 2367)
* SocketFrom: Listener address. (line 2537)
* special backend: Redirects. (line 907)
* srv: Dynamic backends. (line 1435)
* SRV record, 0 weight: Dynamic backends. (line 1407)
* SRV record, DNS: Dynamic backends. (line 1366)
* SRV records, overriding weight: Dynamic backends. (line 1464)
* srverr, log suppression: Service Logging. (line 3508)
* SSLAllowClientRenegotiation: ListenHTTPS. (line 3209)
* SSLEngine: SSL Settings. (line 2178)
* SSLHonorCipherOrder: ListenHTTPS. (line 3203)
* SSLv2: ListenHTTPS. (line 3187)
* SSLv2 <1>: Backend. (line 3663)
* SSLv3: ListenHTTPS. (line 3187)
* SSLv3 <1>: Backend. (line 3663)
* statement, compound: Syntax. (line 1882)
* statement, simple: Syntax. (line 1872)
* strategy, request balancing: Balancer. (line 1166)
* StringMatch: Rewrite. (line 2914)
* StringMatch <1>: rewrite response. (line 3065)
* StringMatch <2>: Service Selection Statements.
(line 3362)
* sub: Pipelines. (line 4524)
* substring match, DeleteHeader: Request Modification.
(line 2761)
* substring match, headers: Rewrite. (line 2935)
* success, log suppression: Service Logging. (line 3496)
* suffix match, DeleteHeader: Request Modification.
(line 2764)
* suffix match, headers: Rewrite. (line 2938)
* Supervisor: Runtime directives. (line 2023)
* template search path: poundctl template. (line 4237)
* TemplateFile: poundctl config. (line 4119)
* TemplateName: poundctl config. (line 4125)
* TemplatePath: poundctl config. (line 4122)
* Threads: Worker Settings. (line 2060)
* time formats: Time and Date Formats.
(line 4924)
* TimeOut: Timeouts. (line 2465)
* TimeOut <1>: Backend. (line 3637)
* TLSv1: ListenHTTPS. (line 3187)
* TLSv1 <1>: Backend. (line 3663)
* TLSv1_1: ListenHTTPS. (line 3187)
* TLSv1_1 <1>: Backend. (line 3663)
* TLSv1_2: ListenHTTPS. (line 3187)
* TLSv1_2 <1>: Backend. (line 3663)
* TrustedIP: Logging configuration.
(line 2323)
* TrustedIP <1>: Listener logging. (line 2697)
* TrustedIP <2>: Service Logging. (line 3471)
* TTL: Session. (line 3854)
* Type: Session. (line 3817)
* typeof: Pipelines. (line 4513)
* url: Request Accessors. (line 1956)
* URL: Rewrite. (line 2918)
* URL <1>: Service Selection Statements.
(line 3366)
* URL <2>: poundctl config. (line 4099)
* URL <3>: multiple servers. (line 4149)
* URL, session type: Session. (line 3831)
* UseBackend: UseBackend. (line 3690)
* User: Runtime directives. (line 2042)
* user database: Authentication. (line 853)
* values, configuration file: Lexical structure. (line 1827)
* Verify: poundctl config. (line 4115)
* Verify <1>: multiple servers. (line 4164)
* VerifyList: ListenHTTPS. (line 3225)
* vhost_combined: Logging. (line 1590)
* vhost_combined, built-in format: Logging. (line 1791)
* warn-deprecated: Usage. (line 312)
* WatcherTTL: Timeouts. (line 2478)
* weight override, SRV records: Dynamic backends. (line 1464)
* weight, SRV record: Dynamic backends. (line 1366)
* Weighted random balancing: Balancer. (line 1170)
* WorkerIdleTimeout: Worker model. (line 1541)
* WorkerIdleTimeout <1>: Worker Settings. (line 2056)
* WorkerMaxCount: Worker model. (line 1533)
* WorkerMaxCount <1>: Worker Settings. (line 2052)
* WorkerMinCount: Worker model. (line 1526)
* WorkerMinCount <1>: Worker Settings. (line 2048)
* WSTimeOut: Timeouts. (line 2487)
* WSTimeOut <1>: Backend. (line 3641)
* xHTTP: Listener-specific limits.
(line 2572)