graygnuorg/pound v4.9

Version 4.9

on GitHub

HTTP request logging

In addition to six built-in log formats, you can define your own named formats and use them in LogLevel directive. Log formats are defined using the following statement:

  LogFormat "name" "FormatString"

The "name" argument specifies a string uniquely identifying this format. "FormatString" is the format specification. It is
modelled after Apache's LogFormat string. For example, the built-in format 3 is defined as:

  "%a - %u %t \"%r\" %s %b \"%{Referer}i\" \"%{User-Agent}i\""

The LogLevel directive has been extended to take symbolic format name as argument. For example:

  LogLevel "my_format"

The traditional built-in formats are assigned the following symbolic names:

• 0 - "null"
• 1 - "regular"
• 2 - "extended"
• 3 - "vhost_combined"
• 4 - "combined"
• 5 - "detailed"

So, instead of

  LogLevel 3

one may write

  LogLevel "vhost_combined"

New statements: ForwardedHeader and TrustedIP

These statements control how the %a log format conversion specifier determines the originator IP address:

• ForwardedHeader "name"

  Defines the name of HTTP header that carries the list of proxies the request has passed through. It is used to report the originator IP address when logging.

  The default value is "X-Forwarded-For". This statement can be used in global, listener, and service scope.

• TrustedIP

  Defines a list of trusted proxy IP addresses, which is used to determine the originator IP. This is a special form of the ACL
  statement and, as the latter, it can appear in two forms: directive and section.

  In directive form, it takes a single argument referring to a named access control list, which must have been defined previously using the ACL statement.

  In section form, it is followed by a list of one or more CIDRs each appearing on a separate line. The End directive on a separate line terminates the statement.

  This statement can be used in global, listener, and service scope.

New service statement: LogSuppress

Suppresses HTTP logs for requests that resulted in response status codes from a particular group or groups. The statement takes one or more arguments specifying status code groups to suppress log messages for:

• info or 1

  1xx status codes

• success or 2

  2xx status codes

• redirect or 3

  3xx status codes

• clterr or 4

  4xx status codes

• srverr or 5

  5xx status codes

• all

  all status codes

Suggested usage is for special services that are likely to process large numbers of similar requests, such as Openmetrics services. For example:

   Service "metrics"
       URL "/metrics"
       Metrics
       LogSuppress success
   End

New request matching directive: StringMatch

The syntax is:

  StringMatch "SUBJECT" [OPTIONS] "PATTERN"

OPTIONS are usual matcher options. The directive matches if SUBJECT, after backreference expansion and accessor interpretation, matches PATTERN.

This directive allows you to build complex service selection criteria. For example:

  Service
      Host "^foobar\.(.+)$"
      StringMatch "$1" -file "domain.list"
      ...
  End

The service above will be used for requests whose Host header value is "foobar." followed by a domain name from the file "domain.list".

New request accessors: host and port

The %[host] accessor returns the hostname part of the Host header value. The %[port] accessor returns port number with leading column character. If no explicit port number is given in the Host value, %[port] returns empty string.

Bugfixes

• Fix the QueryParam statement.
• Improve testsuite and documentation.