6.3 Dynamic backends

Normally, when a backend is declared in configuration file, the value supplied with its Address statement is resolved at once and the resulting IP is associated with the backend. Such backends are static. You can also instruct pound to resolve the hostname and create as many backends as are the IP addresses it resolves to. Such backends are called dynamic. When a dynamic backend is requested, the Backend statement defines a matrix which will be used as a template to generate actual backends from the data in DNS. The TTL value of the DNS record (or records) will define the time to live of the generated backends. When it expires, DNS will be queried again and backends recreated according to the changes in its responses.⁵

In the simplest case, a dynamic backend can be created using A or AAAA DNS records. If several records correspond to the hostname defined in the Address statement, pound can either create a single backend for each of them, or select one of them in round-robin fashion and use it to create a backend. Rest of backend parameters (port value, priority, etc.) will be taken from its matrix declaration.

A more advanced way to create dynamic backends is using SRV records. Each SRV record has four associated parameters: priority, weight, target and port. The priority value defines the pound balancer group where to put generated backends. Weight is assigned as the priority for each generated backend. Finally, target is used as hostname to obtain IP addresses for the backends. For example, suppose the following DNS records are defined:

$ORIGIN _tcp.example.org.
; _srv  TTL     SRV     prio    weight  port target.
_proxy  60      SRV     10      40      8081 be0.example.org.
_proxy  60      SRV     10      70      8082 be1.example.org.
_proxy  60      SRV     20      10      8081 ha1.example.org.
_proxy  60      SRV     20      10      8081 ha2.example.org.

Assuming each of the target hostnames resolves to one IP address, these records will produce two balancer groups of two backends each, and will be roughly equivalent to the following statements:

Backend
        Address "be0.example.org"
        Port 8081
        Priority 40
End
Backend
        Address "be1.example.org"
        Port 8082
        Priority 70
End

Emergency
        Address "ha1.example.org"
        Port 8081
        Priority 10
End
Emergency
        Address "ha2.example.org"
        Port 8081
        Priority 10
End

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:

Dynamic Resolve: first

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

Dynamic Resolve: 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.

Dynamic Resolve: srv

Obtain SRV records for the host name and use them to generate dynamic 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 priority field determines the balancer group where the backend will be hosted.

When resolving hostnames, 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 (A DNS records).

inet6

Use only IPv6 addresses (AAAA DNS records).

For example:

Backend
        Address "_proxy._tcp.example.org"
	Resolve srv
	Family any
End

Notice, that you need not supply Port or Priority values for the dynamic backends of srv resolve type.

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 (see resolver).