Version 4.24

Changes in configuration syntax

Sizes

Arguments to the following keywords can be suffixed with usual size suffixes k, m, and g or their upper-case equivalents: ContentCapture, LineBufferSize, MaxURI, WorkerStackSize.

Durations

A duration is a sequence of decimal numbers, each of which is followed by a time unit suffix, s, m, h or d, standing for seconds, minutes, hours, or days, correspondingly. The suffix is optional for the last number in the sequence, in which case s is assumed.

The following keywords take a duration value as argument:

• Alive
• Client
• ConnTO
• Grace
• OverrideTTL
• RetryInterval
• TTL (in the Session section)
• TimeOut
• WSTimeOut
• WatcherTTL
• WorkerIdleTimeout

Synchronization lines

Synchronization lines in traditional formats are understood:

   #line N
   #line N `FILE`
   # N
   # N `FILE`

Pragmatic comments

Comments that start with the word pragma are treated specially. Such comments modify parsing of the configuration file. This version introduces two pragmatic comments:

• #pragma preprocessor COMMAND

  Enables configuration file preprocessing. See below for details.

• #pragma tab-width N

  Instructs pound to consider each TAB character to be equal to N spaces. This is used when computing column offsets in configuration file, for diagnostic and reporting.

Cert and ACME statements take into account include directory

Arguments to Cert or ACME are taken relative to the current include directory.

Wildcards are allowed in Cert statement

The argument to the Cert directive in ListenHTTPS can contain glob (7) patterns, e.g.:

  Cert "ssl/*.pem"

Placement of Cert directive within ListenHTTPS

In previous versions, the Cert directive was required to precede any other SSL-specific statement (such as ClientCert, etc.) in the ListenHTTPS section. This is no longer the case. This directive can be placed anywhere within ListenHTTPS.

The Use statement in Backend sections

The Use statement inherits settings from a named backend referred to by its argument. The Priority and Disables directives can be used together with it, e.g.:

   Service
       Backend
	   Use "nb"
	   Priority 3
       End
   End

HTTPS statement in Backend sections

In previous versions, the HTTPS statement was required to be used prior to any of the following statements in a Backend section: Cert, Ciphers, Disable. This requirement was lifted. Moreover, any of these statements already imply that the backend is HTTPS capable, which means that the HTTPS statement can be omitted if any of these is used.

Fall-through services

Fall-through services are processed specially. If the request matches such a service, any modification statements from that service are applied to the request, and the selection process continues from the next service. In other words, a fall-through service provides a way to apply a set of modifications common for all services that follow.

A service is declared as fall-through using the FallThrough statement. Such services cannot contain backend definitions or Rewrite response statements. An example of a fall-through service follows:

  Service
      Path -beg "/status/"
      SetHeader "Host: internal"
      LogSuppress success
      FallThrough
  End

Early rewrites

A new flavor of the Rewrite statement is introduced:

  Rewrite early

In contrast to normal rewrites, which are applied to requests before passing them on to the corresponding backends, Rewrite early statements are applied at the early stage of request processing so that the resulting modifications become visible to subsequent configuration statements.

Rewrite early sections used in ListenHTTP (or ListenHTTPS) sections are applied first, right after the request headers have been received and parsed. Those used in Service sections, are applied during service selection, before applying service selection statements for that service.

It is important to notice that any modifications done by early rewrites in a Service section remain visible for subsequent sections, if this one is not selected for processing the request.

To summarize, this release provides two mechanisms for making request modifications visible to conditional statements: early rewrites and fall-through sections.

Beacons

Beacons are special boolean values that can be used in conditional statements to select the service to use. Beacons can change their value only via the pound control interface, using poundctl or similar tool.

Beacons provide a mechanism for adopting pound configuration to changes in external conditions (such as current load average or request rate) without the need to reconfigure the pound daemon.

Beacons are declared using the DeclareBeacon statement in the global scope:

  DeclareBeacon "NAME" [BOOL]

Beacons are examined using the Beacon statement in Section, Match, or Rewrite section, e.g.:

  Beacon "NAME"

To change or inspect the actual value of a beacon, use poundctl:

• poundctl beacon

  Examine all declared beacons and their values.

• poundctl beacon NAME

  Examine the value of the beacon NAME.

• poundctl -s NAME

  Set beacon NAME to true.

• poundctl -d NAME

  Set beacon NAME to false.

Query accessor

The query accessor takes an optional argument. If the query part is present, the argument is prepended to the expansion. This is useful when rewriting URLs, for example:

   Rewrite 308 "https://example.com/%[query ?]"

Request timings

The %T log conversion specifier takes an optional prefix, that determines the starting point for time measuring. Its possible values are

• init

  The time between establishing connection or sending last byte of the previous response and sending last byte of the response to the client.

• req

  The time between receiving first byte of the request and sending last byte of the response to the client. This is the default.

• reqend

  The time after receiving last byte of the request header and sending last byte of the response to the client.

• be

  The time between sending first byte to the backend and sending last byte of the response to the client.

Example:

 "%{reqend:us}T"

Similar extension applies to the D conversion. Here, the prefix indicates the stage of request processing whose duration is requested. Its values are:

• init

  Time between establishing the connection or sending last byte of the previous response and receiving first byte of the request.

• header

  Total time reading the request headers, i.e. between receiving first byte of the request and sending it over to the backend.

• select

  Time spent selecting the service and backend.

• resp

  Time taken by response processing, i.e. time elapsed between the moment when the service and backend have been selected and the moment after the last byte of the response has been sent to the client.

• be

  Time between sending first byte to the backend and sending last
  byte of the response to the client.

• totalreq

  Time between receiving first byte of the request and sending last
  byte of the response to the client.

• grandtotal

  Time between establishing the connection or sending last byte of
  the previous response and sending last byte of the response to the
  client.

Tracing

Tracing helps in debugging complex service selection or rewrite conditions. Each service has an associated trace flag. When this flag is set, each evaluated conditional is reflected in the pound log. Example output:

  (7f2d5534f640) Request from: 192.0.2.11
  (7f2d5534f640) Request: GET /media/id.jpg HTTP/1.1
  (7f2d5534f640) Headers:
  (7f2d5534f640) Host:example.com
  (7f2d5534f640) User-Agent: Mozilla/5.0
  (7f2d5534f640) Accept: #/#
  (7f2d5534f640) service selection: pound.cfg:29.9-36.11:considering service
  (7f2d5534f640) service selection: pound.cfg:30.17-26: header: 1
  (7f2d5534f640) service selection: pound.cfg:31.17-25: path /media: 1
  (7f2d5534f640) service selection: implicit AND: 1
  (7f2d5534f640) service selection: pound.cfg:29.9-36.11: service selected

The value in parentheses identifies the worker thread that did the selection. The result of each conditional is printed as a boolean value (0/1).

To manage trace flags, a new poundctl subcommand, trace, is provided:

• poundctl trace /L/S

  Show trace flag for service S in listener L.

• poundctl trace -s /L/S

  Set trace flag for service S in listener L.

• poundctl trace -d /L/S

  Delete (unset) trace flag for service S in listener L.

The object path specification can be shortened to /L, to operate on all services in the listener L, or to /, to operate on all services defined in the configuration.

Preprocessing

Configuration files can be optionally preprocessed using an external program. To do so, specify the command line of the preprocessor in the preprocessor pragmatic comment appearing in the very beginning of the principal configuration file, like that:

  #pragma preprocessor m4 -s

It is important that this comment appears before the first configuration statement. Comments and empty lines before it are allowed.

A new command line option -E instructs pound to print the preprocessed text and exit.