SearchThe maintenance file is a file-based mechanism that allows the agent to signal maintenance status to
the Traffic Router. When the maintenance file exists on disk, the agent reports its health status as
maintenance instead of healthy, which causes the Traffic Router to stop routing new traffic to
that Varnish node.
Each agent monitors a maintenance file on disk. By default this file is located at
<base-dir>/<agent-name>/maintenance. The agent checks for the presence of this file once per
second.
When the maintenance file is detected:
maintenance in the health check JSON file
(traffic_router_health.json).Stop Routing flag in the database. This visualizes it in the UI and CLI.When the maintenance file is removed, the reverse happens and the agent is restored to healthy
status and becomes available for routing again.
The path to the maintenance file can be configured with the maintenance-file argument:
| Parameter | Default | Description |
|---|---|---|
maintenance-file |
<base-dir>/<agent-name>/maintenance |
Path to the maintenance file on disk. |
This parameter can be set via command-line flag, environment variable, or configuration file as described in Config/ConfigSets.
There are two ways to put an agent into maintenance mode:
Using the stop-routing / resume-routing commands sends a NATS message from brainz to the agent,
which creates or removes the maintenance file automatically.
See Drain Traffic for details on using the CLI, UI, and API.
The maintenance file can also be created or removed directly on the agent’s host. This is useful for automation tools (e.g. Ansible, shell scripts) or situations where the Controller API is not available.
Creating an empty file at the maintenance file path puts the agent into maintenance mode:
touch /var/lib/varnish-controller/agent1/maintenance
Removing it resumes normal operation:
rm /var/lib/varnish-controller/agent1/maintenance
The agent detects the change within one second and updates its status accordingly.
Maintenance mode does not undeploy any VCL configuration from the Varnish instance. The Varnish node continues to serve traffic for clients that reach it directly or through cached DNS records. Maintenance mode only removes the agent from Traffic Router selection, preventing new clients from being routed to it.
This is an important distinction: maintenance mode is a routing-level operation, not a deployment-level operation.