mirror of
https://github.com/graygnuorg/pound.git
synced 2026-10-28 11:35:07 +03:00
8f0228551b
* src/config.c (parse_listen_http) (parse_listen_https): Handle optional listener name. Make sure it is unique. (parse_service): Make sure service name is unique. * src/pound.h (LISTENER): New field: name. * src/poundctl.tmpl: Show listener name, if available. * svc.c (get_nth_listener, get_nth_service) (get_nth_backend,ctl_getnum): Remove. (IDENT): New data type. (ctl_getident,locate_listener,locate_service) (locate_backend): New functions. (service_serialize): Represent NULL service name as null. (listener_serialize): Add listener name. (ctl_service,ctl_listener): Identify objects by their ids or numbers. * NEWS: Document changes. * doc/pound.8: Likewise. * doc/poundctl.8: Likewise.
2135 lines
60 KiB
Groff
2135 lines
60 KiB
Groff
.\" Pound - the reverse-proxy load-balancer
|
|
.\" Copyright (C) 2002-2010 Apsis GmbH
|
|
.\" Copyright (C) 2018-2023 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 "March 3, 2023" "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. The HTTPS requests are
|
|
decrypted and passed to the backends as plain HTTP.
|
|
.PP
|
|
If more than one backend server is defined,
|
|
.B pound
|
|
chooses one of them randomly, based on defined 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). Two types of
|
|
.I listeners
|
|
may be defined: regular HTTP
|
|
.I listeners
|
|
and HTTPS (HTTP over SSL/TLS)
|
|
.IR listeners .
|
|
At the very least a
|
|
.I listener
|
|
must define the address and port to listen on, with additional
|
|
requirements for HTTPS
|
|
.IR listeners .
|
|
.TP
|
|
\fBServices\fR
|
|
A
|
|
.I service
|
|
is the definition of how the requests are answered. The
|
|
.I services
|
|
may be defined within a
|
|
.I listener
|
|
or at the top level (global). When a request is received,
|
|
.B pound
|
|
attempts to match them to each
|
|
.I service
|
|
in turn, starting with the
|
|
.I services
|
|
defined in the
|
|
.I listener
|
|
itself and, if needed, continuing with the
|
|
.I services
|
|
defined at the global level. The
|
|
.I 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
|
|
.I service
|
|
may also define a
|
|
.I session
|
|
mechanism: if defined, future requests from a given client will always
|
|
be answered by the same
|
|
.IR backend .
|
|
.TP
|
|
\fBBackends\fR
|
|
The
|
|
.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. The
|
|
.I backend
|
|
defines how the server should be contacted.
|
|
.IP
|
|
Three types of
|
|
.I backends
|
|
may be defined: a "regular"
|
|
.I backend
|
|
which receives requests and returns responses, a "redirect"
|
|
.IR backend ,
|
|
in which case
|
|
.B pound
|
|
will respond with a redirect response, without accessing any
|
|
.I backend
|
|
at all, or an "emergency"
|
|
.IR backend ,
|
|
which will be used only if all other backends are "dead".
|
|
.IP
|
|
Multiple
|
|
.I backends
|
|
may be defined within a
|
|
.IR service ,
|
|
in which case
|
|
.B pound
|
|
will load-balance between the available
|
|
.IR backends .
|
|
.IP
|
|
If a
|
|
.I 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
|
|
.I backends
|
|
are available (none were defined, or all are "dead") then
|
|
.B pound
|
|
will reply with "503 Service Unavailable", without checking additional
|
|
.IR services .
|
|
.IP
|
|
Normally, the connection between
|
|
.B pound
|
|
and
|
|
.I 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 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 facilities). 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 facilities). 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, only one \fIFEATURE\fR is implemented:
|
|
.RS
|
|
.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.
|
|
.RE
|
|
.PP
|
|
In general, any number of backend servers may be specified. Use the
|
|
priority to affect the load distribution among unequal-performance
|
|
servers.
|
|
.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 within the configuration file,
|
|
although it is customary for them to be at the start.
|
|
.TP
|
|
\fBUser\fR "user_name"
|
|
Specify the user
|
|
.B pound
|
|
will run as (must be defined in the system user database).
|
|
.TP
|
|
\fBGroup\fR "group_name"
|
|
Specify the group
|
|
.B pound
|
|
will run as (must be defined in the system group database).
|
|
.TP
|
|
\fBRootJail\fR "directory_path_and_name"
|
|
Specify the directory that
|
|
.B pound
|
|
will chroot to at runtime. Please note that OpenSSL requires access to
|
|
/dev/urandom, so make sure you create a device by that name,
|
|
accessible from the root jail directory.
|
|
.B pound
|
|
may also require access to
|
|
.I /dev/syslog
|
|
or similar.
|
|
.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
|
|
\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
|
|
\fBLogLevel\fR \fIn\fR
|
|
Specify the logging level: 0 for no logging, 1 (default) for regular
|
|
logging, 2 for extended logging (show chosen backend server as well),
|
|
3 for Apache-like format (Combined Log Format with Virtual Host), 4
|
|
(same as 3 but without the virtual host information) and 5 (same as 4
|
|
but with information about the
|
|
.B Service
|
|
and
|
|
.B Backend
|
|
used).
|
|
This value can be overridden for specific listeners.
|
|
.TP
|
|
\fBIgnoreCase\fR \fIbool\fR
|
|
Ignore case when matching URLs (default: \fIfalse\fR). This 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 \fBURL\fR 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 and 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 "name"
|
|
Use an OpenSSL hardware acceleration card called \fIname\fR. Available
|
|
only if OpenSSL-engine is installed on your system.
|
|
.TP
|
|
\fBECDHcurve\fR "name"
|
|
Use the named curve for elliptical curve encryption (default: prime256v1).
|
|
.TP
|
|
\fBControl\fR "/path/to/socket"
|
|
Set the control socket path. If not defined,
|
|
.B pound
|
|
does not listen for any commands. The commands may be issued by using
|
|
the
|
|
.BR poundctl (8)
|
|
program.
|
|
.TP
|
|
\fBInclude\fR "/path/to/file"
|
|
Include the file as though it were part 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 "name"
|
|
Define a \fInamed access control list\fR (\fIACL\fR). An ACL is a
|
|
list of network addresses in CIDR notation, terminated with an
|
|
.B End
|
|
directive on a line by itself. E.g.:
|
|
.sp
|
|
.RS
|
|
.EX
|
|
ACL "secure"
|
|
"192.0.2.0/26"
|
|
"203.0.113.0/24"
|
|
End
|
|
.EE
|
|
.sp
|
|
Named ACLs can be used in \fBService\fR definitions to make services
|
|
available from certain IP addresses only.
|
|
.RE
|
|
.TP
|
|
\fBPIDFile\fR "filename"
|
|
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].
|
|
PID file is used only in daemon mode (\fBDaemon on\fR in the
|
|
configuration file).
|
|
.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. This may be not possible in two cases: if it
|
|
switches to another user privileges after startup (at least one of
|
|
\fBUser\fR or \fBGroup\fR used in the configuration file), or if it
|
|
runs in a chrooted environment (\fBRootJail\fR used). In these cases,
|
|
the PID file will remain on disk after termination of the program.
|
|
.RE
|
|
.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
|
|
and address and a 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 symbolic host name
|
|
that must be resolvable at run-time, or a full pathname of a UNIX
|
|
socket. Either this parameter or
|
|
.B SocketFrom
|
|
(see below) must be present. The address 0.0.0.0 may be used as an
|
|
alias for 'all available addresses on this machine', but this practice
|
|
is strongly discouraged, as it will interfere with the rewriting
|
|
mechanisms (see below).
|
|
.TP
|
|
\fBPort\fR \fIport\fR
|
|
The port number or service name that
|
|
.B pound
|
|
will listen on. This parameter must be present if the
|
|
.B Address
|
|
parameter contains an IPv4 or IPv6 address.
|
|
.TP
|
|
\fBSocketFrom\fR "/path/to/socket"
|
|
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 "pattern to match"
|
|
Define a pattern that must be matched by each request sent to this
|
|
listener. A request that does not match is considered to be illegal.
|
|
By default
|
|
.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
|
|
\fBErr404\fR "filename"
|
|
A file with the text to be displayed if an Error 404 occurs.
|
|
Default: "Not Found.".
|
|
.TP
|
|
\fBErr413\fR "filename"
|
|
A file with the text to be displayed if an Error 413 occurs.
|
|
Default: "Request too large.".
|
|
.TP
|
|
\fBErr414\fR "filename"
|
|
A file with the text to be displayed if an Error 414 occurs.
|
|
Default: "Request URI is too long.".
|
|
.TP
|
|
\fBErr500\fR "filename"
|
|
A file with the text to be displayed if an Error 500 occurs.
|
|
Default: "An internal server error occurred. Please try again later.".
|
|
.TP
|
|
\fBErr501\fR "filename"
|
|
A file with the text to be displayed if an Error 501 occurs.
|
|
Default: "This method may not be used.".
|
|
.TP
|
|
\fBErr503\fR "filename"
|
|
A file with the text to be displayed if an Error 503 occurs.
|
|
Default: "The service is not available. Please try again later.".
|
|
.TP
|
|
\fBMaxRequest\fR \fIn\fR
|
|
Request maximal size. All requests will be limited to these many
|
|
bytes. If a request contains more data than allowed, an error 413 is
|
|
returned. Default: unlimited.
|
|
.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 value
|
|
Override the global
|
|
.B LogLevel
|
|
value.
|
|
.TP
|
|
\fBService\fR [ "name" ]
|
|
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 "directory"
|
|
Serve ACME challenge requests from the given
|
|
.IR directory .
|
|
See the 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 Modification directives
|
|
The following directives modify the incoming request prior to passing
|
|
it to the selected service. These are discussed in detail
|
|
in the section
|
|
.BR "REQUEST MODIFICATION" ,
|
|
below.
|
|
.TP
|
|
\fBDeleteHeader\fR "header: pattern"
|
|
Remove certain headers from the incoming requests. All occurrences of
|
|
the matching specified header will be removed. See the section
|
|
for a detailed discussion of various header modification directives.
|
|
.TP
|
|
\fBSetHeader\fR "header: to add"
|
|
Add the defined header to the request passed to the backend
|
|
server. The header is added verbatim. Use multiple \fBHeaderAdd\fR
|
|
directives if you need to add more than one header.
|
|
.TP
|
|
\fBSetURL\fR "value"
|
|
Sets the URL part of the request.
|
|
.TP
|
|
\fBSetPath\fR "value"
|
|
Sets the path part.
|
|
.TP
|
|
\fBSetQuery\fR "value"
|
|
Sets the query part.
|
|
.TP
|
|
\fBSetQueryParam\fR "name" "value"
|
|
Modifies the query. Sets the query parameter \fIname\fR to \fIvalue\fR.
|
|
.TP
|
|
.BR Rewrite " ... [ " Else " ... ] " End
|
|
Conditionally apply request modification depending on whether request
|
|
matches certain conditions.
|
|
.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 "header: to add"
|
|
Same as \fBSetHeader\fR.
|
|
.TP
|
|
\fBAddHeader\fR "header: to add"
|
|
Same as \fBSetHeader\fR.
|
|
.TP
|
|
\fBHeaderRemove\fR "pattern"
|
|
Same as \fBDeleteHeader\fR.
|
|
.TP
|
|
\fBHeadRemove\fR "pattern"
|
|
Same as \fBDeleteHeader\fR.
|
|
.SH "HTTPS Listener"
|
|
An 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 "certificate file"
|
|
Specify the server certificate. The
|
|
.I certificate file
|
|
is the file containing the certificate, possibly a certificate chain
|
|
and the signature for this server. 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 "acceptable:cipher:list"
|
|
This is the list of ciphers that will be accepted by the SSL
|
|
connection; it is a string in the same format as in OpenSSL
|
|
.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 "CAcert_file"
|
|
Set the list of "trusted" CA's for this server. The CAcert_file is a
|
|
file containing a sequence of CA certificates (PEM format). The names
|
|
of the defined CA certificates will be sent to the client on connection.
|
|
.TP
|
|
\fBVerifyList\fR "Verify_file"
|
|
Set the CA (Certificate Authority). The Verify_file 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 "CRL_file"
|
|
Set the CRL (Certificate Revocation List) file. The CRL_file 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 "name"
|
|
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
|
|
\fBURL\fR [\fIoptions\fR] "\fIpattern\fR"
|
|
Match the URL of the incoming request. By default, \fIpattern\fR is
|
|
treated as case-sensitive regular expression. This can be changed by
|
|
\fIoptions\fR, described below.
|
|
.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 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.
|
|
.TP
|
|
\fBQueryParam\fR "\fIname\fR" [\fIoptions\fR] "\fIpattern\fR"
|
|
Match the value of the query parameter \fIname\fR.
|
|
.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 \-re
|
|
Use regular expression matching.
|
|
.TP
|
|
.B \-exact
|
|
Use exact string matching.
|
|
.TP
|
|
.B \-beg
|
|
Exact match at the beginning of string (prefix match).
|
|
.TP
|
|
.B \-end
|
|
Exact match at the end of string (suffix match).
|
|
.TP
|
|
.B \-case
|
|
Case-sensitive comparison.
|
|
.TP
|
|
.B \-icase
|
|
Case-insensitive comparison.
|
|
.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 "pattern"
|
|
Same as \fBHeader\fR.
|
|
.TP
|
|
\fBHeadDeny\fR "pattern"
|
|
A shortcut for
|
|
.IP
|
|
\fBNot header\fR "pattern"
|
|
.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 "header: pattern"
|
|
Remove matching headers from the incoming requests.
|
|
.TP
|
|
\fBSetHeader\fR "header: to add"
|
|
Add the defined header to the request passed to the backend
|
|
server.
|
|
.TP
|
|
\fBSetURL\fR "value"
|
|
Sets the URL part of the request.
|
|
.TP
|
|
\fBSetPath\fR "value"
|
|
Sets the path part.
|
|
.TP
|
|
\fBSetQuery\fR "value"
|
|
Sets the query part.
|
|
.TP
|
|
\fBSetQueryParam\fR "name" "value"
|
|
Modifies the query. Sets the query parameter \fIname\fR to \fIvalue\fR.
|
|
.TP
|
|
.BR Rewrite " ... [ " Else " ... ] " End
|
|
Conditionally apply request modification depending on whether request
|
|
matches certain conditions.
|
|
.SS Backend definitions
|
|
.TP
|
|
\fBBackend\fR
|
|
Directives enclosed between a
|
|
.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
|
|
\fBRedirect\fR [\fIcode\fR] "url"
|
|
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. You may
|
|
define multiple redirectors in a service, as well as mixing them with
|
|
regular backends.
|
|
.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 can contain references to parenthesized subexpressions
|
|
in the eight recently matched request matching directives of the enclosing
|
|
.BR Service .
|
|
Syntactically, \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.
|
|
.IP
|
|
Beside these constructs,
|
|
.I request accessors
|
|
can be used. A request accessor is
|
|
.IP
|
|
.RS
|
|
.EX
|
|
.IR %[ name ]
|
|
.EE
|
|
.RE
|
|
.IP
|
|
where \fIname\fR is one of:
|
|
.BR url ,
|
|
.BR path ,
|
|
.BR query ,
|
|
.BR param ,
|
|
and
|
|
.BR header ,
|
|
denoting the corresponding part of the request. The
|
|
.B param
|
|
and
|
|
.B header
|
|
accessors take a single argument: the name of the query parameter or
|
|
HTPP header. Accessors are explained in detail in section
|
|
.BR "REQUEST MODIFICATION DIRECTIVES" .
|
|
.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 reverts first two path components of the
|
|
original URL:
|
|
.IP
|
|
.EX
|
|
Service
|
|
Host -re "(.+)"
|
|
URL "^/([^/]+)/([^/]+)(/.*)?"
|
|
Redirect "http://%0/$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 Err 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 an
|
|
.B Emergency
|
|
and
|
|
the following
|
|
.B End
|
|
directives define an emergency backend server (see below for
|
|
details). You may define only one emergency server per service, which
|
|
.B pound
|
|
will attempt to use if all 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 a
|
|
.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).
|
|
.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 \fIbackreference
|
|
expansions\fR as discussed in the description of the \fBRedirect\fR
|
|
statement, in section
|
|
.B Service
|
|
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. 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
|
|
\fBCert\fR "certificate file"
|
|
Specify the certificate that
|
|
.B pound
|
|
will use as a client. The
|
|
.I certificate file
|
|
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 "acceptable:cipher:list"
|
|
This is the list of ciphers that will be accepted by the SSL
|
|
connection; it is a string in the same format as in OpenSSL
|
|
.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 (between 1 and 9, 5 is default). Higher priority
|
|
backends will be used more often than lower priority ones, so you should
|
|
define higher priorities for more capable servers.
|
|
.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).
|
|
.SH "Emergency"
|
|
The emergency server 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. 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, or a symbolic host name
|
|
that must be resolvable at run-time. 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 that
|
|
.B pound
|
|
will connect to. This is a
|
|
.B mandatory
|
|
parameter for non Unix-domain backends.
|
|
.PP
|
|
Additionally, the following directives are also supported:
|
|
.BR TimeOut ,
|
|
.BR WSTimeOut ,
|
|
.BR ConnTO ,
|
|
.BR HTTPS ,
|
|
.BR Cert ,
|
|
.BR Ciphers ,
|
|
.BR Disable .
|
|
These have the same meaning as in the
|
|
.B Backend
|
|
section, which see.
|
|
.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 "name"
|
|
The session identifier. This directive is permitted only for sessions of type
|
|
URL (the name of the request parameter we need to track), COOKIE (the name of
|
|
the cookie) and HEADER (the header name).
|
|
.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 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 matchibg \fIPATTERN\fR. By
|
|
default, \fIPATTERN\fR is treated as extended POSIX regular
|
|
expression. One or more \fIoptions\fR can be supplied to modify
|
|
the default behavior. 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:
|
|
.RS
|
|
.TP
|
|
.B \-re
|
|
Use regular expression matching.
|
|
.TP
|
|
.B \-exact
|
|
Use exact string matching.
|
|
.TP
|
|
.B \-beg
|
|
Exact match at the beginning of string (prefix match).
|
|
.TP
|
|
.B \-end
|
|
Exact match at the end of string (suffix match).
|
|
.TP
|
|
.B \-case
|
|
Case-sensitive comparison.
|
|
.TP
|
|
.B \-icase
|
|
Case-insensitive comparison.
|
|
.RE
|
|
.PP
|
|
The \fIVALUE\fR argument in the above directives is subject to
|
|
.IR "request evaluation", during which ny occurrence of
|
|
.I request accessors
|
|
found in it is replaced them with the values they produce.
|
|
Syntactically, a request accessor is:
|
|
.PP
|
|
.EX
|
|
\fB%[ \fINAME\fR [\fIARG\fR] \fB]\fR
|
|
.EE
|
|
.PP
|
|
where \fINAME\fR is the accessor name and \fIARG\fR is optional
|
|
argument. Notice, that square brackets shown in bold are part
|
|
of the accessor, whereas those enclosing \fIARG\fR are used to
|
|
denote its optional nature.
|
|
.PP
|
|
The following accessors are defined:
|
|
.TP
|
|
.B url
|
|
Returns the URL part of the request.
|
|
.TP
|
|
.B path
|
|
Returns the path part of the request.
|
|
.TP
|
|
.B query
|
|
Returns the query part of the request.
|
|
.TP
|
|
.BI param " NAME"
|
|
Returns the value of the query parameter \fINAME\fR.
|
|
.TP
|
|
.BI header " NAME"
|
|
Returns the value of the HTTP header \fINAME\fR.
|
|
.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, the
|
|
.B Rewrite
|
|
block is:
|
|
.PP
|
|
.EX
|
|
.B Rewrite
|
|
\&.
|
|
\&.
|
|
\&.
|
|
.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, providing 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
|
|
When used in this context, arguments to request modification
|
|
directives are also subject to
|
|
.I backreference expansion
|
|
similar to that discussed in the description of the \fBRedirect\fR
|
|
statement, in section
|
|
.B Service
|
|
above. To illustrate this, here's the
|
|
above example rewritten using backreferences instead of 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 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 addition
|
|
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.
|
|
.IP
|
|
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.
|
|
.IP
|
|
The \fIopt\fR values passed to the directive are:
|
|
.RS
|
|
.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.
|
|
.RE
|
|
.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 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 RootJail 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 RFC's and
|
|
only valid requests are passed to the backend servers. This is not
|
|
absolutely fool-proof - as the recent Apache problem with chunked
|
|
transfers demonstrated. However, given the current standards, this is
|
|
the best that can be done - HTTP is an inherently weak protocol.
|
|
.SH DEPRECATED FEATURES
|
|
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
|
|
.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.
|
|
.PP
|
|
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
|
|
.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$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-2023 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:
|