At the AMA session during the recent Veeam 100 Summit in Lisbon, one feature request came up that I've heard many times before: Veeam needs a maintenance mode: Disable everything before an upgrade, and afterwards bring back exactly the state you had before. That includes the jobs that were intentionally disabled.
Until this exists in the product, Veeam's own KB2991 describes the manual way: disable all jobs in the console and note which ones were already disabled, so you know which ones not to re-enable later. With five jobs that's fine. With fifty jobs across VM backups, agent policies, backup copies, tape, plugins and CDP, someone always forgets the SureBackup job, or the copy job that was disabled on purpose months ago.
So after Lisbon I sat down and designed a PS script for it. 🤗
While testing, I noticed I wasn't the first to have this idea. Back in 2023, Martin Weber posted VEEAM Maintenance Mode PowerShell Scripts here on the Community Hub. It uses a similar approach: two scripts that save the job states to a JSON file, then disable and later restore them. It's worth a look. His scripts are based on Get-VBRJob, so they only cover the job types that cmdlet returns. Since then VBR has gained many job types with their own cmdlets, and some of them report their state differently. My script goes in a different direction there.
The idea
The script has no "enter" or "leave" switch. It checks for one file, VeeamJobState.json, in its own folder.
| Run | Condition | What happens |
|---|---|---|
| 1st run | No VeeamJobState.json | Saves the state of all jobs, disables the enabled ones, then runs a configuration backup |
| 2nd run | VeeamJobState.json exists | Re-enables only the jobs that were enabled before, then archives the state file |
Jobs that were disabled before maintenance stay disabled afterwards. After a successful restore, the state file is renamed to VeeamJobState.json.1, .2, .3 and so on. The history is kept, and the next run starts fresh.
What it covers
- VM backup and replication jobs, including NAS and file share, object storage, file copy and VM copy jobs
- CDP policies
- Veeam Agent jobs and agent policies managed by VBR
- Backup copy jobs
- Plugin policies like RMAN, SAP HANA or MSSQL
- Tape jobs
- SureBackup jobs
- Entra ID tenant backup jobs
- Other jobs that no specific cmdlet returns, such as Proxmox VE or Nutanix AHV, depending on the version
How it works
First run:
- Find all jobs and policies.
- Stop with an error if any job, Instant Recovery session or configuration backup is running. Nothing is changed.
- Save the state of every job to
VeeamJobState.json, before anything is changed. - Disable every job that is currently enabled.
- Read all job states again and report anything that didn't change.
- Run a configuration backup and wait for the result. This can be used if anything fails during your planned upgrade. Make sure to know your encryption PW for it! 😉
Second run:
- Re-enable only the jobs that were enabled before.
- Check the result.
- Archive the state file.
Running the configuration backup after disabling is intentional. If you have to roll back the configuration after a failed upgrade, your jobs come back disabled, so nothing starts against a half-upgraded environment. Run the script once more and they are enabled exactly as before.
I also deliberately chose not to stop running jobs automatically. If a full backup or a tape job is running, the script refuses to continue, and you decide whether to stop it or wait.
Usage
Run it on the VBR server in an elevated PowerShell session with a VBR administrator account.
# See what the script detects, without changing anything
.\Set-VeeamMaintenanceMode.ps1 -Report
# Enter maintenance mode
.\Set-VeeamMaintenanceMode.ps1
# ... upgrade ...
# Leave maintenance mode
.\Set-VeeamMaintenanceMode.ps1Unblock-File -Path .\Set-VeeamMaintenanceMode.ps1
Options
| Parameter | Purpose |
|---|---|
-Report | Lists every job with category, type, enabled state and running status. Nothing is changed. Run this first. |
-Force | Continues even if jobs or Instant Recovery sessions are running. Useful for backup copy jobs in immediate mode, which always appear as running. |
-SkipConfigBackup | Skips the configuration backup at the end. |
-SkipOtherJobs | Excludes jobs found only via the unsupported .NET call. |
-Server | VBR server to connect to. Default is localhost. |
Every run writes VeeamMaintenance_<timestamp>.log into the script folder, which you can attach to your change ticket. Also you find the recent states in the file if anything fails.
Lessons from the lab
- Jobs without a schedule can't be disabled with
Disable-VBRJob. VBR shows them as "Stopped" with "Not scheduled". The script logs a warning instead of an error. They can't start automatically, but someone could still start them by hand. - Tape jobs report
Enabled = Falsewhen they have no schedule, even if they aren't disabled. The script handles this, but check the-Reportoutput. - Plugin policies for RMAN, SAP HANA and similar are started from the database side. While they're disabled, those backups fail. Tell your DBAs before you start.
- Unsupported calls: to read some job states reliably, the script uses
[Veeam.Backup.Core.CBackupJob]. This isn't an official cmdlet and may change between versions. That's one more reason to run-Reportfirst. - Not covered: Veeam Backup for Microsoft 365, cloud-native policies for AWS, Azure and Google Cloud, and standalone agents. They run outside VBR.
Get the script
https://github.com/VeeamCoder/vbr-mmode
Until a maintenance mode is built into the product, this should save you some clicks and a few surprises. Test it in your lab first, and if you find a job type that isn't detected correctly, let me know in the comments.
Happy upgrading.
Mike
