Backend (Pound)

9.11.4.1 Backend

The Backend section defines a regular backend. The overall syntax, as for any section statement, is:

Backend [ "name" ]
  …
End

Optional name argument assigns a symbolic name to the service. That name is used to identify the backend in diagnostic and access log messages (see ‘%{obj}N’), metric output (see Metrics), and in poundctl requests (see poundctl). In the absence of an assigned name, the ordinal (0-based) number of the backend in the enclosing Service is used as its identifier.

The following statements can be used in a Backend section:

Backend directive: Address IP ¶

IP address or host name of the backend server. If the name cannot be resolved to a valid address, pound will assume that it represents a path to a Unix-domain socket.

This directive is mandatory.

Backend directive: Disabled bool ¶

Mark this backend as disabled.

Backends can be enabled or disabled at runtime using the poundctl utility (see enable).

Note: not to be confused with the Disable statement, described below.

Backend directive: Port n ¶: Sets the port number to connect to. This directive must be present if the Address statement contains an IP address.

Backend directive: Priority n ¶

Sets numeric priority for this backend. Priorities are used to control probability of receiving a request for handling in case of multiple backends. See Request balancing, for a detailed discussion.

Allowed values for n are 1 to 65535.

Following directives configure dynamic backends. see Dynamic backends, for a detailed discussion:

Backend directive: Family name ¶

Defines the address family to look for when resolving hostnames:

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

Backend directive: IgnoreSRVWeight bool ¶

When using SRV records, ignore their weight fields. Instead, copy priority of the producing backend to generated backends.

This directive is valid when used together with Resolve srv (see below).

Backend directive: OverrideTTL n ¶

This directive configures update interval (in seconds) for dynamic backends (see Dynamic backends). At the end of each update interval, the DNS be queried and dynamic backends reconfigured (if needed) according to its responses. By default, the TTL value obtained from previous DNS response is used.

To configure the interval to retry failed DNS lookups, see RetryInterval, below.

Backend directive: Resolve type ¶

Declares a dynamic backend. Valid values for type are

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

Backend directive: RetryInterval n ¶

Retry failed DNS lookups in n seconds. Default is 600.

See also the RetryInterval statement in Resolver section (see Resolver).

The following three directives set various timeout parameters for backend operations:

Backend directive: ConnTO n ¶: Sets connection timeout, i.e. time to wait for establishing connection with the backend (in seconds).

Backend directive: TimeOut n ¶: Sets the response timeout, i.e. time to wait for a response from the backend (in seconds). Default is 15.

Backend directive: WSTimeOut n ¶: Idle timeout for WebSocket operations, in seconds. Default value: 600 (10 minutes).

Backend servers can use HTTPS as well as plaintext HTTP. The following directives configure HTTPS backends:

Backend directive: HTTPS ¶: This directive indicates that the remote server speaks HTTPS.

Backend directive: Cert "filename" ¶: This specifies the certificate that pound will use as a client. The filename is the name of a file containing the certificate, possibly a certificate chain and the signature.

Backend directive: Ciphers "cipherlist" ¶: This is the list of ciphers that will be accepted by the SSL connection with the backend (for HTTPS backends); it is a string in the same format as used by the OpenSSL functions ciphers and SSL_CTX_set_cipher_list.

Backend directive: Disable proto ¶

Disable the SSL protocol proto and all earlier protocols. Allowed values for proto are: SSLv2, SSLv3, TLSv1, TLSv1_1, TLSv1_2.

Note: not to be confused with the Disabled statement, described above.

Backend directive: ServerName "name" ¶: This directive specifies the name to use for server name identification (SNI). It also rewrites the Host: header for this particular backend. This means you don’t have to use SetHeader in addition to it.