1VCL-PROBE(7)                                                      VCL-PROBE(7)
2
3
4

NAME

6       VCL-probe - Configuring Backend Health Probes
7

BACKEND HEALTH PROBES

9       Varnish  can  be configured to periodically send a request to test if a
10       backend is answering and thus "healthy".
11
12       Probes can be configured per backend:
13
14          backend foo {
15              [...]
16              .probe = {
17                  [...]
18              }
19          }
20
21       They can be named and shared between backends:
22
23          probe light {
24              [...]
25          }
26
27          backend foo {
28              .probe = light;
29          }
30
31          backend bar {
32              .probe = light;
33          }
34
35       Or a default probe can be defined, which applies to all backends  with‐
36       out a specific .probe configured:
37
38          probe default {
39              [...]
40          }
41
42       The basic syntax is the same as for backends:
43
44          probe name {
45              .attribute1 = value;
46              .attribute2 = "value";
47              [...]
48          }
49
50       There are no mandatory attributes, they all have defaults.
51

ATTRIBUTE .URL

53       The URL to query.  Defaults to /:
54
55          .url = "/health-probe";
56

ATTRIBUTE .REQUEST

58       Can be used to specify a full HTTP/1.1 request to be sent:
59
60          .request = "GET / HTTP/1.1"
61              "Host: example.com"
62              "X-Magic: We're fine with this."
63              "Connection: close";
64
65       Each  of  the  strings  will have CRNL appended and a final HTTP header
66       block terminating CRNL will be appended as well.
67
68       Because connection shutdown is part of the  health  check,  Connection:
69       close is mandatory.
70

ATTRIBUTE .EXPECTED_RESPONSE

72       The expected HTTP status, defaults to 200:
73
74          .expected_response = 418;
75

ATTRIBUTE .TIMEOUT

77       How fast the probe must succeed, default is two seconds:
78
79          .timeout = 10s;
80

ATTRIBUTE .INTERVAL

82       Time between probes, default is five seconds:
83
84          .interval = 1m;
85

THE BACKEND HEALTH SHIFT REGISTER

87       Backend  health  probes  uses a 64 stage shift register to remember the
88       most recent health probes and to evaluate the total health of the back‐
89       end.
90
91       In the CLI, a good backend health status looks like this:
92
93          varnish> backend.list -p boot.backend
94          Backend name    Admin    Probe    Health     Last change
95          boot.backend    probe    5/5      healthy    Wed, 13 Jan 2021 10:31:50 GMT
96           Current states  good:  5 threshold:  4 window:  5
97            Average response time of good probes: 0.000793
98            Oldest ================================================== Newest
99            4444444444444444444444444444444444444444444444444444444444444444 Good IPv4
100            XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX Good Xmit
101            RRRRRRRRRRRRRRRRRRRRRRR----RRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRR Good Recv
102            HHHHHHHHHHHHHHHHHHHHHHH--------HHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHH Happy
103
104       Starting  from  the  bottom,  the last line shows that this backend has
105       been declared "Happy" for most the 64 health  probes,  but  there  were
106       some trouble some while ago.
107
108       However,  in  this  case  the  .window  is  configured to five, and the
109       .threshold is set to four, so at this point in  time,  the  backend  is
110       considered fully healthy.
111
112       An  additional  .initial  fills  that many "happy" entries in the shift
113       register when the VCL is loaded, so that backends  can  quickly  become
114       healthy, even if their health is normally considered over many samples:
115
116          .interval = 1s;
117          .window = 60;
118          .threshold = 45;
119          .initial = 43;
120
121       This  backend  will  be  considered healthy if three out of four health
122       probes in the last minute were good, but it becomes healthy as soon  as
123       two good probes have happened after the VCL was loaded.
124
125       The default values are:
126
127       • .window = 8
128
129       • .threshold = 3
130
131       • .initial = one less than .threshold
132
133       Note  that  the  default .initial means that the backend will be marked
134       unhealthy until the first probe response come  back  successful.   This
135       means that for backends created on demand (by vmods) cannot use the de‐
136       fault value for .initial, as the freshly  created  backend  would  very
137       likely still be unhealthy when the backend request happens.
138
139   SEE ALSO
140       • varnishd(1)
141
142       • vcl(7)
143
144       • vcl-backend(7)
145
146       • vmod_directors(3)
147
148       • vmod_std(3)
149
150   HISTORY
151       VCL was developed by Poul-Henning Kamp in cooperation with Verdens Gang
152       AS, Redpill Linpro and Varnish Software.  This manual page  is  written
153       by  Per  Buer,  Poul-Henning Kamp, Martin Blix Grydeland, Kristian Lyn‐
154       gstøl, Lasse Karstensen and others.
155
156   COPYRIGHT
157       This document is licensed under the same license as Varnish itself. See
158       LICENSE for details.
159
160       • Copyright (c) 2006 Verdens Gang AS
161
162       • Copyright (c) 2006-2021 Varnish Software AS
163
164
165
166
167                                                                  VCL-PROBE(7)