VCL-PROBE(7)

💖 VCL-probe — Configuring Backend Health Probes 💖

okay bestie, welcome to VCL-PROBE(7), straight out of the Miscellaneous Information Manual (section 7, the cool section). this is the page about making Varnish poke your backends to check if they're still alive. let's get into it 🫶

---

🌸 BACKEND HEALTH PROBES 🌸

so here's the tea: Varnish can be set up to periodically send a request to test if a backend is answering, and therefore "healthy". yes, it's literally a vibe check for your servers. 💅

Probes can be configured per backend, like this:

backend foo {
    [...]
    .probe = {
        [...]
    }
}

They can also be named and shared between backends — friendship bracelets but for probes:

probe light {
    [...]
}

backend foo {
    .probe = light;
}

backend bar {
    .probe = light;
}

Or you can define a default probe, which applies to all backends that don't have their own specific .probe configured. main character behavior honestly:

probe default {
    [...]
}

The basic syntax is the same as for backends:

probe name {
    .attribute1 = value;
    .attribute2 = "value";
    [...]
}

And here's the thing — there are no mandatory attributes, they all have defaults. no cap. everything's optional. 😌

---

✨ ATTRIBUTE .URL ✨

The URL to query. Defaults to /:

.url = "/health-probe";

---

✨ ATTRIBUTE .REQUEST ✨

This one lets you specify a full HTTP/1.1 request to be sent:

.request = "GET / HTTP/1.1"
    "Host: example.com"
    "X-Magic: We're fine with this."
    "Connection: close";

Each of the strings will have CRLF appended, and a final HTTP header block terminating CRLF will be appended as well. slay.

Because connection shutdown is part of the health check, Connection: close is mandatory. like, non-negotiable bestie, don't skip it. 🚨

---

✨ ATTRIBUTE .EXPECTED_RESPONSE ✨

The expected HTTP status. Defaults to 200:

.expected_response = 418;

(and yes you can absolutely ask for 418 if that's your truth 💅)

---

✨ ATTRIBUTE .EXPECT_CLOSE ✨

Whether or not to expect the backend to close the underlying connection.

Accepts true or false, defaults to true:

.expect_close = false;

Warning: when the backend does not close the connection, setting expect_close to false makes probe tasks wait until they time out before inspecting the response. so like... slow. lowkey painful. 😭

---

✨ ATTRIBUTE .TIMEOUT ✨

How fast the probe must succeed. Default is two seconds:

.timeout = 10s;

---

✨ ATTRIBUTE .INTERVAL ✨

Time between probes. Default is five seconds:

.interval = 1m;

---

👑 THE BACKEND HEALTH SHIFT REGISTER 👑

Backend health probes use a 64 stage shift register to remember the most recent health probes and to evaluate the total health of the backend. it's giving memory, it's giving receipts. 🧚

In the CLI, a good backend health status looks like this:

varnish> backend.list -p boot.backend
Backend name    Admin    Probe    Health     Last change
boot.backend    probe    5/5      healthy    Wed, 13 Jan 2021 10:31:50 GMT
 Current states  good:  5 threshold:  4 window:  5
  Average response time of good probes: 0.000793
  Oldest ================================================== Newest
  4444444444444444444444444444444444444444444444444444444444444444 Good IPv4
  XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX Good Xmit
  RRRRRRRRRRRRRRRRRRRRRRR----RRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRR Good Recv
  HHHHHHHHHHHHHHHHHHHHHHH--------HHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHH Happy

Starting from the bottom, the last line shows that this backend has been declared "Happy" for most of the 64 health probes, but there were some trouble some while ago. we've all been there. 🙈

However — in this case the .window is configured to five, and the .threshold is set to four, so at this point in time, the backend is considered fully healthy. healed era. ✨

An additional .initial fills that many "happy" entries in the shift register when the VCL is loaded, so that backends can quickly become healthy, even if their health is normally considered over many samples:

.interval = 1s;
.window = 60;
.threshold = 45;
.initial = 43;

This backend will be considered healthy if three out of four health probes in the last minute were good, but it becomes healthy as soon as two good probes have happened after the VCL was loaded.

The default values are:

• .window = 8
• .threshold = 3
• .initial = one less than .threshold

Note that the default .initial means that the backend will be marked unhealthy until the first probe response come back successful. This means that for backends created on demand (by vmods) cannot use the default value for .initial, as the freshly created backend would very likely still be unhealthy when the backend request happens. so like, heads up bestie, that's a whole trap. 💀

---

🦋 SEE ALSO 🦋

• varnishd(1)
• vcl(7)
• vcl-backend(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. legends only. 👑

---

💜 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

---

and that's the whole page bestie!! 🫶 this was VCL-PROBE(7) from the Miscellaneous Information Manual, part of the Varnish docs, written by the Varnish crew (Poul-Henning Kamp, Verdens Gang AS, Redpill Linpro, Varnish Software — the icons fr fr). go forth and probe responsibly. mwah. 💖✨🎀