VCL-backends(7) Miscellaneous Information Manual VCL-backends(7)

# [Name](#Name)

VCL-backends - Configuring Backends

# [Backend definition](#Backend_definition)

A backend declaration creates and initialises a named backend object. A declaration start with the keyword **backend** followed by the name of the backend. The actual declaration is in curly brackets, in a key/value fashion.:

```
backend name {


    .attribute1 = value;


    .attribute2 = value;


    [...]
}
```

If there is a backend named **default** it will be used unless another backend is explicitly set. If no backend is named **default** the first backend in the VCL program becomes the default.

If you only use dynamic backends created by VMODs, an empty, always failing (503) backend can be specified:

```
backend default none;
```

A backend must be specified with either a **.host** or a **.path** attribute, but not both. All other attributes have default values.

# [Attribute .host](#Attribute_.host)

To specify a networked backend **.host** takes either a numeric IPv4/IPv6 address or a domain name which resolves to *at most* one IPv4 and one IPv6 address:

```
.host = "127.0.0.1";
.host = "[::1]:8080";
.host = "example.com:8081";
.host = "example.com:http";
```

# [Attribute .port](#Attribute_.port)

The TCP port number or service name can be specified as part of **.host** as above or separately using the **.port** attribute:

```
.port = "8081";
.port = "http";
```

Defaults to 80 if **.ssl** is set to 0, 443 otherwise.

# [Attribute .path](#Attribute_.path)

The absolute path to a [Unix(4)](/man/os/varnish/Unix.4) domain socket of a local backend:

```
.path = "/var/run/http.sock";
```

or, where available, **@** followed by the name of an abstract socket of a local backend:

```
.path = "@mybackend";
```

A warning will be issued if the uds-socket does not exist when the VCL is loaded. This makes it possible to start the UDS-listening peer, or set the socket file's permissions afterwards.

If the uds-socket socket does not exist or permissions deny access, connection attempts will fail.

# [Attribute .host\_header](#Attribute_.host_header)

A host header to add to probes and regular backend requests if they have no such header:

```
.host_header = "example.com";
```

# [HTTPS/TLS Attributes](#HTTPS/TLS_Attributes)

The **.ssl\*** attributes control how Varnish connect to the backend using TLS:

```
.ssl = 1;
.ssl_sni = 0;
.ssl_verify_peer = 0;
.ssl_verify_host = 1;
```

For all of these, 0 means "activated" and 1 "deactivated". If **.ssl** is deactivated, the others have no effect.

**.ssl \[default: 0]**

Set to 1 to activate HTTPS connection to the backend. By default the connections will have an SNI extension name provided during negotiation.

This defaults to the **.host** attribute, unless if the **.host\_header** attribute is set in which case that will be used instead.

Activating HTTPS also changess the default **.port** value to 443.

**.ssl\_sni \[default: 1]**

Set this to 0 to disable the use of the Server Name Indication (SNI) extension for backend TLS connections. SNI allows a backend to serve multiple TLS domains over a single IP and port.

The SNI name defaults to the backend **.host** value, unless **.host\_header** is defined, in which case it will be used as the SNI name.

**.ssl\_verify\_peer \[default: 1]**

Set this to 0 to disable verification of the peer’s certificate chain.

This allows a backend to use a self signed certificate.

**.ssl\_verify\_host \[default: 0]**

Set this to 1 to enable verification of the peer’s certificate identity. The identity in the certificate is verified against the name configured in the **.host attribute**, unless **.host\_header** is set in which case that is used instead.

If set to 0, this allows a backend to use an invalid certificate.

**.ssl\_ca\_file \[default: none]**

Path to a PEM file with one or more CA certificates to verify the backend certificate against, instead of the system default CA store:

```
.ssl_ca_file = "/etc/varnish/backend-ca.pem";
```

The file must exist and be readable when the VCL is loaded, or the load will fail.

The file is read when the backend's connection pool is created. Changes to it on disk take effect only once all VCLs referencing the backend are discarded, or *varnishd* is restarted. The same applies to the system default CA store, which is read at startup.

# [Timeout Attributes](#Timeout_Attributes)

These attributes control how patient *varnishd* is during backend fetches:

```
.connect_timeout = 1.4s;
.first_byte_timeout = 20s;
.between_bytes_timeout = 10s;
```

The default values comes parameters with the same names, see [*varnishd(1)*](/man/os/varnish/varnishd.1).

# [Attribute .max\_connections](#Attribute_.max_connections)

Limit how many simultaneous connections varnish can open to the backend:

```
.max_connections = 1000;
```

# [Attribute .wait\_limit](#Attribute_.wait_limit)

Maximum number of transactions that can queue waiting for a backend connection to become available:

```
.wait_limit = 1000;
```

Note that this feature must be used with caution, as it can cause threads to pile up and increase response times.

Defaults to the [*varnishd(1)*](/man/os/varnish/varnishd.1) *backend\_wait\_limit* parameter.

