Project pound


4.6  —  2023-03-07
* Load-balancing strategies

A load balancing strategy defines algorithm used to distribute
incoming requests between multiple regular backends.  This version
of pound implements two such strategies:

** Weighted Random Balancing

This is the default strategy and the one implemented by prior versions
of pound.  Each backend is assigned a numeric priority between 0 and 9
(inclusive).  The backend to use for each request is determined at
random taking into account backend priorities, so that backends with
numerically greater priorities have proportionally greater chances of
being selected than the ones with lesser priorities.

** Interleaved Weighted Round Robin Balancing

Requests are assigned to each backend in turn.  Backend priorities, or
weigths, are used to control the share of requests handled by each
backend.  The greater the weight, the more requests will be sent to
this backend.

* New statement: Balancer

The Balancer statement can appear in global and in Service scope.  It
defines the load balancer to use.  Possible arguments are: random, to
use weighted random balancing (default), and iwrr to use interleaved
weighted round robin balancing.

* Backreferences

Up to eight most recent matches are saved.  They can be referenced
as $N(M), where N is number of the parenthesized subexpression, and
M is number of the match.  Matches are numbered in reverse chronological
order with the most recent one being at index 0.  The (0) can be
omitted ($1 is the same as $1(0)).

For example, given the following statements:

  Host -re "www\\.(.+)"
  Header -re -icase "^Content-Type: *(.*)"
  Path "^/static(/.*)?"

"$1" refers to the subgroup of Path, "$1(1)" - to that of Header, and
"$1(2)" - to that of Host.

Curly braces may be used to delimit reference from the text that
follows it.  This is useful if the reference is immediately followed
by a decimal digit or opening parenthesis, as in: "${1}(text)".

* Request matching directives

In addition to "URL" and "Header", the following matching directives
are provided

  Path [options] "value"
    Match path.

  Query [options] "value"
    Match query.

  QueryParam "name" [options] "value"
    Match query parameter.

* Request modification directives

Request modification directives apply changes to the incoming request
before passing it on to the service or backend.  They can be used both
in ListenHTTP (ListenHTTPS) and Service sections.  The following
directives are provided:

  DeleteHeader "header: pattern"
      Remove matching headers from the incoming requests.

  SetHeader "header: to add"
      Add the defined header to the request passed.  If the header
      already exists, change its value.

  SetURL "value"
      Sets the URL part of the request.

  SetPath "value"
      Sets the path part.

  SetQuery "value"
      Sets the query part.

  SetQueryParam "name" "value"
      Sets the query parameter "name" to "value".

  Rewrite ... [ Else ... ] End
      Conditionally apply request modification depending on whether request
      matches certain conditions, e.g.:

			Path "\\.(jpg|gif)$"
			SetPath "/images$0"
			Match AND
				Host ""
				Path "\\.[^.]+$"
			SetPath "/static$0"
			Path "\\.[^.]+$"
			SetPath "/assets$0"

* Request accessors

These are special constructs that, when used in string values, are
replaced with the corresponding parts of the incoming request.  The
supported accessors are:

   The URL of the request.

   The path part of the request.

   The query part of the request.

 %[param NAME]
   The value of the query parameter NAME.

 %[header NAME]
   The value of the request header NAME.

Request accessor can be used in all strings where the use of
backreferences is allowed: i.e. arguments to Redirect, ACME,
Error directives, and to all request modification directives described

* Listener labels

Listeners can be assigned symbolic labels.  The syntax is:

  ListenHTTP "name"
  ListenHTTPS "name"

The "name" must be unique among all listeners defined in the

This symbolic name can be used to identify listener in poundctl
requests (see below).

* Service labels

Service labels must be unique among all services within the
listener (or in the configuration file, for global ones).

* Use of listener and service labels in poundctl

Listeners and services can be identified both by their numbers and
labels.  For example:

  poundctl list /main/static/1

* Use of multiple redirects in single service

Use of multiple redirect backends in single service, as well as mixing
them with regular backends is deprecated and causes a warning message.

Pound is a reverse proxy, load balancer and HTTPS front-end for Web servers. It was developed to enable distributing load among several Web-servers and to allow for a convenient SSL wrapper for those Web servers that do not offer it natively.

Pound was originally developed by Robert Segall at Apsis GmbH. I took over its development when Robert announced that he abandons it.