1VCL-PROBE(7) VCL-PROBE(7)
2
6 VCL-probe - Configuring Backend Health Probes
7
9 Varnish can be configured to periodically send a request to test if a
10 backend is answering and thus "healthy".
11 Probes can be configured per backend:
13 backend foo {
15 [...]
16 .probe = {
17 [...]
18 }
19 }
20 They can be named and shared between backends:
22 probe light {
24 [...]
25 }
26 backend foo {
28 .probe = light;
29 }
30 backend bar {
32 .probe = light;
33 }
34 Or a default probe can be defined, which applies to all backends with‐
36 out a specific .probe configured:
37 probe default {
39 [...]
40 }
41 The basic syntax is the same as for backends:
43 probe name {
45 .attribute1 = value;
46 .attribute2 = "value";
47 [...]
48 }
49 There are no mandatory attributes, they all have defaults.
51
53 The URL to query. Defaults to /:
54 .url = "/health-probe";
56
58 Can be used to specify a full HTTP/1.1 request to be sent:
59 .request = "GET / HTTP/1.1"
61 "Host: example.com"
62 "X-Magic: We're fine with this."
63 "Connection: close";
64 Each of the strings will have CRNL appended and a final HTTP header
66 block terminating CRNL will be appended as well.
67 Because connection shutdown is part of the health check, Connection:
69 close is mandatory.
70
72 The expected HTTP status, defaults to 200:
73 .expected_response = 418;
75
77 Whether or not to expect the backend to close the underlying connec‐
78 tion.
79 Accepts true or false, defaults to true:
81 .expect_close = false;
83 Warning: when the backend does not close the connection, setting ex‐
85 pect_close to false makes probe tasks wait until they time out before
86 inspecting the response.
87
89 How fast the probe must succeed, default is two seconds:
90 .timeout = 10s;
92
94 Time between probes, default is five seconds:
95 .interval = 1m;
97
99 Backend health probes uses a 64 stage shift register to remember the
100 most recent health probes and to evaluate the total health of the back‐
101 end.
102 In the CLI, a good backend health status looks like this:
104 varnish> backend.list -p boot.backend
106 Backend name Admin Probe Health Last change
107 boot.backend probe 5/5 healthy Wed, 13 Jan 2021 10:31:50 GMT
108 Current states good: 5 threshold: 4 window: 5
109 Average response time of good probes: 0.000793
110 Oldest ================================================== Newest
111 4444444444444444444444444444444444444444444444444444444444444444 Good IPv4
112 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX Good Xmit
113 RRRRRRRRRRRRRRRRRRRRRRR----RRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRR Good Recv
114 HHHHHHHHHHHHHHHHHHHHHHH--------HHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHH Happy
115 Starting from the bottom, the last line shows that this backend has
117 been declared "Happy" for most the 64 health probes, but there were
118 some trouble some while ago.
119 However, in this case the .window is configured to five, and the
121 .threshold is set to four, so at this point in time, the backend is
122 considered fully healthy.
123 An additional .initial fills that many "happy" entries in the shift
125 register when the VCL is loaded, so that backends can quickly become
126 healthy, even if their health is normally considered over many samples:
127 .interval = 1s;
129 .window = 60;
130 .threshold = 45;
131 .initial = 43;
132 This backend will be considered healthy if three out of four health
134 probes in the last minute were good, but it becomes healthy as soon as
135 two good probes have happened after the VCL was loaded.
136 The default values are:
138 • .window = 8
140 • .threshold = 3
142 • .initial = one less than .threshold
144 Note that the default .initial means that the backend will be marked
146 unhealthy until the first probe response come back successful. This
147 means that for backends created on demand (by vmods) cannot use the de‐
148 fault value for .initial, as the freshly created backend would very
149 likely still be unhealthy when the backend request happens.
150 SEE ALSO
152 • varnishd(1)
153 • vcl(7)
155 • vcl-backend(7)
157 • vmod_directors(3)
159 • vmod_std(3)
161 HISTORY
163 VCL was developed by Poul-Henning Kamp in cooperation with Verdens Gang
164 AS, Redpill Linpro and Varnish Software. This manual page is written
165 by Per Buer, Poul-Henning Kamp, Martin Blix Grydeland, Kristian Lyn‐
166 gstøl, Lasse Karstensen and others.
167 COPYRIGHT
169 This document is licensed under the same license as Varnish itself. See
170 LICENSE for details.
171 • Copyright (c) 2006 Verdens Gang AS
173 • Copyright (c) 2006-2021 Varnish Software AS
175 VCL-PROBE(7)