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) defines minimum 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

Notice, that an SRV record can have a weight of 0. This will translate to pound backend priority 0, which is normally not allowed (see Request balancing). According to RFC 2782, this is the preferred way of defining weights where “there isn’t any server selection to do”, whereas “[i]n the presence of records containing weights greater than 0, records with weight 0 should have a very small chance of being selected”. Pound handles this as follows: if all SRV records have zero weight, priority of the resulting backends is set to 1. This makes sure the backend selection algorithm works and gives each backend equal chance of being selected. This translation does not take place, however, if at least one of SRV records has a weight greater than 0. Another way to handle such records is using the IgnoreSRVWeight configuration statement, which is discussed below.

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 statement for dynamic backends of srv resolve type. Normally, you don’t need to supply Priority, either. However, you may do so, if you wish to override the weight settings from SRV records. In that case, inform pound about your decision using the following statement in Backend section:

IgnoreSRVWeight true

There are several possible scenarios when this may be needed. One of them is when all SRV records have weight of 0 (see above) and your configuration defines one or more regular backends in the same balancer group as backends generated by those records. In that case, the default priority assigned by pound to those generated backends (1) may prove to be too low for adequate balancing. Using IgnoreSRVWeight allows you to fix that. For example:

Service
        Backend
                Address 192.0.2.15
                Port 80
                Priority 8
        End
        Backend
                Address "_proxy._tcp.example.org"
                Resolve srv
                Family any
                IgnoreSRVWeight true
                Priority 5
        End
End

In this example, backends generated by SRV records for domain ‘_proxy._tcp.example.org’ will be assigned priority 5, no matter what the actual value of SRV weight field.

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).