graygnuorg/pound v4.6

Version 4.6

on GitHub

Load-balancing strategies

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 the number of the parenthesized subexpression, and M is the 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 in 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.:

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

Request 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:

• %[url]
  The URL of the request.

• %[path]
  The path part of the request.

• %[query]
  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 above.

Listener labels

Listeners can be assigned symbolic labels. The syntax is:

  ListenHTTP "name"

or

  ListenHTTPS "name"

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

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.