.\" Pound - the reverse-proxy load-balancer
.\" Copyright (C) 2002-2010 Apsis GmbH
.\" Copyright (C) 2018-2025 Sergey Poznyakoff
.\"
.\" Pound is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 3 of the License, or
.\" (at your option) any later version.
.\"
.\" Pound is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with pound.  If not, see <http://www.gnu.org/licenses/>.
.TH POUND 8 "January 2, 2025" "pound" "System Manager's Manual"
.SH NAME
pound \- HTTP/HTTPS reverse-proxy and load-balancer
.SH SYNOPSIS
.TP
.B pound
[\fB\-FVcehv\fR]
[\fB\-W [\fBno\-]\fIFEATURE\fR]
[\fB\-f \fICONF-FILE\fR]
[\fB\-p \fIPID-FILE\fR]
.SH DESCRIPTION
.PP
.B Pound
is a reverse-proxy load balancing server. It accepts requests from
HTTP/HTTPS clients and distributes them to one or more Web
servers (\fIbackends\fR). These requests may be passed to backends
as plain HTTP or re-encrypted as HTTPS.
.PP
If more than one backend server is defined,
.B pound
chooses one of them randomly, based on the requested balancing
algorithm and backend priorities. By default,
.B pound
keeps track of associations between clients and backend servers (sessions).
.SH GENERAL PRINCIPLES
.P
In general
.B pound
needs three types of objects defined in order to function:
.IR listeners ,
.I services
and
.IR backends .
.TP
\fBListeners\fR
A
.I listener
is a definition of how
.B pound
receives requests from the clients (browsers). Listeners of two types
are supported: regular HTTP listeners and HTTPS listeners.  In the
simplest case, a listener must define the address and port to listen
on, with additional requirements for HTTPS listeners.
.TP
\fBServices\fR
A
.I service
routes requests to backends.  Services may be defined within a
listener or in global scope.  When a request is received,
.B pound
attempts to match it to each service in turn, starting with the
services defined in the listener itself and, if needed, continuing
with those defined at the global level.  Services may define their own
conditions as to which requests they can answer: typically this
involves certain URLs (images only, or a certain path) or specific
headers (such as the Host header).  A service may also define a
.I session
mechanism: if so, future requests from a given client will always
be answered by the same
.IR backend .
.TP
\fBBackends\fR
.I Backends
are the actual servers for the content requested. By itself,
.B pound
supplies no responses - all contents must be received from a "real"
web server.  A
.I backend
defines how the server should be contacted.
.IP
Several types of backends are defined:
.RS
.TP
.I Regular backend
Regular backends are the most often used type of backends and the
.I raison d'etre
of
.BR pound .
A regular backend passes received requests to a backend server, waits
for it to respond and sends the response back to the requesting
client.
.TP
.I Redirect backend
A redirect backend responds to each request with a redirect response.
See
.BR Redirect ,
below.
.TP
.I ACME backend
A special backend designed to handle ACME challenges.  Backends of
this type are used to handle HTTP-01 authorization when re-issuing
.I LetsEncrypt
certificates.
.IP
See the
.B ACME
section below.
.TP
.I Error backend
An error backend creates and returns an HTTP status response.
.TP
.I Emergency backend
A special case of regular backend which will be used only if all other
regular backends fail to respond.
.RE
.IP
Multiple backends may be defined within a service, in which case
.B pound
will balance the load between the available backends.
.IP
Two types of load-balancing strategies are implemented: random
balancing (default), and interleaved weighted round-robin balancing.
.IP
If a backend fails to respond, it will be considered "dead", in which
case
.B pound
will stop sending requests to it. Dead
.I backends
are periodically checked for availability, and once they respond again they
are "resurrected" and requests are sent again their way. If no backends
are available (none were defined, or all are "dead"), then
.B pound
will reply with "503 Service Unavailable", without checking additional
services.
.IP
Normally, the connection between
.B pound
and its backends is via plain HTTP.  It is, however, possible to use
HTTPS as well.
.PP
A working
.B pound
configuration may define multiple listeners and services.  They can be
identified either by 0-based ordinal number within the configuration
(or, for services, within the listener) or by their symbolic name.
Backends are identified by their ordinal number within service.
.SH REQUEST BALANCING
\fILoad balancing strategy\fR defines algorithm used to distribute
incoming requests between multiple regular backends.  Each backend
is assigned a
.I priority
-- a positive number indicating its relative weight among other backends.
The share of requests a backend handles can be estimated as:
.IP
.RS
.EX
.BR "Pi / S(P)" ,
.EE
.RE
.PP
where
.B Pi
is priority of the backend with index
.BR i ,
and
.B S(P)
is sum of all priorities.
.PP
Two balancing strategies are implemented:
.TP
.B 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.
.TP
.B 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.
.IP
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.
.PP
Within each \fBService\fR, multiple backends are grouped in
.IR "balancer groups" .
Each such group is assigned a unique integer \fIpriority\fR, 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.
.PP
By default, backends declared using the \fBBackend\fR keyword are
assigned to the balancer group 0.  These are backends used during
normal operation.  Backends declared using the \fBEmergency\fR keyword
are assigned to the balancer group 65535.  These backends form a pull
of \fIhigh availability\fR backends, which will be tried only if all
of the normal backends fail.
.PP
More backend groups can be added using dynamic backends, discussed
below.
.SH WORKER MODEL
Each incoming request is processed by a specific \fIworker\fR, i.e. a
thread in the running program.  The number of running workers is
controlled by three configuration parameters.  \fBWorkerMinCount\fR
defines the minimum number of workers that should always be running
(5, by default). Another parameter, \fBWorkerMaxCount\fR sets the
upper limit on the number of running workers (it defaults to 128).
.PP
At each given moment, a worker can be in one of two states: \fIidle\fR
or \fIactive\fR (processing a request).  If an incoming request
arrives when all running workers are active, and total number of
workers is less than \fBWorkerMaxCount\fR, 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 \fIrequest
queue\fR, where it will wait for a worker to become available to
process it.
.PP
The third parameter, \fBWorkerIdleTimeout\fR, specifies maximum time
a thread is allowed to spend in the \fIidle\fR state.  If a worker
remains idle longer than that and total number of workers is greater
than the allotted minimum (\fBWorkerMinCount\fR), the idle worker is
terminated.
.SH OPTIONS
The following command line options are available:
.TP
\fB\-c\fR
Check only:
.B pound
will exit immediately after parsing the configuration file. This may
be used for running a quick syntax check before actually activating a
server.
.TP
\fB\-e\fR
Log to standard error (standard output for \fBLOG_DEBUG\fR and
\fBLOG_INFO\fR severity levels).  This option implies \fIforeground mode\fR
(\fB\-F\fR) and overrides the \fILogLevel\fR configuration setting.
.TP
\fB\-F\fR
Foreground mode.  The program will not detach from the controlling
terminal and will remain in foreground after startup.  This overrides
the \fBDaemon\fR configuration setting.  The log stream (syslog
facility or stderr) requested in the configuration remains in effect.
See also the \fB\-e\fR option, above.
.TP
\fB\-f\fR \fIFILE\fR
Location of the configuration file (see below for a full description
of the format).  Default is
.IR $sysconfdir/pound.cfg ,
where \fI$sysconfdir\fR stands for the system configuration directory,
as determined at build time.  Most often it is either
.IR /usr/local/etc ,
or
.IR /etc .
.TP
.B \-h
Print short command line usage summary and exit.
.TP
\fB\-p\fR pid_file
Location of the PID file.
.B Pound
will write its own PID into this file. Normally this is used for shell
scripts that control starting and stopping of the daemon. See the
description of
.B PIDFile
statement in the
.B GLOBAL DIRECTIVES
section below, for a detailed discussion of this file.
.TP
\fB\-v\fR
Verbose mode: during startup, error messages will be sent to stderr
(stdout for \fBLOG_DEBUG\fR and \fBLOG_INFO\fR severity levels).  If
.B pound
was configured to log to syslog, error diagnostics will be duplicated
there as well.  After startup the configuration settings take effect.
.TP
\fB\-V\fR
Print version:
.B pound
will exit immediately after printing the current version, licensing
terms, and configuration flags.
.TP
\fB\-W [\fBno\-]\fIFEATURE\fR
Enable or disable (if prefixed with \fBno\-\fR) additional \fBpound\fR
features.  As of this version, the following \fIFEATURE\fRs are implemented:
.RS
.TP
.RB [ no\- ] warn\-deprecated
Warn if any deprecated statements are used in configuration file.
.TP
.RB [ no\- ] dns
Resolve host names found in configuration file.  This is the default.
You can disable it if your configuration file refers to backends only
by their IP addresses, in order to suppress potentially lengthy
network host address lookups.
.TP
.B no\-include\-dir
Don't set the include directory to the system configuration
directory.  This means that each relative filename used in arguments
to the directives in the configuration file will be looked up in the
current working directory.  This feature is useful mainly in
testsuite.
.TP
\fBinclude\-dir=\fIDIR\fR
Override the default include directory setting.  Set it to \fIDIR\fR.
See the discussion of the \fBIncludeDir\fR directive in section
.BR "GLOBAL DIRECTIVES" ,
below.
.RE
.SH "CONFIGURATION FILE"
Each line in the file is considered a complete configuration
directive. Empty lines and comments are ignored. Comments are
introduced with a \fB#\fR sign and extend to the end of line on which
it appears.
.PP
There are three types of directives:
.B global
directives (they affect the settings for the entire program instance),
.B listener
directives (they define which requests
.B pound
will listen for), and
.B service
directives (they affect only a specific group of requests).
.PP
In general, a directive consists of a \fIkeyword\fR and one or
more \fIvalues\fR, separated by any amount of whitespace.  Leading and
trailing whitespace is ignored. Keywords are case-insensitive. A
\fIvalue\fR can be:
.TP
.I Numeric
A decimal number.
.TP
.I Boolean
The words \fByes\fR, \fBtrue\fR, \fBon\fR, or \fB1\fR indicating
\fItrue\fR, and \fBno\fR, \fBfalse\fR, \fBoff\fR, or \fB0\fR
indicating \fIfalse\fR. All words are case-insensitive.
.TP
.I String
Any sequence of characters between double-quotes.  A backslash is
treated as an escape character: if it is followed by a double-quote
or another backslash, it is removed and the character after it is
read literally.  If it is followed by any other character, a warning
message is printed.
.TP
.I Identifier
A sequence of characters starting with an ASCII letter and consisting
of letters, digits and underscores.
.TP
.I IP address
An IPv4 or IPv6 address in numeric form, or a hostname.
.PP
Unless specified otherwise, directives may appear in any order.
.SH "GLOBAL DIRECTIVES"
Global directives may appear anywhere at the top level within the
configuration file, although it is customary for them to be at the
start.
.TP
\fBUser\fR "\fIuser_name\fR"
Specify the user
.B pound
will run as (must be defined in the system user database).
.TP
\fBGroup\fR "\fIgroup_name\fR"
Specify the group
.B pound
will run as (must be defined in the system group database).
.TP
\fBRootJail\fR "\fIdirectory\fR"
Specify the directory that
.B pound
will chroot to at runtime.
.TP
\fBHeaderOption\fR \fIopt\fR...
Sets default options for header addition.  \fIopt\fR is one of:
\fBnone\fR to disable additional headers, \fBforwarded\fR to enable
adding
.BR X\-Forwarded\-For ,
.BR X\-Forwarded\-Proto ,
and
.B X\-Forwarded\-Port
headers, and
.B ssl
to enable passing information about SSL certificates in various
.B X\-SSL\-*
headers.  The default is
.IP
.RS
.B HeaderOption forwarded ssl
.RE
.IP
This setting can be overridden on a per-listener basis.  See the
description of \fBHeaderOption\fR directive in \fBHTTP Listener\fR
section, and section \fBBUILT-IN HEADERS\fR, for a detailed
discussion of various header modification directives and their effect.
.TP
\fBBalancer\fR \fBrandom\fR | \fBiwrr\fR
Defines the load-balancing strategy to use.  Possible arguments are:
\fBrandom\fR, to use weighted random balancing algorithm. an
\fBiwrr\fR, meaning interleaved weighted round robin balancing.
See
.BR "REQUEST BALANCING" ,
above, for a detailed discussion of these balancing strategies.
.IP
The \fBBalancer\fR statement in global scope applies to all
\fBService\fR directives that don't contain \fBBalancer\fR
definitions of their own.
.TP
\fBDaemon\fR \fIbool\fR
Have
.B pound
run in the foreground (if \fIfalse\fR) or as a daemon (if
\fItrue\fR). By default
.B pound
runs as a daemon (detaches itself from the controlling terminal and
puts itself in the background). By specifying this option you can force
.B pound
to work like a regular process. Useful for debugging or if you want to
use something like \fIdaemontools\fR.
.TP
\fBSupervisor\fR \fIbool\fR
When running in daemon mode, start a \fIsupervisor\fR process first.
This process will monitor the subordinate \fBpound\fR process, restarting
it if it fails.
.TP
\fBWorkerMinCount\fR \fIN\fR
Sets minimum number of worker threads that must always be running.
The default is 5.
See the section
.B WORKER MODEL
above for a detailed discussion.
.TP
\fBWorkerMaxCount\fR \fIN\fR
Sets maximum number of worker threads.  The default is 128.
See the section
.B WORKER MODEL
above for a detailed discussion.
.TP
\fBWorkerIdleTimeout\fR \fISEC\fR
Sets idle timeout for a worker thread.  Default is 30 seconds.
See the section
.B WORKER MODEL
above for a detailed discussion.
.TP
\fBThreads\fR \fIN\fR
This statement, retained for backward compatibility with previous
versions of
.BR pound ,
is equivalent to:
.IP
.RS
.EX
WorkerMinCount \fIN\fR
WorkerMaxCount \fIN\fR
.EE
.RE
.TP
\fBLogFacility\fR \fIident\fR
Specify the log facility to use.  The
.I ident
is one of the following:
.BR auth ,
.BR authpriv ,
.BR cron ,
.BR daemon ,
.BR ftp ,
.BR kern ,
.BR lpr ,
.BR mail ,
.BR news ,
.BR syslog ,
.BR user ,
.BR uucp ,
.B local0
through
.BR local7 .
The default value is
.BR daemon .
Using a \fB\-\fR (dash) for the facility name causes
.B pound
to log to stdout/stderr.
.TP
\fBLogFormat\fR "\fIname\fR" "\fIformat_def\fR"
Define HTTP log format.  \fIName\fR is a string uniquely identifying
this format.  \fIFormat_def\fR is the format string definition.  See
below, section
.BR "REQUEST LOGGING" ,
for a detailed description.
.TP
\fBLogLevel\fR \fIn\fR
Specify the logging level using built-in format indices: 0 for no
logging, 1 (default) for regular logging, 2 for extended logging (show
chosen backend server as well), 3 for Apache-like format (Combined Log
Format with Virtual Host), 4 (same as 3 but without the virtual host
information) and 5 (same as 3 but with information about the
.B Service
and
.B Backend
used).
This value can be overridden for specific listeners.
.IP
See
below, section
.BR "REQUEST LOGGING" ,
for a detailed description.
.TP
\fBLogLevel\fR "\fIname\fR"
Select a named format for logging HTTP requests.  \fIName\fR can
be either one of five built-in format names
.RB ( null ,
.BR regular ,
.BR extended ,
.BR vhost_combined ,
.BR combined ,
or
.BR detailed ),
or a format name defined earlier via the
.B LogFormat
directive.  See section
.BR "REQUEST LOGGING" ,
for a detailed discussion.
.TP
\fBLogTag\fR "\fIstring\fR"
Sets the string to tag log messages with.  This is used when log
output goes to syslog.  Default is the name with which \fBpound\fR
was started.
.TP
\fBForwardedHeader\fR \fIname\fR
Defines the name of the HTTP header that carries the list of proxies
the request has passed through.  It is used to report the originator
IP address when logging.  See the description of
.B %a
specifier in
.BR "REQUEST LOGGING" .
The default is
.BR X\-Forwarded\-For .
.TP
.B TrustedIP
Defines a list of
.I trusted proxy
IP addresses, which is used to determine the originator IP.  See the
description of
.B %a
specifier in
.BR "REQUEST LOGGING" ,
for a detailed discussion.
.IP
This statement is a special form of \fBACL\fR statement, described
below.  It can appear as a \fIsection\fR or \fIdirective\fR.  When
used as a section, it is followed by a list of one or more CIDRs
each appearing on a separate line.  The \fBEnd\fR keyword terminates
the statement, e.g.:
.IP
.RS
.EX
TrustedIP
  "127.0.0.1/8"
  "10.16.0.0/16"