# [Attribute .wait\_timeout](#Attribute_.wait_timeout)

When a transaction is queued waiting for a backend connection to become available (see *.wait\_limit*), this is the time that the transaction will wait before giving up:

```
.wait_timeout = 1s;
```

It is strongly advised to never set this higher than a couple of seconds.

Defaults to the [*varnishd(1)*](/man/os/varnish/varnishd.1) *backend\_wait\_timeout* parameter.

# [Attribute .proxy\_header](#Attribute_.proxy_header)

Send a PROXY protocol header to the backend with the **client.ip** and **server.ip** values:

```
.proxy_header = 2;
```

Legal values are one and two, depending which version of the PROXY protocol you want.

*Notice* this setting will lead to backend connections being used for a single request only (subject to future improvements). Thus, extra care should be taken to avoid running into failing backend connections with EADDRNOTAVAIL due to no local ports being available. Possible options are:

- Use additional backend connections to extra IP addresses or TCP ports
- Increase the number of available ports (Linux sysctl **net.ipv4.ip\_local\_port\_range**)
- Reuse backend connection ports early (Linux sysctl **net.ipv4.tcp\_tw\_reuse**)

# [Attribute .preamble](#Attribute_.preamble)

Send a BLOB on all newly opened connections to the backend:

```
.preamble = :SGVsbG8gV29ybGRcbgo=:;
```

# [Attribute .via](#Attribute_.via)

Name of another *proxy* backend through which to make the connection to the *destination* backend using the PROXY2 <https://raw.githubusercontent.com/haproxy/haproxy/master/doc/proxy-protocol.txt> protocol, for example:

```
backend proxy {


  .path = "/path/to/proxy2_endpoint";
}
backend destination {


  .host = "1.2.3.4";


  .via = proxy;
}
```

The *proxy* backend can also use a **.host**/**.port** definition rather than **.path**.

Use of the **.path** attribute for the *destination* backend is not supported.

The **.via** attribute is unrelated to **.proxy\_header**. If both are used, a second header is sent as per **.proxy\_header** specification.

Unless specified for *destination*, the **connect\_timeout**, **first\_byte\_timeout** and **between\_bytes\_timeout** attributes are copied from *proxy* to *destination*.

As of this release, the *proxy* backend used with **.via** cannot be a director, it cannot itself use **.via** (error: *Cannot stack .via* *backends*) and the protocol is fixed to PROXY2 <https://raw.githubusercontent.com/haproxy/haproxy/master/doc/proxy-protocol.txt>.

Implementation detail:

If **.via = <proxy>** is used, a PROXY2 <https://raw.githubusercontent.com/haproxy/haproxy/master/doc/proxy-protocol.txt> preamble is created with the *destination* backend's address information as **dst\_addr**/**dst\_port** and, optionally, other TLV attributes. The connection is then made to the *proxy* backend's endpoint (**path** or **host**/**port**). This is technically equivalent to specifying a **backend** **destination\_via\_proxy** with a **.preamble** attribute containing the appropriate PROXY2 <https://raw.githubusercontent.com/haproxy/haproxy/master/doc/proxy-protocol.txt> preamble for the *destination* backend.

# [Attribute .authority](#Attribute_.authority)

The HTTP authority to use when connecting to this backend. If unset, **.host\_header** or **.host** are used.

**.authority = ""** disables sending an authority.

**.authority** can not be an IP address.

A colon and anything following (signifying a port) is removed from the authority.

As of this release, the attribute is only used by **.via** connections as a **PP2\_TYPE\_AUTHORITY** Type-Length-Value (TLV) in the PROXY2 <https://raw.githubusercontent.com/haproxy/haproxy/master/doc/proxy-protocol.txt> preamble.

# [Attribute .probe](#Attribute_.probe)

Please see [*vcl-probe(7)*](/man/os/varnish/vcl-probe.7).

# [SEE ALSO](#SEE_ALSO)

- [*varnishd(1)*](/man/os/varnish/varnishd.1)
- [*vcl(7)*](/man/os/varnish/vcl.7)
- [*vcl-probe(7)*](/man/os/varnish/vcl-probe.7)
- [*vmod\_directors(3)*](/man/os/varnish/vmod_directors.3)
- [*vmod\_std(3)*](/man/os/varnish/vmod_std.3)

# [HISTORY](#HISTORY)

VCL was developed by Poul-Henning Kamp in cooperation with Verdens Gang AS, Redpill Linpro and Varnish Software. This manual page is written by Per Buer, Poul-Henning Kamp, Martin Blix Grydeland, Kristian Lyngstøl, Lasse Karstensen and others.

# [COPYRIGHT](#COPYRIGHT)

This document is licensed under the same license as Varnish itself. See LICENSE for details.

- Copyright (c) 2006 Verdens Gang AS
- Copyright (c) 2006-2021 Varnish Software AS

---

Document: vcl-backend(7) from varnish 9.1.0-r3 (Chainguard OS)
Source: https://github.com/varnish/varnish