Using Varnish to set a Maintenance Page on your website

There may come a time when you would like to perform a fairly major update to your website, but you don’t want to be serving out semi-broken pages while you update your stylesheets, javascript files or static image assets. Without re-configuring Apache to point to an alternative DocumentRoot, how might you display a simple maintenance page to avoid this? What if you need to take Apache offline (even momentarily) to update some of the dependency modules? Or what if you finally want to do that upgrade from Lighttpd to Apache? What will serve out your Maintenance Page while your webserver is offline?

If you use an HTTP accelerator like Varnish, you can use it to serve out a simple Maintenance Page whilst you do your updates in the background. Instead of passing through incoming requests to your Apache back-end, and then caching them for subsequent requests, Varnish will simply respond with the Maintenance Page that you design.

Sound like something you might want to do? Well, here’s how (on Red Hat and clones):

Create a Varnish VCL configuration file somewhere on your Linux system. My default Varnish configuration file lives in /etc/varnish/default.vcl, so I chose to put my new Varnish Maintenance configuration file at /etc/varnish/maintenance.vcl. This new file should have the following contents (you may need to change small details like the backend host and port to match your specific configuration):

# /etc/varnish/maintenance.vcl
backend default {
    .host = "";
    .port = "8000";
sub vcl_recv {
    error 503;
sub vcl_error {
    set obj.http.Content-Type = "text/html; charset=utf-8";
    # Create your Maintenance Page here
    synthetic {"We're currently down for maintenance.

We’re currently down for maintenance.

We won’t be long, so please check back soon. Thanks for your patience.

    return (deliver);

This file, /etc/varnish/maintenance.vcl, can live on your filesystem without ever impacting the day-to-day operation of your website. Varnish will still load its default configuration on startup, and it will only use your new Maintenance configuration if you tell it to.

So, how do you tell it to? When you’re ready to start your website updates and want to start displaying your Maintenance Page, you simply log onto your server and run the following commands:

varnishadm vcl.load maintenance_mode /etc/varnish/maintenance.vcl

This will create a new Varnish profile, called maintenance_mode. Note that at the moment, Varnish is still serving normal website content; all you’ve done is made it aware of an alternative configuration to the one it normally uses.

varnishadm vcl.use maintenance_mode

Now we’ve activated the new maintenance_mode configuration profile. You should find that if you attempt to load your webpage, Varnish returns your Maintenance Page. You should find that there are no hits in the Apache web logs, and you should also find that if you hit Apache directly, you will see your regular website (but you’ve got a firewall in place to stop every Tom, Dick and Harry doing that, right?). If you’ve got multiple hosts serving the same website content through a load-balancer, you’ll obviously need to run the commands above on each webserver separately.

You’re now ready to start your maintenance. You can take as long as you need at this point, because Varnish has your back. If you’re going to be a while, I would mention an estimated time when you expect your website to be back online on the Maintenance Page, to prevent people getting annoyed if they keep checking back before your new website is back up.

You can stop and start services to your heart’s content, with the obvious exception of Varnish! You can pretty do whatever you want behind the scenes, as Varnish won’t pass any traffic back to Apache.

Once you’ve finished making your updates, and you’re ready to launch your shiny new website, you simply run the following command:

varnishadm vcl.use boot

This will revert Varnish back to it’s default (startup) configuration, and you should find that it starts loading your updated website just as it did previously.

Hope you found that useful!

1 thought on “Using Varnish to set a Maintenance Page on your website

Leave a Reply

Your email address will not be published. Required fields are marked *