End
.EE
.RE
.IP
In directive form, this statement takes single argument, the name of
an access control list defined earlier using the \fBACL\fR statement,
e.g.
.IP
.RS
.EX
TrustedIP "proxy_addresses"
.EE
.RE
.TP
\fBIgnoreCase\fR \fIbool\fR
Ignore case when doing regex matching (default: \fIfalse\fR). This
directive sets the default for the following service matching
directives:
.BR URL ,
.BR Path ,
.BR QueryParam ,
.BR Query ,
.BR StringMatch ,
as well as for the \fBDeleteHeader\fR modification directive.  Its
value can be overridden for specific services.
.IP
This statement is deprecated and will be removed in future versions.
Please, use the \fB\-icase\fR option to the service matching directive
instead.  See the discussion of \fIoptions\fR in
.B Service Matching Directives
section below.
.TP
\fBAlive\fR \fIn\fR
Specify how often
.B pound
will check for resurrected backend hosts (default: 30 seconds). In
general, it is a good idea to set this as low as possible - it
will find resurrected hosts faster. However, if you set it too
low it will consume resources - so beware.
.TP
\fBClient\fR \fIn\fR
Specify for how long
.B pound
will wait for a client request (default: 10 seconds). After this
long has passed without the client sending any data
.B pound
will close the connection. Set it higher if your clients
time-out on a slow network or over-loaded server, lower if you
start getting DOS attacks or run into problems with IE clients.
This value can be overridden for specific listeners.
.TP
\fBTimeOut\fR \fIn\fR
How long should
.B pound
wait for a response from the backend (in seconds). Default: 15 seconds.
This value can be overridden for specific backends.
.TP
\fBConnTO\fR \fIn\fR
How long should
.B pound
wait for a connection to the backend (in seconds). Default: the
.B TimeOut
value. This value can be overridden for specific backends.
.TP
\fBWSTimeOut\fR \fIn\fR
How long should
.B pound
wait for data from either backend or client in a connection upgraded to
a WebSocket (in seconds). Default: 600 seconds.
This value can be overridden for specific backends.
.TP
\fBGrace\fR \fIn\fR
How long should
.B 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
.B pound
with a TERM or QUIT signal, in which case the program exits without any
delay.
.TP
\fBSSLEngine\fR "\fIname\fR"
Use an OpenSSL hardware acceleration card called \fIname\fR. Available
only if OpenSSL-engine is installed on your system.
.TP
\fBECDHcurve\fR "\fIname\fR"
Use the named curve for elliptical curve encryption (default: prime256v1).
.TP
\fBControl\fR "\fIpathname\fR"
Set the control socket path.
See the
.B Control socket
section below, for a detailed description of this feature.
.TP
\fBCombineHeaders\fR ... \fBEnd\fR
Declare names of the headers that can appear multiple times in a
message, and that should be combined into one value.  Header names
must appear one per line between \fBCombineHeaders\fR and \fBEnd\fR.
.IP
See the section
.BR "MULTI-VALUE HEADERS" ,
for a detailed discussion of this feature.
.TP
\fBIncludeDir\fR "\fIdir\fR"
Sets the \fIinclude directory\fR.  This is the directory
where \fIpound\fR looks for relative file names that appear in other
configuration directives (e.g. \fIInclude\fR).  The default value is
the system configuration directory as set at compile time (you can
check its value in the output of \fBpound -V\fR).  This initial value
can be changed in the command line using the
\fB\-W include\-dir=\fIname\fR option or reset to the current working
directory using the \fB\-W no\-include\-dir\fR option (see the
discussion of \fB\-W\fR below).
.TP
\fBInclude\fR "\fIfile\fR"
Include the file as though it were part of the configuration file.  If
\fIfile\fR is a relative file name, it will be looked in the \fIinclude
directory\fR (see above).
.IP
This directive is allowed both at topmost level and in any subsections
of the configuration file.
.TP
\fBAnonymise\fR
(alternative spelling \fBAnonymize\fR also accepted) Replace the last
byte of the client address with 0 for logging purposes.
Default: log the client address in full.
.TP
\fBACL\fR "\fIname\fR"
Define a \fInamed access control list\fR (\fIACL\fR).  An ACL is a
list of network addresses in CIDR notation, one address per line,
terminated with an
.B End
directive on a line by itself.  E.g.:
.IP
.RS
.EX
ACL "secure"
   "192.0.2.0/26"
   "203.0.113.0/24"
End
.EE
.RE
.IP
The
.B Include
directive is allowed within
.BR ACL .
.IP
Named ACLs can be used in \fBService\fR definitions to make services
available from certain IP addresses only.
.RE
.TP
\fBPIDFile\fR "\fIfilename\fR"
Sets the name of the file where to store program PID.  It can be
overridden by the
.B \-p
command line option.
.IP
.I Notice
the following:
.RS
.nr step 1 1
.IP \n[step].
When running with a supervisor, this file holds PID of the supervisor
process.  Otherwise, it holds PID of the main
.B pound
process.  This means it is always suitable for signalling the program
using the traditional \fBkill `cat filename`\fR technique.
.IP \n+[step].
Before shutting down,
.B pound
removes this file.  However, this may be not possible if it switches to
privileges of another user after startup (at least one of \fBUser\fR or
\fBGroup\fR are set in the configuration file) and the file is stored in
a directory whose permissions forbid write access for that user.
.RE
.TP
\fBRegexType posix\fR | \fBpcre\fR | \fBperl\fR
Sets the type of regular expressions to use in request matching
statements.
.B posix
selects POSIX extended regular expressions and
.B pcre
or
.B perl
select Perl-compatible regular expressions.  The latter requires
compile-time support.  The selected regular expression type remains in
effect until next
.B RegexType
statement or end of the configuration file, whichever occurs first.
.SS Control socket
.B Pound
can be instructed to listen for management requests,
which will allow you to obtain information about the running
instance, change state of configured listeners, services, and
backends, etc.  These requests may be issued by using the
.BR poundctl (8)
utility.
.PP
Usually, a UNIX socket is used to communicate with the management interface.
It is configured via the
.B Control
statement.  This statement has two forms.  In
.I inline
form, the statement takes a single argument, specifying the name of
the UNIX socket file to create and listen on.  For example:
.PP
.EX
Control "/run/pound.sock"
.EE
.PP
The file will be owned by the user that started
.B pound
(normally root) and will have mode 0600.
.PP
The block form allows you to specify file mode and, to certain extent,
the socket file ownership:
.PP
.EX
Control
    Socket "/run/pound.sock"
    Mode 660
    ChangeOwner true
