Showing a maintenance message

1. The problem I’m having:

When I create a special file on disk I want to show a (maintenance) message instead of passing requests on to a reverse_proxy.

The provided config should work but I am wondering:

  1. Could I deliver the content of the file “message.html” for (all requests) and still return a 503?

  2. What is the performance impact of the file check? Will it check on disk for every request?

Or is there a better way of doing this?

2. Error messages and/or full log output:


3. Caddy version:

$ caddy version

4. How I installed and ran Caddy:

NixOS via systemd

/nix/store/1cvy9h1k8lfc9na97g8fx6iy6sr5i3dz-caddy-2.7.6/bin/caddy run --config /etc/caddy/caddy_config --adapter caddyfile

a. System environment:

NixOS, arm

b. Command:


c. Service/unit/compose file:


d. My complete Caddy config:

    log {
        level ERROR
} {
    log {
        output file /var/log/caddy/

    # if file "message.html" exist on disk show it

    root * /etc/caddy/message

    @exists {
      file message.html

    handle @exists {
      respond "We will be back shortly" 503 {

    # otherwise pass on to proxy

    handle {
      reverse_proxy echo1.default.svc.cluster.local:80

    tls internal

5. Links to relevant resources:

Yeah, you can override the status that file_server writes, see the docs. file_server (Caddyfile directive) — Caddy Documentation

Yes, but syscalls for files are fast and generally cached, so it’s fine.

1 Like

you can override the status that file_server writes, see the docs

Hm. But when the request is for /foo.html it would try to server foo.html, no?
And I would still want to serve message.html instead.

Then use a rewrite beforehand to change the path for the file to serve. Examples here: handle_errors (Caddyfile directive) — Caddy Documentation

In fact, you could just trigger an error when in maintenance, and then use handle_errors to serve the page.

@maintenance file /message.html
error @maintenance 503

handle_errors {
	@503 `{err.status_code} in [503]`
	handle @503 {
		rewrite * /message.html

The file_server directive is implemented such that if there’s an error in the stack, it’ll use the status code from that error when serving the file.


Thanks for the help again! :heart:

1 Like