VCL-BACKENDS(7)

🌸 VCL-BACKENDS(7) 🌸

okay bestie, welcome to the Miscellaneous Information Manual section, page VCL-BACKENDS(7). this is literally the page about configuring backends and it's gonna be so good, i promise 🫶

---

✨ NAME ✨

VCL-backends — configuring backends 💅

---

🎀 BACKEND DEFINITION 🎀

so a backend declaration creates and initialises a named backend object. it kicks off with the keyword backend, then the name of the backend, and the actual declaration lives inside curly brackets, key/value style, like:

backend name {
    .attribute1 = value;
    .attribute2 = value;
    [...]
}

if there's a backend named default, that one gets used unless another backend is explicitly set. and if literally nobody named a backend default, then the first backend in the VCL program becomes the default. periodt.

if you only use dynamic backends created by VMODs, you can specify an empty, always failing (503) backend like this:

backend default none;

a backend must be specified with either a .host or a .path attribute — but not both. every other attribute has default values. no cap. ✨

---

🌈 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 🦋

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

.port = "8081";

.port = "http";

---

🍓 ATTRIBUTE .PATH 🍓

the absolute path to a 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 💜

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

.host_header = "example.com";

---

⏰ 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 come from parameters with the same names, see varnishd(1).

---

🔥 ATTRIBUTE .MAX_CONNECTIONS 🔥

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

.max_connections = 1000;

---

🌸 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) backend_wait_limit parameter.

---

🧚 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. like, fr fr.

defaults to the varnishd(1) backend_wait_timeout parameter.

---

👑 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 🎀

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

.preamble = :SGVsbG8gV29ybGRcbgo=:;

---

🦋 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 ⭐

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 💖

please see vcl-probe(7). 🫶

---

🌟 SEE ALSO 🌟

• varnishd(1)
• vcl(7)
• vcl-probe(7)
• vmod_directors(3)
• vmod_std(3)

---

📜 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. iconic honestly 👑

---

💜 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

---

okay that's the whole thing bestie, you ate it 💅✨ and that's a wrap from VCL-BACKENDS(7) in the Miscellaneous Information Manual — catch you on the next page, mwah 🎀🦋🌈