1VCL-BACKENDS(7) VCL-BACKENDS(7)
2
6 VCL-backends - Configuring Backends
7
9 A backend declaration creates and initialises a named backend object.
10 A declaration start with the keyword backend followed by the name of
11 the backend. The actual declaration is in curly brackets, in a
12 key/value fashion.:
13 backend name {
15 .attribute1 = value;
16 .attribute2 = value;
17 [...]
18 }
19 If there is a backend named default it will be used unless another
21 backend is explicitly set. If no backend is named default the first
22 backend in the VCL program becomes the default.
23 If you only use dynamic backends created by VMODs, an empty, always
25 failing (503) backend can be specified:
26 backend default none;
28 A backend must be specified with either a .host or a .path attribute,
30 but not both. All other attributes have default values.
31
33 To specify a networked backend .host takes either a numeric IPv4/IPv6
34 address or a domain name which resolves to at most one IPv4 and one
35 IPv6 address:
36 .host = "127.0.0.1";
38 .host = "[::1]:8080";
40 .host = "example.com:8081";
42 .host = "example.com:http";
44
46 The TCP port number or service name can be specified as part of .host
47 as above or separately using the .port attribute:
48 .port = "8081";
50 .port = "http";
52
54 The absolute path to a Unix(4) domain socket of a local backend:
55 .path = "/var/run/http.sock";
57 or, where available, @ followed by the name of an abstract socket of a
59 local backend:
60 .path = "@mybackend";
62 A warning will be issued if the uds-socket does not exist when the VCL
64 is loaded. This makes it possible to start the UDS-listening peer, or
65 set the socket file's permissions afterwards.
66 If the uds-socket socket does not exist or permissions deny access,
68 connection attempts will fail.
69
71 A host header to add to probes and regular backend requests if they
72 have no such header:
73 .host_header = "Host: example.com";
75
77 These attributes control how patient varnishd is during backend
78 fetches:
79 .connect_timeout = 1.4s;
81 .first_byte_timeout = 20s;
82 .between_bytes_timeout = 10s;
83 The default values comes parameters with the same names, see var‐
85 nishd(1).
86
88 Limit how many simultaneous connections varnish can open to the back‐
89 end:
90 .max_connections = 1000;
92
94 Send a PROXY protocol header to the backend with the client.ip and
95 server.ip values:
96 .proxy_header = 2;
98 Legal values are one and two, depending which version of the PROXY pro‐
100 tocol you want.
101 Notice this setting will lead to backend connections being used for a
103 single request only (subject to future improvements). Thus, extra care
104 should be taken to avoid running into failing backend connections with
105 EADDRNOTAVAIL due to no local ports being available. Possible options
106 are:
107 • Use additional backend connections to extra IP addresses or TCP
109 ports
110 • Increase the number of available ports (Linux sysctl
112 net.ipv4.ip_local_port_range)
113 • Reuse backend connection ports early (Linux sysctl
115 net.ipv4.tcp_tw_reuse)
116
118 Send a BLOB on all newly opened connections to the backend:
119 .preamble = :SGVsbG8gV29ybGRcbgo=:;
121
123 Name of another proxy backend through which to make the connection to
124 the destination backend using the PROXY2 protocol, for example:
125 backend proxy {
127 .path = "/path/to/proxy2_endpoint";
128 }
129 backend destination {
130 .host = "1.2.3.4";
131 .via = proxy;
132 }
133 The proxy backend can also use a .host/.port definition rather than
135 .path.
136 Use of the .path attribute for the destination backend is not sup‐
138 ported.
139 The .via attribute is unrelated to .proxy_header. If both are used, a
141 second header is sent as per .proxy_header specification.
142 As of this release, the proxy backend used with .via can not be a di‐
144 rector, it can not itself use .via (error: Can not stack .via backends)
145 and the protocol is fixed to PROXY2.
146 Implementation detail:
148 If .via = <proxy> is used, a PROXY2 preamble is created with the desti‐
150 nation backend's address information as dst_addr/dst_port and, option‐
151 ally, other TLV attributes. The connection is then made to the proxy
152 backend's endpoint (path or host/port). This is technically equivalent
153 to specifying a backend destination_via_proxy with a .preamble attri‐
154 bute containing the appropriate PROXY2 preamble for the destination
155 backend.
156
158 The HTTP authority to use when connecting to this backend. If unset,
159 .host_header or .host are used.
160 .authority = "" disables sending an authority.
162 As of this release, the attribute is only used by .via connections as a
164 PP2_TYPE_AUTHORITY Type-Length-Value (TLV) in the PROXY2 preamble.
165
167 Please see vcl-probe(7).
168
170 • varnishd(1)
171 • vcl(7)
173 • vcl-probe(7)
175 • vmod_directors(3)
177 • vmod_std(3)
179
181 VCL was developed by Poul-Henning Kamp in cooperation with Verdens Gang
182 AS, Redpill Linpro and Varnish Software. This manual page is written
183 by Per Buer, Poul-Henning Kamp, Martin Blix Grydeland, Kristian Lyn‐
184 gstøl, Lasse Karstensen and others.
185
187 This document is licensed under the same license as Varnish itself. See
188 LICENSE for details.
189 • Copyright (c) 2006 Verdens Gang AS
191 • Copyright (c) 2006-2021 Varnish Software AS
193 VCL-BACKENDS(7)