End
.EE
.PP
The substatements are:
.TP
.B Socket "\fIfilename\fR"
Specifies the name of the socket file to use.  This is the only
mandatory statement in the block form.
.TP
.B Mode \fIoctal\fR
Sets the mode of the socket file.
.TP
.B ChangeOwner \fIbool\fR
This statement takes effect if at least one of
.B User
or
.B Group
global statements is used.  When set to
.B true
it will change the owner of the socket file to that specified by
those two statements.
.PP
It is also possible to have
.B pound
listen for management requests on an INET or INET6 address.  See
below, the section
.BR "Backend definitions" ,
description of the
.B Control
statement.
.SH "HTTP Listener"
An HTTP listener defines an address and port that
.B pound
will listen on for HTTP requests.  The listener declaration begins with
the keyword
.B ListenHTTP
on a separate line.  The keyword may be followed by a quoted string
supplying listener name.  This name is a unique label that identifies
the listener.
.PP
All configuration directives enclosed between
.B ListenHTTP
and
.B End
are specific to a single HTTP listener.  At the very least you must specify
IP address and port for each listener. The following directives are
available:
.TP
\fBAddress\fR \fIaddress\fR
The address that
.B pound
will listen on. This can be a numeric IP address, or a full pathname
of a UNIX socket.  If neither this directive nor
.B SocketFrom
(see below) is given,
.I ::0
is assumed.
.TP
\fBPort\fR \fIport\fR
The port number or service name that
.B pound
will listen on.  If not given, default port number is assumed, i.e.
80, for
.BR ListenHTTP ,
and 443, for
.B ListenHTTPS
(see below).
.TP
\fBSocketFrom\fR "\fIpathname\fR"
Read the socket to listen on from the UNIX socket given as argument.
If this parameter is supplied, neither
.B Address
nor
.B Port
may be used.  This parameter is intended for testing
.BR pound .
.TP
\fBxHTTP\fR \fIn\fR
Defines which HTTP verbs are accepted. The possible values are:
.IP
.B 0
(default) accept only standard HTTP requests (GET, POST, HEAD).
.IP
.B 1
additionally allow extended HTTP requests (PUT, PATCH, DELETE).
.IP
.B 2
additionally allow standard WebDAV verbs (LOCK, UNLOCK, PROPFIND,
PROPPATCH, SEARCH, MKCOL, MOVE, COPY, OPTIONS, TRACE, MKACTIVITY,
CHECKOUT, MERGE, REPORT).
.IP
.B 3
additionally allow MS extensions WebDAV verbs (SUBSCRIBE, UNSUBSCRIBE,
NOTIFY, BPROPFIND, BPROPPATCH, POLL, BMOVE, BCOPY, BDELETE, CONNECT).
.TP
\fBClient\fR \fIn\fR
Override the global
.I Client
time-out value.
.TP
\fBCheckURL\fR "\fIpattern\fR"
Define a pattern that must be matched by each request sent to this
listener. A request that does not match is considered to be illegal.
By default
.B pound
accepts all requests (i.e. the pattern is ".*"), but you are free to
limit it to something more reasonable. Please note that this applies
only to the request path -
.B pound
will still check that the request is syntactically correct.
.TP
\fBErrorFile\fR \fINNN\fR "\fIfilename\fR"
Read the content to be returned along with the HTTP status code
\fINNN\fR from the file \fIfilename\fR.  The file will be read
exactly once, at the program startup.
.IP
Allowed values for \fINNN\fR are:
.BR 400 ,
.BR 401 ,
.BR 404 ,
.BR 405 ,
.BR 413 ,
.BR 414 ,
.BR 500 ,
.BR 501 ,
.BR 503 .
.TP
\fBErr\fINNN\fR "\fIfilename\fR"
This statement is equivalent to
.IP
.EX
ErrorFile \fINNN\fR "\fIfilename\fR"
.EE
.IP
It is provided for compatibility with previous versions of the program.
.TP
\fBMaxRequest\fR \fIn\fR
Maximum allowed size of incoming request. All requests will be limited
to these many bytes. If a request contains more data than allowed, an
error 413 is returned. Default: unlimited.
.TP
\fBMaxURI\fR \fIn\fR
Maximum allowed length of an URI.  If the URI of a request is longer than
\fIn\fR bytes, an error 414 is returned. Default: unlimited.
.TP
\fBRewriteLocation\fR 0|1|2
If set to 1, force
.B pound
to change the Location: and Content-location: headers in responses. If they
point to the backend itself or to the listener (but with the wrong protocol),
the response will be changed to show the virtual host in the request. Default:
1 (active).  If the value is set to 2, only the backend address is compared;
this is useful for redirecting a request to an HTTPS listener on
the same server as the HTTP listener.
.TP
\fBRewriteDestination\fR \fIbool\fR
If set to \fItrue\fI, force
.B pound
to change the "Destination:" header in requests. The header is changed
to point to the backend itself with the correct protocol. Default:
\fIfalse\fR.
.TP
\fBLogLevel\fR \fIn\fR
Log HTTP requests using built-in format \fIn\fR.  This statement
configures logging specific for this listener, overriding the
global
.B LogLevel
setting.  See
.BR "REQUEST LOGGING" ,
for a detailed discussion.
.TP
\fBLogLevel\fR "\fIname\fR"
Select a named format for logging HTTP requests.  \fIName\fR can
be either one of five built-in format names
.RB ( null ,
.BR regular ,
.BR extended ,
.BR vhost_combined ,
.BR combined ,
or
.BR detailed ),
or a format name defined earlier via the
.B LogFormat
directive.
.IP
This statement configures logging specific for this listener,
overriding the global
.B LogLevel
setting.  See section
.BR "REQUEST LOGGING" ,
for a detailed discussion.
.TP
\fBForwardedHeader\fR \fIname\fR
Defines the name of the HTTP header that carries the list of proxies
the request has passed through.  It is used to report the originator
IP address when logging.  See the description of
.B %a
specifier in
.BR "REQUEST LOGGING" .
This statement overrides the \fBForwardedHeader\fR directive from the
global scope.
.IP
The default is
.BR X\-Forwarded\-For .
.TP
.B TrustedIP
Defines a list of
.I trusted proxy
IP addresses, which is used to determine the originator IP.  See the
description of
.B %a
specifier in
.BR "REQUEST LOGGING" ,
for a detailed discussion.
.IP
This statement overrides the \fBTrustedIP\fR directive from the
global scope.
.TP
\fBService\fR [ "\fIname\fR" ]
This defines a private service (see below for service definition
syntax). This service will be used only by this listener. Optional
\fIname\fR supplies the label, that can be used in
.BR poundctl (8)
requests to identify the service.  This label must be unique among all
services within the enclosing listener, or, for global services,
within the configuration.
.TP
\fBACME\fR "\fIdirectory\fR"
Serve ACME challenge requests from the given
.IR directory .
See section
.B ACME
below.
.TP
\fBHeaderOption\fR \fIopt\fR...
Modifies global header addition options for this listener.  Global
options are set by the \fBHeaderOption\fR directive in the global
scope and default to \fBforwarded ssl\fR.  \fIopt\fR is one of:
.RS
.TP
.B all
Enable all additional headers.
.TP
.B none
Disable all additional headers.
.TP
.B forwarded
Enable adding
.BR X\-Forwarded\-For ,
.BR X\-Forwarded\-Proto ,
and
.B X\-Forwarded\-Port
headers.
.TP
.B ssl
Enable passing information about SSL certificates in various
.B X\-SSL\-*
headers.
.RE
.IP
Each option except \fBnone\fR can be prefixed with \fBno\-\fR to
revert its meaning.
.IP
For example, to disable adding the \fBX\-SSL\-*\fR headers for a
listener, one would use:
.IP
.RS
.B HeaderOption no\-ssl
.RE
.IP
See the description of \fBHeaderOption\fR directive in \fBGLOBAL
DIRECTIVES\fR section, and section \fBBUILT-IN HEADERS\fR, for a
detailed discussion of various header modification directives and
their effect.
.SS String expansion
Some of the statements described below take as their arguments string
values that undergo several \fIexpansions\fR before use.  These
expansions are as follows:
.TP
.B Backreference expansion
Backreference is a construct that refers to a \fIparenthesized
group\fR within a regular expression matched by one of service
matching directives described above.  During backreference expansion,
each occurrence of such construct in a string is replaced with the
actual value of that parenthesized group.
.IP
Syntactically backreference can take two forms.  The construct
\fB$\fIN\fR (\fIN\fR is a decimal number)
refers to \fIN\fRth parenthesized subexpression of the most
recently matched statement, and \fB$\fIN\fB(\fIM\fB)\fR refers to
\fIN\fRth parenthesized subexpression of \fIM\fRth recently matched
statement.  Numbering of subexpressions starts at 1 (\fB$0\fR refers
to the entire matching string).  Numbering of matches starts
at 0.
.IP
For example, given the following statements
.IP
.EX
Host -re "www\\.(.+)"
Header -re -icase "^Content-Type: *(.*)"
Path "^/static(/.*)?"
.EE
.IP
\fB$1\fR refers to the subgroup of \fBPath\fR, \fB$1(1)\fR - to that of
\fBHeader\fR, and \fB$1(2)\fR - to that of \fBHost\fR.
.IP
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: \fB"${1}(text)"\fR.
.IP
To insert a literal dollar or percent sign in
.IR url ,
use
.B $$
or
.BR $% ,
correspondingly.
.TP
.B Request accessor interpretation
Request accessor is \fB%[\fIname\fR\fB]\fR, where \fIname\fR denotes
a part of the incoming request to access.  Accessors are interpreted and
replaced with 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.
.IP
The following accessors are defined:
.RS
.TP
.B url
Request URL.
.TP
.B path
Request path.
.TP
.B query
Query part.
.TP
\fBparam \fINAME\fR
The value of the query parameter \fINAME\fR.
.TP
\fBheader \fINAME\fR
The value of HTTP header \fINAME\fR.
.TP
.B host
Hostname part of the \fBHost\fR header.  If the latter
does not include port number, it is equivalent to \fB%[header
host]\fR.
.B port
If the value of the \fBHost\fR header includes port number,
\fB%[port]\fR evaluates to port number with the leading colon
character. Otherwise, it evaluates to empty string.
.SS Modification directives
The following directives modify the incoming request prior to passing
it to the selected service. These are discussed in detail
in section
.BR "REQUEST MODIFICATION" ,
below.
.TP
\fBDeleteHeader\fR "\fIheader\fB: \fIpattern\fR"
Remove certain headers from the incoming requests. All occurrences of
the matching header will be removed. The argument is treated verbatim.
.TP
\fBSetHeader\fR "\fIheader\fB: \fIvalue\fR"
Add header to the request passed to the backend server. Argument
undergoes string expansion as described above. The expanded value must
be a valid header line.
.TP
\fBSetURL\fR "\fIvalue\fR"
Sets the URL part of the request. Argument is subject to string expansion.
.TP
\fBSetPath\fR "\fIvalue\fR"
Sets the path part of the request. Argument is subject to string expansion.
.TP
\fBSetQuery\fR "\fIvalue\fR"
Sets the query part of the request. Argument is subject to string expansion.
.TP
\fBSetQueryParam\fR "\fIname\fR" "\fIvalue\fR"
Modifies the query.  Sets the query parameter \fIname\fR to
\fIvalue\fR. The \fIvalue\fR argument is subject to string expansion.
.TP
.BR Rewrite " [" request | response "] ... [ " Else " ... ] " End
Conditionally modify request or response depending on whether it
matches certain conditions.  If the argument is omitted, \fBrequest\fR
is assumed.
.IP
Request modification is described in detail in section
.B "REQUEST MODIFICATION DIRECTIVES" .
.IP
Response modification is covered by section
.BR "RESPONSE MODIFICATION" .
.SS Compatibility directives
The following directives are retained for compatibility with previous
versions of
.BR pound .
They will be removed in future releases.
.TP
\fBHeaderAdd\fR "\fIheader\fB: \fIvalue\fR"
Same as \fBSetHeader\fR.
.TP
\fBAddHeader\fR "\fIheader\fB: \fIvalue\fR"
Same as \fBSetHeader\fR.
.TP
\fBHeaderRemove\fR "\fIpattern\fR"
Same as \fBDeleteHeader\fR.
.TP
\fBHeadRemove\fR "\fIpattern\fR"
Same as \fBDeleteHeader\fR.
.SH "HTTPS Listener"
HTTPS listener defines an address and port that
.B pound
will listen on for HTTPS requests.  The listener declaration begins with
the keyword
.B ListenHTTPS
on a separate line.  The keyword may be followed by a quoted string
supplying listener name.  This name is a unique label that identifies
the listener.
.PP
All configuration directives enclosed between
.B ListenHTTPS
and
.B End
are specific to a single HTTPS listener. At the very least you must specify
an address, a port and a server certificate for each listener. All directives
defined for HTTP listeners are applicable to HTTPS listeners as well. The
following additional directives are also available:
.TP
\fBCert\fR "\fIfilename\fR"
Specify the server certificate.  \fIFilename\fR is either a
.I certificate file
name, or the name of a directory containing certificate files.
.IP
.I Certificate file
is a file containing the certificate, possibly a certificate chain
and the signature for this server, in that order.
.IP
This directive is
.B mandatory
for HTTPS listeners.
.IP
Please note that multiple
.B Cert
directives are allowed if your OpenSSL version supports SNI. In such cases,
the first directive is the default certificate, with additional certificates
used if the client requests them.
.IP
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
.B after
host-specific certificates).
.IP
.B Cert
directives
.B must
precede all other SSL-specific directives.
.TP
\fBClientCert\fR 0|1|2|3 \fIdepth\fR
Ask for the client's HTTPS certificate: 0 - don't ask (default), 1 - ask,
2 - ask and fail if no certificate was presented, 3 - ask but do not verify.
.I 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.
.TP
\fBDisable\fR SSLv2|SSLv3|TLSv1|TLSv1_1|TLSv1_2
Disable the protocol \fBand all lower protocols as well\fR.
This is due to a limitation in OpenSSL, which does not support
disabling a single protocol. For example,
.B Disable TLSv1
would disable SSLv2, SSLv3 and TLSv1, thus allowing only TLSv1_1 and TLSv1_2.
.TP
\fBCiphers\fR "\fIcipher_list\fR"
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
.BR ciphers (1)
and
.BR SSL_CTX_set_cipher_list (3).
.TP
\fBSSLHonorCipherOrder\fR \fIbool\fR
If set to \fItrue\fR, the server will broadcast a preference to use
ciphers in the order supplied in the \fBCiphers\fR directive.  If the
value is \fIfalse\fR, the server will accept any cipher from the
.B Ciphers
list.  Default value is \fIfalse\fR.
.TP
\fBSSLAllowClientRenegotiation\fR 0|1|2
If this value is 0, client initiated renegotiation will be disabled.
This will mitigate DoS exploits based on client renegotiation,
regardless of the patch status of clients and servers related to
"Secure renegotiation".  If the value is 1, secure renegotiation is
supported.  If the value is 2, insecure renegotiation is supported,
with unpatched clients. \fBThis can lead to a DoS and a Man in the
Middle attack!\fR The default value is 0.
.TP
\fBCAlist\fR "\fIfilename\fR"
Set the list of "trusted" CA's for this server. The \fIfilename\fR is
the name of a file containing a sequence of CA certificates (PEM
format). The names of the defined CA certificates will be sent to the
client on connection.
.TP
\fBVerifyList\fR "\fIfilename\fR"
Set the CA (Certificate Authority). The \fIfilename\fR is a file that
contains the CA root certificates (in PEM format).
.IP
.IR "Please note":
there is an important difference between the CAlist and the VerifyList. The
CAlist tells the client (browser) which client certificates it should
send. The VerifyList defines which CAs are actually used for the
verification of the returned certificate.
.TP
\fBCRLlist\fR "\fIfilename\fR"
Set the CRL (Certificate Revocation List) file. The \fIfilename\fR is a file
that contains the CRLs (in PEM format).
.TP
\fBNoHTTPS11\fR 0|1|2
Behave like an HTTP/1.0 server for HTTPS clients. If this value is
0, disable the check. If the value is 1, do not allow multiple
requests on SSL connections. If the value is 2 (default), disable multiple
requests on SSL connections only for MSIE clients. Required
work-around for a bug in certain versions of IE.
.SH "Service"
A service is a definition of which backend servers
.B pound
will use to reply to incoming requests. A service may be defined as part
of a listener (in which case it will be used only by that listener), or
globally (which makes it available to all listeners).
.B Pound
selects a listener based on user-supplied conditions that analyze the
incoming request URL and/or headers.  It will always scan
listener-specific services first.  If none matches, it
will try the global ones.  Services are tried in the same order as
they are defined in configuration.
.PP
All configuration directives enclosed between
.B Service
and
.B End
are specific to a single service. They can be subdivided into two
categories: \fIservice matching directives\fR and \fIbackend
definitions\fR.
.SS Service Matching Directives
These directives determine whether a particular request should be
handled by this service.  When a request arrives, each service is
considered in turn (first services defined within the listener that
received the request, then the ones defined in global scope).  First
service that matches the request will be used.  If no service matches,
a 503 "Service unavailable" error is returned.
.PP
Unless explicitly stated in the configuration file, all matching
directives are joined by a boolean \fBAND\fR.
.PP
A service with no matching directives always matches.
.TP
\fBACL\fR "\fIname\fR"
Match the source IP address against the named ACL.  The ACL must have
been defined earlier (see the
.B ACL
statement in
.B "GLOBAL DIRECTIVES"
section above).  If the IP doesn't match, then this service will be
skipped and next one tried.
.TP
\fBACL\fR
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 the
.B "GLOBAL DIRECTIVES"
section above.
The ACL definition is finished with a
.B End
keyword on a line by itself.
.sp
Semantically it is equivalent to the named ACL reference described
above.
.TP
\fBBasicAuth\fR "\fIfilename\fR"
Evaluates to true if the incoming request passes basic authorization
as described in RFC 7617.  \fIfilename\fR is the name of a plain text
file containing usernames and passwords, created with
.BR htpasswd (1)
or similar utility.  Unless it starts with a slash, it is taken
relative to the \fBIncludeDir\fR 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 \fBPound\fR notices that its modification time has
changed.
.IP
See the section entitled
.BR "BASIC AUTHENTICATION" ,
for a detailed discussion.
.TP
\fBClientCert \fR"\fIfilename\fR"
Evaluates to \fItrue\fR if the client presented the certificate
matching that from the file \fIfilename\fR (PEM format).
.IP
This conditional cannot be used in standalone services (i.e. services
that are defined in global scope), or if the \fBListenHTTPS\fR section
that hosts the service has the \fBClientCert\fR statement on its own.
.TP
\fBHeader\fR [\fIoptions\fR] "\fIpattern\fR"
The request must contain at least one header matching the given
\fIpattern\fR.  By default, \fIpattern\fR is treated as
case-insensitive extended regular expression.  This can be changed by
\fIoptions\fR, described below.
.TP
\fBHost\fR [\fIoptions\fR] "\fIhostname\fR"
The request must contain a \fBHost\fR header whose value matches
\fIhostname\fR.  In the absence of \fIoptions\fR, case-insensitive
exact match is assumed, i.e. this construct is equivalent to
.IP
\fBHeader\fR "Host:[[:space:]]*\fIqhost\fR"
.IP
where \fIqhost\fR is the "\fIhostname\fR" argument in quoted form, i.e. with
all characters that have special meaning in regular expressions
escaped.
.IP
See below for the discussion of \fIoptions\fR and their effect on
matching.
.IP
This statement is provided to facilitate handling of \fIvirtual
hosts\fR.  See the
.B EXAMPLES
section.
.TP
\fBPath\fR [\fIoptions\fR] "\fIpattern\fR"
Match the path part of the incoming request.
.TP
\fBQuery\fR [\fIoptions\fR] "\fIpattern\fR"
Match the query part of the incoming request. The argument must be
properly percent-encoded, if it contains whitespace or other
non-printable characters.
.TP
\fBQueryParam\fR "\fIname\fR" [\fIoptions\fR] "\fIpattern\fR"
Match the value of the query parameter \fIname\fR.
.TP
\fBStringMatch\fR "\fIstring\fR" [\fIoptions\fR] "\fIpattern\fR"
Expand \fIstring\fR as described in \fBString expansion\fR (see below)
and match the resulting value against \fIpattern\fR.
.TP
\fBURL\fR [\fIoptions\fR] "\fIpattern\fR"
Match the URL of the incoming request.  By default, \fIpattern\fR is
treated as case-sensitive extended regular expression.  This can be
changed by \fIoptions\fR, described below.
.PP
The \fIoptions\fR argument in the above directives can be used to
select the comparison method.  It consists of zero or more option
flags from the following list:
.TP
.B \-beg
Exact match at the beginning of string (prefix match).
.TP
.B \-case
Case-sensitive comparison.
.TP
.B \-contain
Match substring.
.TP
.B \-end
Exact match at the end of string (suffix match).
.TP
.B \-exact
Exact string match.
.TP
.B \-file
Treat \fIpattern\fR as the name of a file to read patterns from.  If
the name is relative, it will be looked up in the \fIinclude
directory\fR (see the discussion of the \fBIncludeDir\fR directory
above).  Patterns are read from the file line by line.  Leading and
trailing whitespace is removed.  Empty
lines and comments (lines starting with \fB#\fR) are ignored.
.TP
.B \-icase
Case-insensitive comparison.
.TP
.BR \-pcre " or " \-perl
Use Perl-compatible regular expression (requires compilation-time
support).  This overrides global
.B RegexType
settings.
.TP
.B \-posix
Use POSIX extended regular expression.  This overrides global
.B RegexType
settings.
.TP
.B \-re
Use regular expression matching, as set by the
.B RegexType
statement.
.PP
For example, the following will match any request whose \fBHost\fR
header begins with "www." (case-insensitive):
.PP
.EE
Host -icase -beg "www."
.EX
.SS Compatibility directives
The following directives are provided for backward compatibility with
older versions of
.BR pound .
They will be removed in future versions.
.TP
\fBHeadRequire\fR "\fIpattern\fR"
Same as \fBHeader\fR.
.TP
\fBHeadDeny\fR "\fIpattern\fR"
A shortcut for
.IP
\fBNot header\fR "\fIpattern\fR"
.IP
In other words: the request may
.B not
contain any header matching the given pattern.  See the
.B Negation
section, below.
.SS Negation
Prefixing any of the directives discussed above with \fBnot\fR will
revert the sense of comparison.  For example,
.PP
.EX
Not url "^/static/"
.EE
.PP
will match any request, whose URL \fIdoes not\fR begin with "/static/".
.PP
Negating compound statements is allowed as well, e.g.:
.PP
.EX
Not ACL
   "192.0.2.0/26"
   "203.0.113.0/24"
End
.EE
.SS Match statement
A \fBMatch\fR statement allows you to group matching directives using
arbitrary boolean operations.  The syntax is:
.PP
.EX
Match \fIOP\fR
  \fIdirectives\fR...
End
.EE
.PP
where \fIOP\fR is \fBAND\fR to use boolean and, and \fBOR\fR
(case-insensitive) to use boolean \fIor\fR, and \fIdirectives\fR stand for
any number of matching directives discussed above (including the
\fBMatch\fR directive).
.PP
Prefixing \fBMatch\fR directive with a word \fBnot\fR reverts its result.
.PP
\fBMatch\fR directives can be nested to any depth.
.PP
Technically, an implicit \fBMatch AND\fR block is created around
unenclosed matching directives on the top level of a \fBService\fR block.
.SS Modification directives
The following directives modify the incoming request prior to passing
it to the selected backend.  These are discussed in detail
in the section
.BR "REQUEST MODIFICATION" ,
below.
.TP
\fBDeleteHeader\fR "\fIheader\fB: \fIpattern\fR"
Remove matching headers from the incoming requests.
.TP
\fBSetHeader\fR "\fIheader\fB: \fIvalue\fR"
Add the defined header to the request passed to the backend
server.
.TP
\fBSetURL\fR "\fIvalue\fR"
Sets the URL part of the request.
.TP
\fBSetPath\fR "\fIvalue\fR"
Sets the path part.
.TP
\fBSetQuery\fR "\fIvalue\fR"
Sets the query part.
.TP
\fBSetQueryParam\fR "\fIname\fR" "\fIvalue\fR"
Modifies the query.  Sets the query parameter \fIname\fR to \fIvalue\fR.
.TP
.BR Rewrite " [" request | response "] ... [ " Else " ... ] " End
Conditionally modify request or response depending on whether it
matches certain conditions.  If the argument is omitted, \fBrequest\fR
is assumed.
.IP
Request modification is described in detail in section
.B "REQUEST MODIFICATION DIRECTIVES" .
.IP
Response modification is covered by section
.BR "RESPONSE MODIFICATION" .
.SS Backend definitions
.TP
\fBBalancer\fR \fBrandom\fR | \fBiwrr\fR
Defines the load-balancing strategy to use.  Possible arguments are:
\fBrandom\fR, to use weighted random balancing algorithm. an
\fBiwrr\fR, meaning interleaved weighted round robin balancing.
See
.BR "REQUEST BALANCING" ,
above, for a detailed discussion of these balancing strategies.
.IP
This directive overrides the \fBBalancer\fR directive in global scope.
.TP
\fBBackend\fR
Directives enclosed between
.B Backend
and
the following
.B End
directives define a single backend server (see below for details). You
may define multiple backends per service, in which case
.B pound
will attempt to load-balance between them.
.TP
.B Control
Enables a special \fBcontrol backend\fR -- a management interface that
returns information about the running \fBpound\fR server, makes it
possible to change state of configured listeners, services and
backends, and provides other management facilities.  The management
interface is discussed in detail in
section
.BR "Control socket" ,
above.  The \fBControl\fR backend provides remote access to this
interface.  Be careful to properly protect the control interface
by use of HTTPS, ACLs and/or basic authorization, e.g.:
.IP
.RS
.EX
ListenHTTPS
    Address 192.0.2.1
    Port 443
    Cert "/etc/ssl/priv/example.pem"

    Service
        Not BasicAuth "pound/htpasswd"
        Rewrite response
            SetHeader "WWW-Authenticate: Basic realm=\"Restricted access\""
        End
        Error 401
    End

    Service
        ACL "secure"
        Control
    End
End
.EE
.RE
.TP
\fBRedirect\fR [\fIcode\fR] "\fIurl\fR"
This is a special type of backend. Instead of sending the request to a backend
.B pound
replies immediately with a redirection to the given URL.
.IP
It is allowed to define multiple redirectors in a service, as well as
mixing them with regular backends, but there is little if any
justification for such usage, so it is deprecated.
.IP
Optional \fIcode\fR can be one of:
.BR 301 ,
.B 302
(the default),
.BR 303 ,
.BR 307 ,
or
.BR 308 .
.IP
The redirection destination is determined by the actual
.I url
you specify.  It is expanded as described in \fBString expansion\fR
above.
.IP
For compatibility with previous \fBpound\fR versions, if no
\fB$\fIN\fR references are found in
.IR url ,
the following logic is used:
if it is a "pure" host (i.e. with no path) then the client will be
redirected to the host you specified, with the original request path
appended. If your
.I url
does contain a path, then the request path is ignored.
.IP
Examples: the following swaps the first two path components of the
original URL:
.IP
.EX
Service
    Host -re "(.+)"
    URL "^/([^/]+)/([^/]+)(/.*)?"
    Redirect "http://$0(1)/$2/$1$3"
End
.EE
.IP
Notice the use of \fBHost\fR to supply hostname part for the redirect.
.IP
Using request accessors, the above example can be rewritten as:
.IP
.EX
Service
    URL "^/([^/]+)/([^/]+)(/.*)?"
    Redirect "http://%[header host]/$2/$1$3"
End
.EE
.IP
Compatibility syntax: if you specified
.IP
.EX
Redirect "http://abc.example"
.EE
.IP
and the client requested
.I http://xyz/a/b/c
then it will be redirected to
.IR "http://abc.example/a/b/c" ,
but if you specified
.IP
.EX
Redirect "http://abc.example/index.html"
.EE
.IP
it will be sent to
.IR "http://abc.example/index.html".
.TP
\fBError \fISTATUS\fR [\fIFILE\fR]
Special case of backend that returns HTTP error page.  The \fISTATUS\fR
argument supplies HTTP status code.  Optional \fIFILE\fR argument is
the name of a disk file with the error page content (HTML).  If not
supplied, the text is determined as usual: first the
.BI ErrorFile " STATUS"
statement for the enclosing listener is consulted.  If it is not present, the
default error page is used.
.IP
The \fBError\fR directive is useful in a catch-all service, which
outputs an error page if no service matching the incoming request was
found.  See the \fBEXAMPLES\fR section for details.
.TP
\fBEmergency\fR
Directives enclosed between
.B Emergency
and the following
.B End
directives define an emergency backend server (see below for
details). You may define any number of emergency servers.  A backend
will be selected from emergency backends if all regular backends are down.
.TP
.B Metrics
Special backend type that implements Openmetrics protocol output.  See
the section
.B Metrics
below for a detailed discussion.
.TP
\fBSession\fR
Directives enclosed between
.B Session
and
the following
.B End
directives define a session-tracking mechanism for the current
service. See below for details.
.SS Other directives
.TP
\fBIgnoreCase\fR \fIbool\fR
Override the global
.B IgnoreCase
setting.
.IP
This statement is deprecated and will be removed in future versions.
Please, use the \fB\-icase\fR option to the \fBURL\fR directive
instead.  See the discussion of \fIoptions\fR in
.B Service Matching Directives
section above.
.TP
\fBDisabled\fR \fIbool\fR
Start
.B pound
with this service disabled (\fItrue\fR) or enabled (\fIfalse\fR). If
started as disabled, the service can be later enabled with
.BR poundctl (8).
.TP
\fBForwardedHeader\fR \fIname\fR
Defines the name of the HTTP header that carries the list of proxies
the request has passed through.  It is used to report the originator
IP address when logging.  See the description of
.B %a
specifier in
.BR "REQUEST LOGGING" .
This statement overrides the \fBForwardedHeader\fR directive from the
listener scope.
.IP
The default is
.BR X\-Forwarded\-For .
.TP
.B TrustedIP
Defines a list of
.I trusted proxy
IP addresses, which is used to determine the originator IP.  See the
description of
.B %a
specifier in
.BR "REQUEST LOGGING" ,
for a detailed discussion.
.IP
This statement overrides the \fBTrustedIP\fR directive from the
listener scope.
.TP
.BI LogSuppress " class"
Suppresses HTTP logging for requests that resulted in status codes
from the specified
.IR class .
Valid status classes are:
.IP
.RS
.TP
.IR info " or " 1
.I 1xx
response codes.
.TP
.IR success " or " 2
.I 2xx
response codes.
.TP
.IR redirect " or " 3
.I 3xx
response codes.
.TP
.IR clterr " or " 4
.I 4xx
response codes.
.TP
.IR srverr " or " 5
.I 5xx
response codes.
.TP
.I all
All response codes.
.RE
.IP
Multiple arguments are allowed.
.IP
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.  See the \fBMetric\fR section below for
an example.
.SH "ACME"
This statement creates a \fIservice\fR specially crafted for answering
ACME HTTP-01 challenge requests (see
.BR https://letsencrypt.org/docs/challenge-types/#http-01-challenge ).
It takes a single argument specifying a directory where ACME
challenges are stored. The argument is subject to string expansion
(see the subsection \fBString expansion\fR, above).
.PP
It is supposed that another program is started
periodically, which checks for certificates approaching their
expiration, issues renewal requests and stores the obtained ACME
challenges in that directory.
.SH "Backend"
A backend is a definition of a single backend server
.B pound
will use to reply to incoming requests.  Backends are defined via
a
.B Backend
statement.  There are two forms of this statement:
.I service-specific
and
.I global
(or
.IR named )
backend.  These will be discussed later in this section.
All configuration directives enclosed between
.B Backend
and
.B End
are specific to a single backend.

The following directives are available:
.TP
\fBAddress\fR \fIaddress\fR
The address that
.B pound
will connect to. This can be a numeric IP address, a symbolic host name
that must be resolvable at run-time, or a full pathname of a UNIX
socket. If the name cannot be resolved to a valid address,
.B pound
will assume that it represents the path for a Unix-domain socket. This is a
.B mandatory
parameter.
.TP
\fBPort\fR \fIport\fR
The port number or service name that
.B pound
will connect to. This is a
.B mandatory
parameter for non Unix-domain backends.
.TP
\fBHTTPS\fR
The backend is using HTTPS.
.TP
\fBServerName\fR "\fIname\fR"
Specify the name to use for server name identification (\fBSNI\fR).
This directive also rewrites the \fBHost:\fR header for this
particular backend.  This means you don't have to use \fBSetHeader\fR
in addition to it.
.IP
This directive may appear only after the \fBHTTPS\fR directive.
.TP
\fBCert\fR "\fIfilename\fR"
Specify the certificate that
.B pound
will use as a client. The
.I filename
is the file containing the certificate, possibly a certificate chain
and the signature.
This directive may appear only after the
.B HTTPS
directive.
.TP
\fBDisable\fR SSLv2|SSLv3|TLSv1|TLSv1_1|TLSv1_2
Disable the protocol \fBand all lower protocols as well\fR.
This is due to a limitation in OpenSSL, which does not support
disabling a single protocol. For example,
.B Disable TLSv1
would disable SSLv2, SSLv3 and TLSv1, thus allowing only TLSv1_1 and TLSv1_2.
This directive may appear only after the
.B HTTPS
directive.
.TP
\fBCiphers\fR "\fIcipherlist\fR"
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
.BR ciphers (1)
and
.BR SSL_CTX_set_cipher_list (3).
This directive may appear only after the
.B HTTPS
directive.
.TP
\fBPriority\fR \fIn\fR
The priority of this backend. Higher priority backends will be used
more often than lower priority ones, so you should define higher
priorities for more capable servers. Exact scheduling and allowed
values for this keyword depend on the load balancing strategy in use
(see the section
.BR "REQUEST BALANCING" ,
above).  For
.IR "weighted random balancing" ,
allowed values for
.B Priority
are between 0 and 9, inclusive.  For
.IR "interleaved weighted round robin balancing" ,
allowed range is 0 to 65535, inclusive.
.IP
Default value is 5.
.TP
\fBTimeOut\fR \fIn\fR
Override the global
.B TimeOut
value.
.TP
\fBConnTO\fR \fIn\fR
Override the global
.B ConnTO
value.
.TP
\fBWSTimeOut\fR \fIn\fR
Override the global
.B WSTimeOut
value.
.TP
\fBDisabled\fR \fIbool\fR
Start
.B pound
with this backend disabled (1) or enabled (0). If started as disabled, the
backend can be later enabled with
.BR poundctl (8).
.SS Dynamic backends
Dynamic backends are created and updated on the fly based on the
information from DNS.  A backend is declared as dynamic by the
.B Resolve
statement.  Its value defines what type of DNS record is used to
generate dynamic backends:
.TP
.B first
Resolve the symbolic host name from the \fBAddress\fR directive and
use first IP from the DNS response as the address of the created dynamic
backend.  Thus, at most one dynamic backend will be produced.
.TP
.B all
Resolve the symbolic host name from the \fBAddress\fR directive 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.
.TP
.B srv
Obtain SRV records for the host name and use them to generate
backends.  Each record produces new dynamic backend of the
.B Resolve all
type, which produces regular backends as described above.  The weight field
of the SRV record is mapped to the priority field of each generated
backend.  The SRV priority field identifies the balancer group where
the backend will be hosted.
.PP
The following directives further configure dynamic backends:
.TP
\fBFamily any \fR|\fB inet \fR|\fB inet6
Selects the family of the addresses to look for:
.RS
.TP
.B any
Use all address families available.  This is the default.
.TP
.B inet
Use only IPv4 addresses (\fBA\fR DNS RRs).
.TP
.B inet6
Use only IPv6 addresses (\fBAAAA\fR DNS RRs).
.RE
.TP
\fBIgnoreSRVWeight \fIbool\fR
When using \fBSRV\fR records, ignore their \fIweight\fR fields and
assign priorities for the generated backends from the priority of
the producing backend.

This directive is valid when used together with
.BR "Resolve srv" .
.TP
.BI OverrideTTL " N"
Query DNS each \fIN\fR seconds for possible changes in configuration
of the existing dynamic backends.  If this statement is not used, the
TTL value returned with the DNS response will be used instead.
.TP
.BI RetryInterval " N"
Retry failed DNS queries each \fIN\fR seconds.  Default is 600.
.SS Global and per-service backends
A
.B Backend
definition can appear as a part of the service, i.e. in a
.B Service
section.
or globally.  In the latter case, the
.B Backend
keyword must be followed by a symbolic name assigned to this backend, e.g.:
.PP
.EX
Backend "name"
  ...
End
.EE
.PP
This name must uniquely identify the backend among other globally
defined backends.  A global backend is attached to a service using
the
.B UseBackend
statement.  It takes the symbolic name of the backend as its argument.
The statement
.PP
.EX
UseBackend "name"
.EE
.PP
has essentially the same effect as if full backend definition appeared
instead of it in this place.  A substantial difference between the use
of service-specific and global backends is that a single global
backend can be used in multiple services.  In a way,
.B UseBackend
statement
.I expands
to a backend definition within the service.
.PP
Furthermore, you can
also adjust the \fBPriority\fR and \fBDisabled\fR parameters of the
global backend definition for use in a particular service.  To do
so, use the following syntax:
.PP
.EX
Backend "name"
  Priority 3
  Disabled no
End
.EE
.PP
In this form, the
.B Backend
statement acts as
.BR UseBackend .
Two directives can appear within such
.B Backend
statement:
.BR Priority ,
and
.BR Disabled .
They override the settings defined in the global backend "\fIname\fR".
.PP
Notice, that in spite of their similarity, the two
.I named
forms of the
.B Backend
statement serve different purposes: when used in global scope, a named
.B Backend
.I defines
a backend for further use in various services, and when used
within a service, it
.I creates a copy
of the backend defined elsewhere and
.I attaches
it to this service.
.PP
The actual global definition may appear before as well as after
service or services it is used in.
.SH "Resolver"
The \fBResolver\fR section controls DNS lookups for dynamic backend
generation (see above).  It can contain the following directives:
.TP
.BI CNAMEChain " N"
Maximum allowed length of a \fICNAME chain\fR.  CNAME chains are
formed by DNS CNAME records pointing to another CNAME.  Although
prohibited by the RFC, such usage does occur sometimes.  By default,
.B pound
does not accept CNAME chains.  If you work with nameserver that
returns them, set this statement to a small integer value, defining
maximum number of CNAMEs in the chain that can be accepted.  The value
of 2 or 3 should suffice in most cases.
.TP
\fBConfigFile\fR "\fIFILE\fR"
Read the resolver configuration from \fIFILE\fR, instead of the
default \fB/etc/resolv.conf\fR.
.TP
\fBConfigText\fR ... \fBEnd\fR
Alternative way to supply resolver configuration.  The material within
this section is read verbatim and used as the content of the resolver
configuration file.
.IP
If both
.B ConfigFile
and
.B ConfigText
are used, the last used statement wins.
.TP
.BI debug " bool"
Whether to enable DNS debugging info.
.TP
.BI 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.
.SH "Emergency"
Emergency servers will be used once all existing backends are "dead".
All configuration directives enclosed between
.B Emergency
and
.B End
are specific to a single service.  For the list of directives allowed
for use in
.B Emergency
sections, refer to the description of
.BR Backend .
.SH "Session"
Defines how a service deals with possible HTTP sessions.  All configuration
directives enclosed between
.B Session
and
.B End
are specific to a single service. Once a session is identified,
.B pound
will attempt to send all requests within that session to the same backend
server.
.PP
The following directives are available:
.TP
\fBType\fR IP|BASIC|URL|PARM|COOKIE|HEADER
What kind of sessions are we looking for: IP (the client address), BASIC (basic
authentication), URL (a request parameter), PARM (a URI parameter), COOKIE (a
certain cookie), or HEADER (a certain request header).
This is a
.B mandatory
parameter.
.TP
\fBTTL\fR \fIn\fR
How long can a session be idle (in seconds). A session that has been idle for
longer than the specified number of seconds will be discarded.
This is a
.B mandatory
parameter.
.TP
\fBID\fR "\fIname\fR"
The session identifier. This directive is permitted only for sessions of type
URL (the name of the request parameter we need to track), COOKIE (the name of
the cookie) and HEADER (the header name).
.PP
See below for some examples.
.SH Metrics
The following service definition enables Openmetric telemetry output
on endpoint
.BR /metrics:
.PP
.EX
Service
    URL "/metrics"
    Metrics
End
.EE
.PP
To control access to the telemetry endpoint, use the
.B ACL
statement.
.PP
The \fBLogSuppress\fR directive can be used in openmetric
services to suppress logging of served HTTP requests.
.PP
For example:
.PP
.EX
Service
    URL "/metrics"
    Metrics
    ACL "secure"
    LogSuppress success
End
.EE
.PP
The metrics output is sufficiently self-documented by
.B # HELP
descriptor lines.
.SH HIGH-AVAILABILITY
.B Pound
attempts to keep track of active backend servers, and will temporarily disable
servers that do not respond (though not necessarily dead: an overloaded server
that
.B pound
cannot establish a connection to will be considered dead). However, every
.B Alive
seconds, an attempt is made to connect to the dead servers in case
they have become active again. If this attempt succeeds, connections
will be initiated to them again.
.PP
In general it is a good idea to set this time interval as low as is
consistent with your resources in order to benefit from resurrected
servers at the earliest possible time. The default value of 30 seconds
is probably a good choice.
.PP
The clients that happen to hit a dead backend server will just receive a
.I "503 Service Unavailable"
message.
.SH REQUEST MODIFICATION DIRECTIVES
Several statements are provided to modify the incoming requests prior
to passing them to the backend.  These statements can be present both in
.B ListenHTTP
.RB ( ListenHTTPS )
and in
.B Service
sections.
.PP
Basic request modification directives are:
.TP
\fBSetURL\fR "\fIvalue\fR"
Set the URL of the incoming request to \fIvalue\fR.
.TP
\fBSetPath\fR "\fIvalue\fR"
Set the path part of the URL to the given string.
.TP
\fBSetQuery\fR "\fIvalue\fR"
Set the query part of the URL to the given string.  \fIvalue\fR must be
a valid query with the special characters properly encoded using
percent encoding.
.TP
\fBSetQueryParam\fR "\fIname\fR" "\fIvalue\fR"
Set the query parameter \fIname\fR to the \fIvalue\fR.  Value must be
properly encoded if it contains reserved characters.
.TP
\fBSetHeader\fR "\fIname\fB: \fIvalue\fR"
Sets the HTTP header.  If the header \fIname\fR already exists, it
will be overwritten.  Otherwise, new header will be added to the end
of the header list.
.TP
\fBDeleteHeader\fR [\fIoptions\fR] "\fIpattern\fR"
Remove from the request all headers matching \fIpattern\fR.  By
default, \fIpattern\fR is treated as extended POSIX regular
expression.  The \fIoptions\fR argument can be used to change this
behavior.  It consists of zero or more option flags from the following list:
.RS
.TP
.B \-beg
Exact match at the beginning of string (prefix match).
.TP
.B \-case
Case-sensitive comparison.
.TP
.B \-contain
Match substring.
.TP
.B \-end
Exact match at the end of string (suffix match).
.TP
.B \-exact
Use exact string matching.
.TP
.B \-icase
Case-insensitive comparison.
.TP
.BR \-pcre " or " \-perl
Use Perl-compatible regular expression (requires compilation-time
support).  This overrides global
.B RegexType
settings.
.TP
.B \-posix
Use POSIX extended regular expression.  This overrides global
.B RegexType
settings.
.TP
.B \-re
Use regular expression matching, as set by the
.B RegexType
statement.
.RE
.PP
The \fIvalue\fR argument in the above directives is subject to
string expansion. Refer to subsection \fBString expansions\fR, for
details.
.PP
The
.B Rewrite
block statement is used to associate one or more of the above
directives with request matching directives (discussed in the subsection
.B Service Matching Directives
above), so that request modification takes place only when the request
matches certain conditions.
.PP
Syntactically, a
.B Rewrite
block is:
.PP
.EX
.BR Rewrite " [" request "]"
\&.
\&.
\&.
.B Else
\&.
\&.
\&.
.B End
.EE
.PP
where dots stand for any number of request matching and request
modification statements.  The \fBElse\fR part is optional; any number
of \fBElse\fR blocks can be supplied, thus providing for conditional branching.
The following concocted example illustrates it:
.PP
.EX
Rewrite
   Path "\\.(jpg|gif)$"
   SetPath "/images%[path]"
Else
   Match AND
     Host "example.org"
     Path "\\.[^.]+$"
   End
   SetPath "/static%[path]"
Else
   Path "\\.[^.]+$"
   SetPath "/assets%[path]"
End
.EE
.PP
Here, if a path ends with a filename with suffix ".jpg" or ".gif",
"/images" is prepended to it (notice that path always starts with
a slash, hence it should not be used explicitly).  If the path ends
with any other extension, the action depends on the host being
addressed.  The path is prefixed with "/static" if the host is
"example.org", and with "/assets" otherwise.
.PP
To illustrate the effects of string expansion, here's the the above
example rewritten using backreference expansion instead of request
accessors:
.PP
.EX
Rewrite
   Path ".*\\.(jpg|gif)$"
   SetPath "/images$0"
Else
   Match AND
     Host "example.org"
     Path ".*\\.[^.]+$"
   End
   SetPath "/static$0"
Else
   Path ".*\\.[^.]+$"
   SetPath "/assets$0"
End
.EE
.PP
Request modification directives from
.B ListenHTTP
(or
.BR ListenHTTPS )
section are applied first, followed by directives from the
.B Service
section.  Directives appearing within a single section are
applied in the same order as they appear in the configuration file.
.SH BUILT-IN HEADERS
In addition to the \fBSetHeader\fR and \fBDeleteHeader\fR directives
discussed above, the \fBHeaderOption\fR directive controls insertion
of the built-in headers:
.TP
\fBHeaderOption\fR \fIopt\fR...
.PP
There are two kinds of such headers: \fIforwarded\fR headers that
convey information about original destination of the request, and
\fIssl\fR headers (for \fBHTTPS\fR connections), that hold information
about server and client SSL certificates.  These are discussed in detail below.
.PP
By default, both kinds of built-in additional headers are enabled.
This default can be changed by using the \fBHeaderOption\fR directive.
Placed in global scope, this directive sets global options.  Used
within a \fBListenHTTP\fR or \fBListenHTTPS\fR block, it affects only
settings for that listener.
.PP
The \fIopt\fR values passed to the directive are:
.TP
.B none
Disable both kinds of additional headers.
.TP
.B forwarded
Enable forwarded headers.
.TP
.B no\-forwarded
Disable forwarded headers.
.TP
.B ssl
Enable ssl headers.
.TP
.B no\-ssl
Disable ssl headers.
.PP
The built-in headers are added before request modification directives
are applied.  Thus, you can use
.B DeleteHeader
and
.B SetHeader
to trim down headers added by
.BR HeaderOptions .
.SS Forwarded Headers
The headers in the \fIforwarded\fR header group are:
.TP
.B X\-Forwarded\-For
The IP address of the HTTP client that sent the request,
.TP
.B X\-Forwarded\-Proto
The protocol (\fBhttp\fR or \fBhttps\fR) that the client used to
connect to
.BR pound .
.TP
.B X\-Forwarded\-Port
Destination port that the client used to connect to
.BR pound .
.SS HTTPS Headers
If a client browser connects to
.B pound
via HTTPS and the \fIssl\fR header group is enabled, then the
following header is added:
.TP
.B X\-SSL\-Cipher
Contains SSL version followed by a slash and active cipher algorithm.
.PP
Additionally, if the client presented its certificate,
the following headers are added that describe the client certificate:
.TP
.B X\-SSL\-Subject
Details about the certificate owner.
.TP
.B X\-SSL\-Issuer
Details about the certificate issuer (Certificate Authority).
.TP
.B X\-SSL\-NotBefore
Starting date of certificate validity.
.TP
.B X\-SSL\-NotAfter
Ending date of certificate validity.
.TP
.B X\-SSL\-Serial
Certificate serial number (decimal).
.TP
.B X\-SSL\-Certificate
The full client certificate (PEM-format multi-line)
.SH RESPONSE MODIFICATION
Headers in the response obtained from a regular backend or generated
with a \fBError\fR backend can be modified before sending them back to
the requesting server.  A special form of the \fBRewrite\fR directive
is provided for this purpose:
.PP
.EX
.B Rewrite response
\&.
\&.
\&.
.B Else
\&.
\&.
\&.
.B End
.EE
.PP
where dots stand for any number of response matching and modification
statements.  The \fBElse\fR part is optional; any number
of \fBElse\fR blocks can be supplied, thus providing for conditional
branching.
.PP
This directive can be used in
.BR ListenHTTP ,
.BR ListenHTTPS ,
and
.B Service
definitions.
.PP
Response modification directives from the
.B Service
section are applied first, followed by directives from the
.B ListenHTTP
(or
.BR ListenHTTPS )
section.  Directives appearing within a single section are
applied in the same order as they appear in the configuration file.
.PP
Response matching statements are:
.TP
\fBHeader\fR [\fIoptions\fR] "\fIpattern\fR"
Matches if the response contains at least one header matching the given
\fIpattern\fR.
.TP
\fBStringMatch\fR "\fIstring\fR" [\fIoptions\fR] "\fIpattern\fR"
Expand \fIstring\fR as described in \fBString expansion\fR (see below)
and match the resulting value against \fIpattern\fR.
.IP
By default, \fIpattern\fR is treated as
case-insensitive extended regular expression.  This can be changed by
\fIoptions\fR, as described in
section
.BR "Service Matching Directives" ,
above.
.TP
.B Match
The \fBMatch\fR statement is as described in section
.BR "Match statement" ,
except that only directives described above are allowed within it.
.TP
.B Not
Placed before any of the above directives, reverts its result.
.PP
Following \fIresponse modification\fR statements are defined:
.TP
\fBDeleteHeader\fR "\fIheader\fB: \fIpattern\fR"
Remove matching headers from the response.
.TP
\fBSetHeader\fR "\fIheader\fB: \fIvalue\fR"
Add header to the response.  Argument
undergoes string expansion as described above. The expanded value must
be a valid header line.
.SH MULTI-VALUE HEADERS
HTTP protocol allows for certain headers to appear in the message
multiple times.  Namely, multiple headers with the same header name
are permitted if that header field is defined as a comma-separated
list.  The standard specifies that such fields can be combined in
a single \fIheader: value\fR pair, by appending each subsequent field
value to the previous one, each separated by a comma.
.PP
.B Pound
is able to perform such combining both on incoming requests and on
responses.  To enable this feature, declare names of headers
that can be combined using the
.B CombineHeaders
section statement.  This statement must be followed by header names,
each on a separate line, and terminated with an
.B End
statement.  E.g.:
.PP
.EX
CombineHeaders
    "Accept"
    "Allow"
    "Forwarded"
End
.EE
.PP
You can also store header names in a file, and include that file after
.BR CombineHeaders ,
e.g.:
.PP
.EX
CombineHeaders
    Include "multivalue.txt"
End
.EE
.SH BASIC AUTHENTICATION
To limit access to a service or services to certain authenticated
users, use a combination of \fBBasicAuth\fR matching and response
modification.
.PP
The \fBBasicAuth\fR matching directive evaluates to true, if the
incoming request contains Authorization header with scheme "Basic",
such that user name and password obtained from it match a line in the
given disk file.  The file must be a plain-text file created with
.BR htpasswd (1)
or similar utility, i.e. each non-empty line of it must contain
username and password hash separated by a colon.  Password hash can be
one of:
.nr step 1 1
.IP \n[step].
Password in plain text.
.IP \n+[step].
Hash created by the system
.BR crypt (3)
function.
.IP \n+[step].
Password hashed using SHA1 algorithm and encoded in base64.
This hash must be prefixed by
.BR {SHA} .
.IP \n+[step].
Apache-style \fIapr1\fR hash.
.PP
Combined with the response rewriting described above, this can be
used to implement basic HTTP authentication in
.B Pound
as shown in the following example:
.PP
.EX
  Service "auth"
      Not BasicAuth "/etc/pound/htpass"
      Rewrite response
          SetHeader "WWW-Authenticate: Basic realm=\\"Restricted access\\""
      End
      Error 401
  End
.EE
.PP
Placing this service definition before others ensures that services
defined below it will be tried only if the incoming request passes
basic authentication.
.SH REQUEST LOGGING
Logging of HTTP requests and responses is controlled by
.B LogLevel
directive.  This directive can appear either in global scope, in which
case it affects all listeners defined below it, or in listener scope,
in which case it affects only this listener, overriding the global
setting.
.PP
Argument to the
.B LogLevel
directive can be either an integer number in range 0 through 5
(inclusive), or a quoted string.  Numeric value identifies one of
the
.I built-in
log formats, described later in this section.  String value refers
either to a built-in format name, or to a user-defined format name.
In the latter case, the named format must be defined earlier using the
.B LogFormat
statement.
.SS Format specification
The syntax of the
.B LogFormat
statement is:
.PP
.EX
LogFormat "\fIname\fR" "\fIformat_string\fR"
.EE
.PP
First argument, \fIname\fR, is a unique identifier for this format,
which will be used later to refer to it.  \fIFormat_string\fR is
a character string composed of ordinary characters (not \fB%\fR),
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.
.PP
Conversion specifications are single characters prefixed with a
percent sign.  Depending on the specification, an optional
\fIconversion argument\fR in curly brackets may appear between
\fB%\fR and conversion character.
.PP
The following conversion characters are defined:
.TP
.B %%
Replaced with the percent sign.
.TP
.B %a
Originator IP address of the request.  If the request contains
the \fBX\-Forwarded\-For\fR header and \fBTrustedIP\fR 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
useragent IP addresses.  To determine the actual useragent IP, the
list is traversed from right to left, until an IP is found that is not
listed in \fBTrustedIP\fR ACL.
.IP
If \fBX\-Forwarded\-For\fR header is not present, or \fBTrustedIP\fR
is not defined, or the above algorithm does not return an IP address,
\fB%a\fR expands to the actual remote IP address the request came from
(same as \fB%h\fR).
.IP
The \fBTrustedIP\fR ACL can be defined in global scope, or in
\fBListenHTTP\fR (\fBListenHTTPS\fR) section, or in \fBService\fR
section.  Most-specific ACL overrides least-specific ones, that is
\fBTrustedIP\fR defined in \fBService\fR will be used, if it is
defined.  If not, the one defined in listener will be used, etc.
The syntax of the \fBTrustedIP\fR statement is the same as that of
\fBACL\fR, i.e.
.IP
.RS
.EX
TrustedIP "\fIname\fR"
.EE
.RE
.IP
refers to the named ACL \fIname\fR (which must be defined earlier),
and
.IP
.RS
.EX
TrustedIP
  "\fICIDR0\fR"
  "\fICIDR1\fR"
  ...
End
.EE
.RE
.IP
defines the list of trusted IPs in place.
.IP
\fBForwardedHeader\fR statement defines the name of the header to use
instead of \fBX\-Forwarded\-For\fR.  As \fBTrustedIP\fR, this
statement can appear in global, listener, or in service scope.
.TP
.B %A
Local IP address of the listener.
.TP
.B %B
Size of response in bytes, excluding headers.
.TP
.B %b
Same as \fB%B\fR, but in \fICLF\fR format, i.e. a dash is used when
response size is zero.
.TP
.B %D
The time taken to serve the request, in microseconds.
.TP
.B %h
Client IP address of the request.
.TP
.B %H
The request protocol.
.TP
.BI %{ VARNAME }i
The contents of \fIVARNAME:\fR header line in the request.  Changes
made by header modification directives affect this.
.TP
.BI %{ VARNAME }I
Same as \fB%i\fR, except that if no such header is present in the
request, a dash is substituted.
.TP
.BI %{ OBJNAME }L
Location of the
.B Pound
object that is involved in handling the request.  Valid values for
.I OBJNAME
are:
.BR listener ,
.BR service ,
and
.BR backend .
The location gives position in the configuration file where the object
was defined, and is formatted as
.IP
.EX
.IR NAME : LN1 . COL1 - LN2 . COL2
.EE
.IP
where
.I NAME
is the configuration file name,
.I LN1
and
.I COL1
are number of line and column where the object definition begins,
and
.I LN2
and
.I COL2
are number of line and column where it ends.  Line and column numbers
start with 1.
.TP
.B %m
The request method.
.TP
.BI %{ OBJNAME }N
Name of the
.B Pound
object that is involved in handling the request.  Valid values for
.I OBJNAME
are:
.BR listener ,
.BR service ,
and
.BR backend .
.TP
.B %P
Thread ID of the serving thread.
.TP
.B %q
The query string prepended with a \fB?\fR if it exists, otherwise an
empty string.
.TP
.B %r
First line of request.
.TP
.B %s
Response status code.
.TP
.B %>s
First line of the response.
.TP
.B %t
Time the request was received, in the format
.BR "[18/Sep/2011:19:18:28 -0400]" .
The last number indicates the timezone offset from UTC.
.TP
.B %{format}t
Time the request was received, in the format specified by the argument
.RB ( strftime (3)).
If the format starts with \fBbegin:\fR (default) the time is taken at
the beginning of the request processing.  If it starts with \fRend:\fR
it is the time after the response from the backend has been sent back
to the requester.  In addition to
.BR strftime (3)
formats, the following specifications are recognized:
.RS
.RE
.TP
.B sec
Number of seconds since the Epoch.
.TP
.B msec
Number of milliseconds since the Epoch.
.TP
.B usec
Number of microseconds since the Epoch.
.TP
.B msec_frac
Millisecond fraction of the time.
.TP
.B usec_frac
Microsecond fraction of the time.
.RE
.TP
.B %T
The time taken to process the request, in seconds.
.TP
.BI %{ UNIT }T
The time taken to process the request, in a time unit given by
\fIUNIT\fR.  Valid units are \fBms\fR for milliseconds, \fBus\fR for
microseconds, \fBs\fR for seconds, and \fBf\fR for seconds with
fractional part.  Using \fBs\fR gives the same result as \fB%T\fR
without any format; using \fBus\fR gives the same result as \fB%D\fR.
.TP
.B %u
Remote user if the request was authenticated.
.TP
.B %U
The URL path requested.  This is affected by request modification
directives.
.TP
.B %v
The listener name.
.SS Built-in formats
There are five built-in formats.  These can be identified either by
their numeric index in the format table, or by symbolic name.  The
table below describes each built-in format using the format
specification string:
.TP
.BR 0 ", " null
No request logging at all.
.TP
.BR 1 ", " regular
.EX
"%a %r \- %>s"
.EE
.TP
.BR 2 ", " extended
.EX
"%a %r \- %>s (%{Host}i/%{service}N \-> %{backend}N) %{f}T sec"
.EE
.TP
.BR 3 ", " vhost_combined
(Split in two lines for readability)
.EX
"%{Host}I %a - %u %t \(rs\(dq%r\(rs\(dq %s %b \(rs\(dq%{Referer}i\(rs\(dq \(rs
\(rs\(dq%{User\-Agent}i\(rs\(dq"
.EE
.TP
.BR 4 ", " combined
.EX
"%a \- %u %t \(rs\(dq%r\(rs\(dq %s %b \(rs\(dq%{Referer}i\(rs\(dq \(rs\(dq%{User\-Agent}i\(rs\(dq"
.EE
.TP
.BR 5 ", " detailed
(Split in two lines for readability)
.EX
"%{Host}I %a - %u %t \(rs\(dq%r\(rs\(dq %s %b \(rs\(dq%{Referer}i\(rs\(dq \(rs
\(rs\(dq%{User\-Agent}\(rs\(dq (%{service}N \-> %{backend}N) %{f}T sec"
.EE
.SH SECURITY
.PP
In general,
.B pound
does not read or write to the hard-disk. The exceptions are reading
the configuration file and (possibly) the server certificate file(s)
and error message(s), which are opened read-only on startup, read, and
closed, and the pid file which is opened on start-up, written to and
immediately closed. Following this there is no disk access whatsoever,
so using a \fBRootJail\fR directive is only for extra security bonus points.
.PP
.B Pound
tries to sanitize all HTTP/HTTPS requests: the request itself, the
headers and the contents are checked for conformance to the RFCs and
only valid requests are passed to the backend servers. This is not
absolutely fool-proof - as the recent Apache problem with chunked
transfers demonstrated. However, given the current standards, this is
the best that can be done - HTTP is an inherently weak protocol.
.SH DEPRECATED FEATURES
.SS Configuration statements
The following configuration statements are retained for backward
compatibility with earlier
.B pound
versions.  They will disappear from future releases:
.TP
.B HeadRequire
Use
.B Header
instead.  See
.BR "Service Matching Directives" ,
for details.
.TP
.B HeadDeny
Use
.BR "Not Header" .
For details, see the
.B Negation
subsection in
.BR "Service Matching Directives" .
.TP
.BR AddHeader " and " HeaderAdd
Use
.B SetHeader
instead.  See the section
.BR "REQUEST MODIFICATION DIRECTIVES" ,
for details.
.TP
.BR HeaderRemove " and " HeadRemove
Use
.B DeleteHeader
instead. See the section
.BR "REQUEST MODIFICATION DIRECTIVES" ,
for details.
.TP
.B IgnoreCase
Use the \fB\-icase\fR option to the \fBURL\fR directive
instead.  See the discussion of \fIoptions\fR in the
.B Service Matching Directives
section.
.TP
.BI Err NNN
(where \fINNN\fR is one of:
.BR 400 ,
.BR 401 ,
.BR 403 ,
.BR 404 ,
.BR 413 ,
.BR 414 ,
.BR 500 ,
.BR 501 ,
.BR 503 )
.IP
Use the \fBErrorFile\fR directive, described in the section
.BR HTTP Listener ,
above.
.SS Redirect request hack
The use of the \fIredirect request\fR hack in the \fBRedirect\fR
statement is deprecated as well.
Instead of relying on the trailing slash to append the original URL
to the redirect location, use URL backreferences.  For example,
instead of
.PP
.EX
  Redirect "http://example.org/"
.EE
.PP
use:
.PP
.EX
  URL ".*"
  Redirect "http://example.org$0"
.EE
.SS Multiple redirect backends
Use of multiple \fBRedirect\fR backends in a single service is
deprecated, as well as using  \fBRedirect\fR backends together with
regular ones.  If you know of any valid usage for such configuration,
please drop a note to the authors (see
.BR "REPORTING BUGS" ,
below).
.SH ADDITIONAL NOTES
.B Pound
uses the system log for messages (default facility \fBLOG_DAEMON\fR).
If using
.BR rsyslog ,
you can use the following configuration fragment to redirect
.B pound
messages to a separate file:
.PP
.EX
:programname, startswith, "pound" {
  /var/log/pound.log
  stop
}
.EE
.PP
The format requested by
.B "LogLevel 3"
is understood by most log analyzers.
.PP
Translating HTTPS to HTTP is an iffy proposition: no client
information is passed to the server itself (certificates, etc) and the
backend server may be misled if it uses absolute URLs.
.B Pound
tries to handle this by adding various
.B X\-Forwarded\-*
and
.B X\-SSL\-*
headers.  See
.B "HEADER MODIFICATION"
above, for a detailed discussion.
.PP
.B Pound
deals with (and sanitizes) HTTP/1.1 requests. Thus even if you have an
HTTP/1.0 server, a single connection to an HTTP/1.1 client is kept,
while the connection to the backend server is re-opened as necessary.
.PP
.B Pound
attempts to resolve the names of the hosts that appear in various
requests and/or responses.  That means it needs a functioning resolver
of some kind (be it
.BR /etc/hosts ,
DNS or something else).
However, the use of DNS can be disabled using the
.B \-W no\-dns
command line option.
.SH EXAMPLES
To translate HTTPS requests to a local HTTP server (assuming your
network address is 192.0.2.1):
.PP
.EX
ListenHTTPS
    Address 192.0.2.1
    Port    443
    Cert    "/etc/pound/server.pem"
    Service
        Backend
            Address 127.0.0.1
            Port    80
        End
    End
End
.EE
.PP
To distribute the HTTP/HTTPS requests to three Web servers, where the third one
is a newer and faster machine:
.PP
.EX
ListenHTTP
    Address 192.0.2.1
    Port    80
End

ListenHTTPS
    Address 192.0.2.1
    Port    443
    Cert    "/etc/pound/server.pem"
End

Service
    Backend
        Address 192.168.0.10
        Port    80
    End

    Backend
        Address 192.168.0.11
        Port    80
    End

    Backend
        Address 192.168.0.12
        Port    80
        Priority 3
    End
End
.EE
.PP
To separate between image requests and other Web content and send all requests
for a specific URL to a secure server:
.PP
.EX
ListenHTTP
    Address 192.0.2.1
    Port    80
End

# Images server(s)
Service
    URL ".*.(jpg|gif)"
    Backend
        Address 192.168.0.12
        Port    80
    End
End

# redirect all requests for /forbidden

Service
    Url         -beg "/forbidden"
    Redirect    "https://xyzzy.com"
End

# Catch-all server(s)
Service
    Backend
        Address 192.168.0.10
        Port    80
    End

    Backend
        Address 192.168.0.11
        Port    80
    End

    Session
        Type    BASIC
        TTL     300
    End
End
.EE
.PP
Here is a more complex example: assume your static images (GIF/JPEG)
are to be served from a single backend 192.168.0.10. In addition,
192.168.0.11 is to do the hosting for \fIwww.myserver.com\fR with
URL-based sessions.  Two backends, 192.168.0.20 and 192.168.0.21,
will handle the rest of requests (cookie-based sessions).  Among
these, the latter (192.168.0.21) is less powerful than the former,
so care should be taken that it gets less requests.  The logging will
be done by backend servers.  All plain HTTP requests are to be
redirected to HTTPS and all requests directed to \fImyserver.com\fR -
to \fIwww.myserver.com\fR.  The configuration file may look like this:
.PP
.EX
User        "nobody"
Group       "nogroup"
RootJail    "/var/pound/jail"
Alive       60
LogLevel    0

# HTTP: redirect all requests to the corresponding HTTPS server.
ListenHTTP
    Address 192.0.2.1
    Port    80
    Client  10
    Service
        Host -re ".+"
        URL ".*"
        Redirect 301 "https://$0(1)$0"
    End
End

ListenHTTPS
    Address 192.0.2.1
    Port    443
    Cert    "/etc/pound/pound.pem"
    Client  20
End

# Image server
Service
    URL ".*.(jpg|gif)"
    Backend
        Address 192.168.0.10
        Port    80
    End
End

# Virtual host www.myserver.com
Service
    URL         ".*sessid=.*"
    Host        "www.myserver.com"
    Backend
        Address 192.168.0.11
        Port    80
    End

    Session
        Type    URL
        ID      "sessid"
        TTL     120
    End
End

# Virtual host myserver.com - redirects to www.
Service
    Host        "myserver.com"
    URL         ".*"
    Redirect 301 "https://www.myserver.com$0"
End

# Virtual host server1.com and www.server1.com
Service
    Host        -re "^(www\.)?server1\.com$"
    Backend
        Address 192.168.0.20
        Port    80
        Priority 5
    End

    Backend
        Address 192.168.0.21
        Port    80
        Priority 4
    End

    Session
        Type    COOKIE
        ID      "userid"
        TTL     180
    End
End

# Return custom error page if no matching service was found.
Service
    Error 404 "/var/lib/pound/notfound.html"
End
.EE
.SH FILES
.TP
.B /var/run/pound.pid
This is where
.B pound
will attempt to record its process id.  The exact location is
determined at compile time by the value of the \fB\-\-localstatedir\fR
configuration switch.  It can be changed at runtime using the
.B \-p
command line option.   Use
.B pound \-V
to inspect the actual default.
.TP
.B /etc/pound.cfg\fR
The default configuration file.  The exact location is
determined at compile time by the value of the \fB\-\-sysconfdir\fR
configuration switch.  It can be changed at runtime using the
.B \-f
command line option.  Use
.B pound \-V
to inspect the actual default.
.TP
.B /usr/local/etc/pound/cert.pem
the certificate file(s) for HTTPS. The location must be defined in the configuration
file - this is only a suggestion. The file must contain a PEM-encoded certificate,
optionally a certificate chain from a known Certificate Authority to your server certificate
and a PEM-encoded private key (not password protected). See
.BR openssl (1)
for details. This file should be well protected, lest someone gets your server
private key.
.SH AUTHOR
Written by Robert Segall (Apsis GmbH), and Sergey Poznyakoff.
.SH "REPORTING BUGS"
Report bugs to <gray@gnu.org>.  You may also use github issue tracker
at https://github.com/graygnuorg/pound/issues.
.SH COPYRIGHT
Copyright \(co 2002-2010 Apsis GmbH.
.br
Copyright \(co 2018-2025 Sergey Poznyakoff
.sp
.na
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
.sp
.ad
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
.\" Local variables:
.\" eval: (add-hook 'write-file-hooks 'time-stamp)
.\" time-stamp-start: ".TH [A-Z_][A-Z0-9_.\\-]* [0-9] \""
.\" time-stamp-format: "%:B %:d, %:y"
.\" time-stamp-end: "\""
.\" time-stamp-line-limit: 20
.\" indent-tabs-mode: nil
.\" end: