graygnuorg/pound v4.14

Version 4.14

on GitHub

Dynamic backends

Dynamic backends are created and updated on the fly based on the information from DNS. To declare backend as dynamic, use a symbolic host name in its Address statement and add the Resolve statement with one of the following values:

• first
  Resolve the symbolic host name and use first IP from the DNS response as the address of the created dynamic backend. Thus, at most one dynamic backend will be created.

• all
  Resolve the symbolic host name and create one backend for each address from the DNS response. This enables load balancing between created backends. Each backend will be assigned the same priority.

• srv
  Obtain SRV records for the host name and use them to generate regular backends. Each record produces new dynamic backend of Resolve all type, which creates regular backends as described above. The weight field of the SRV record is mapped to the priority field of each generated backend. The SRV priority field determines the balancing group (see below) where the backend will be hosted.

By default, both IPv4 and IPv6 addresses are looked for. You can select the specific address family using the Family statement. Its allowed values are:

• any
  Use all address families available. This is the default.
• inet
  Use only IPv4 addresses.
• inet6
  Use only IPv6 addresses.

For example:

  Backend
      Address "be0.example.net"
      Port 8080
      Resolve first
      Family inet
  End

Dynamic backends will be updated periodically, when the TTL of the corresponding DNS records expires. If the hostname cannot be resolved or a DNS failure occurs, next update will be scheduled in 600 seconds after the failure. This interval can be configured using the RetryInterval statement in the Backend section, or globally, in the Resolver section.

The Resolver section allows you to control how DNS lookups are performed. It can contain the following directives:

• CNAMEChain integer
  Maximum allowed length of a CNAME chain. CNAME chains are formed by DNS CNAME records pointing to another CNAME. Although prohibited by the RFC, such usage occurs sometimes in the wild. By default, pound does not accept CNAME chains. If you work with a nameserver that uses them, set this statement to a small integer value, defining maximum number of CNAMEs in the chain that pound will accept. The value of 2 or 3 should suffice in most cases.

• ConfigFile string
  Name of the resolver configuration file. Defaults to /etc/resolv.conf.

• ConfigText
  This is a compound statement:

    ConfigText
       ...
    End 
  

  The material between ConfigText and End is read verbatim and used as the content of the resolver configuration file.

  If both ConfigFile and ConfigText are used, the last statement used wins.

• Debug boolean
  Whether to enable DNS debugging info.

• RetryInterval integer
  Interval in seconds, after which to retry failed DNS queries or queries that returned no RRs. This value is used unless the backend defines its own retry interval value.

Dynamic backends can be controlled using poundctl. For example, consider the following output from poundctl list:

  1. Listener http://192.0.2.1:80 enabled
      0. Service active (5)
          0. matrix "be0.example.com" 2 0 active
          1. backend http 198.51.100.15:8081 5 alive active
	  2. backend http 203.0.113.121:8081 5 alive active
          3. backend http 192.0.2.203:8081 5 alive active

The backend 0 ("matrix") refers to the Backend statement in the configuration file that produced the other three dynamic backends. Disabling it (poundctl disable /1/0/0) causes the dynamic ones to be removed. Enabling it will create them again. In a pinch, this can be used to force backend re-creation prior to TTL expiration.

Compiling

To enable dynamic backend support, you will need the adns library. On debian-based systems, it is installed by the following command

  apt-get install libadns1-dev

If all preconditions necessary for enabling dynamic backends are met, the output from configure will end with the following status line:

  Dynamic backends .............................. yes
  *******************************************************************

When compiled with the dynamic backend support, the output of pound -V will contain the following line in the Built-in defaults section:

  Dynamic backends:           enabled

Backend groups

Backend groups are a new pound feature, that extends the idea of regular and emergency backends used in previous versions. Any number of backend groups can be associated with a service. Each group is assigned an integer number (weight). The groups are ordered by weight (in ascending order) and are tried in that order when looking for a backend to serve the request. The look up starts with the first group. The balancing algorithm configured for the service is applied. If no backend can be selected, next group will be tried, and so on.

In the static configuration, regular backends are hosted in backend group of weight 0 and emergency (high availability) backends are stored in group of weight 65535. One consequence of this is that any number of Emergency backend declarations are now allowed in a service. More backend groups can be allocated when using dynamic backends of srv resolve type (see above).

Emergency backends

Any number of emergency backends can be defined. Usual request balancing algorithm applies when selecting an emergency backend.

All statements valid within a Backend section are also valid within an emergency backend declaration.

Listener address configuration

Both Address and Port statements are now optional. If Address is omitted, pound will listen on all available interfaces. If Port is omitted (and not listening on a UNIX socket), default port number for this kind of listener will be used: 80, for ListenHTTP, and 443, for ListenHTTPS.

New request matching conditional: ClientCert

The syntax is:

   ClientCert "FILENAME"

The conditional evaluates to true if the client presented the certificate matching that from the given file (PEM format).

It cannot be used in standalone services (i.e. services that are defined in global scope). It also cannot be used if the ListenHTTPS section that hosts the service has the ClientCert statement of its own.

Remote access to the management interface

A new backend type Control is introduced to make it possible to access the management interface remotely. The example below shows how to configure pound to expose the management interface on http://192.0.2.1:3434:

  ListenHTTP
      Address 192.0.2.1
      Port 3434
      Service
          ACL "secure"
	  Control
      End
  End

poundctl

Changes in poundctl functionality reflect those in the management interface. First of all, the -s option accepts URL as its argument:

  poundctl -s https://user:password@hostname:8080/path

Additionally, the following new options are implemented:

• -C FILE
  Load CA certificates from FILE. If FILE is a directory, all PEM files will be loaded from it.

• -K FILE
  Load client certificate and key from FILE. During TLS handshake, send them to the peer for authentication.

• -k
  Insecure mode: disable peer verification.

• -S NAME
  Take settings for server NAME from the poundctl configuration file (see below).

.poundctl

The file .poundctl in user home directory provides configuration settings for the poundctl command. Syntactically, it is similar to pound.cfg. Upon startup, poundctl first checks if ~/.poundctl exists and reads it if so. If the program cannot determine the URL of the control socket from it (possibly using the argument to the -S option, if given), it scans the pound configuration file (if it exists), looking for Control statement. Finally, if neither method determines the URL, poundctl requires the user to supply the -s option.

The default name and location of the poundctl configuration file can be changed using the environment variable POUNDCTL_CONF. Setting it to empty string disables the configuration mechanism altogether.

configure

Removed historic --with-owner and --with-group options.