Backup Commands
The policy commands manage each domain controller's backup schedule. The backup commands list and inspect restore points and start a backup outside the schedule. The jobs commands follow backup jobs and cancel one that is running.
For how backups are scheduled and stored, see How Backup Works and Backup Types. For how to run cdr and the global options, see Command-Line Reference.
Backup types are given as codes: bmr for a full system backup, which supports both DC state recovery and full system recovery, and systemstate for a DC state backup, which supports DC state recovery only.
policy list
Lists the backup schedules this installation holds: each machine's interval, start time, backup type, whether the schedule is enabled, and when it fires next. The STARTS column shows the start time in the Manager's local time, or any time for a schedule that runs on its interval alone. When a listed schedule has a start time, a hint under the table says that it is the earliest each backup is due, and that with many domain controllers on one time the last start later.
Requirements: The backup.view capability (every role).
Syntax
cdr policy list [options]
Options
| Option | Description |
|---|---|
-M, --machine <FQDN>
|
Only the schedule for this machine. |
-t, --type <CODE>
|
Only schedules of this backup type: bmr (Full system) or systemstate (DC state). |
--disabled
|
Only schedules that exist but are switched off. |
--due
|
Only schedules the Manager would start on its next check. |
--dc-state-only
|
Only machines with DC state backups, which require an OS that still boots and cannot do a full system recovery. |
Examples
cdr policy list --due cdr policy list --dc-state-only cdr policy list --machine dc01.corp.example.com --json
For a machine whose DC agent has never come online, the next-due time reads waiting for agent: the schedule is held, not failing, and its first backup runs as soon as the agent connects. Such a schedule is not listed by --due.
policy set
Creates or changes one machine's backup schedule. cdr reads the current schedule first, so an edit changes only what you give and keeps the rest. The machine does not need an agent yet, so you can schedule a domain controller before you deploy its agent. The command then says that no backup runs until a DC agent is installed and connects, and when the first backup then runs: at the schedule's start time if that is still ahead, or as soon as the agent connects if that is later. With no start time ahead, it runs as soon as the agent connects.
The interval is in minutes, from 5 minutes to 129,600 minutes (90 days). A new schedule takes full system backups, is enabled, and has no start time, unless you say otherwise. Without a start time, the Manager spreads backups around the interval.
--at sets a start time: 24-hour, in the Manager's local time. It is the earliest each backup is due; the backup then waits for a free backup slot. The interval must run at the same times every day: a whole number of days, or one that divides a day evenly (every 1, 2, 3, 4, 6, 8, or 12 hours, or a divisor of an hour). Otherwise cdr refuses the change before it reaches the Manager. This also applies when you change only the interval of a schedule that has a start time; the message then names the start time and tells you to give --at none or another interval. The before-and-after lines and the result show the start time, for example every 1d from 22:00 (manager time). After saving an enabled schedule with a start time, cdr asks the Manager how late the domain controllers on that time should start and prints a warning when they share it with more than Maximum concurrent backups allows at once. The schedule is saved either way.
Changing a schedule to DC state takes away full system recovery for that machine: if it is wiped or replaced, it must be rebuilt rather than restored. cdr warns you and asks for confirmation when an edit makes that change. Changing only the interval of a schedule that is already DC state does not ask again. In a script, pass --yes; without it, the change is refused when there is no terminal.
Requirements: The backup.manage capability (Backup Operator role).
Syntax
cdr policy set <FQDN> [options]
Arguments
| Argument | Description |
|---|---|
<FQDN>
|
Required. The machine to schedule. |
Options
| Option | Description |
|---|---|
-e, --every <MINUTES>
|
How often to back up, in minutes. Required when you create a schedule. Daily is 1440. |
-t, --type <CODE>
|
bmr (Full system) or systemstate (DC state). Default: bmr on a new schedule; unchanged on an edit. |
--at <TIME>
|
The earliest each backup starts, 24-hour, in the Manager's local time, for example 22:00. none removes the start time, so the schedule runs on its interval alone. Unchanged on an edit when not given. |
--disabled
|
Create the schedule switched off, or switch an existing one off. The interval, start time, and type are kept for later. |
--enabled
|
Switch an existing schedule back on. Cannot be combined with --disabled. |
--yes
|
Skip the confirmation that a DC state-only schedule removes full system recovery. |
Examples
cdr policy set dc01.corp.example.com --every 1440 cdr policy set dc01.corp.example.com --every 720 --type bmr cdr policy set dc01.corp.example.com --every 1440 --at 22:00 cdr policy set dc01.corp.example.com --at none cdr policy set dc01.corp.example.com --disabled cdr policy set dc01.corp.example.com --enabled
Exit codes: 0 when the schedule is saved, or when you decline the DC state confirmation (nothing is saved); 1 for an invalid option, such as a malformed --at time, an interval that cannot keep the start time, or a missing --every on a new schedule; 3 when the Manager rejects the schedule, with its reasons.
policy remove
Removes a machine's schedule entirely. This is not the same as disabling it: a disabled schedule keeps its interval and type, and a removed one does not. Removing a schedule deletes no backups. Afterward, the domain controller counts as unscheduled.
The command asks for confirmation. In a script, pass --yes; without it, the command is refused when there is no terminal.
Requirements: The backup.manage capability (Backup Operator role).
Syntax
cdr policy remove <FQDN> [--yes]
Arguments and options
| Argument or option | Description |
|---|---|
<FQDN>
|
Required. The machine whose schedule is removed. |
--yes
|
Skip the confirmation. Required when standard input is not a terminal. |
Example
cdr policy remove dc09.corp.example.com --yes
backup list
Lists the restore points this installation holds, with each one's build gate: whether the operating system build recorded in the backup still matches the machine running under that name. The ID column is the manifest ID that cdr backup show and cdr dc rebuild --manifest take. The list does not show the backup's version identifier; cdr backup show does.
Backups that retention has pruned are not restore points, because their content is gone. The list leaves them out and says how many it left out; --include-pruned lists them, marked pruned, as history. A restore point taken while a recovery of its forest was under way is marked during recovery, because it holds the directory part-way through that recovery. A line under the table names the recovery plan and the last step it had completed.
The TAKEN column also shows the result of each version's latest test restore: verified when it passed, restore failed when it did not, and verifying while one is running. A version never tested, or whose latest test restore ended without a verdict, has no tag. See Test Restores.
Requirements: The backup.view capability (every role).
Syntax
cdr backup list [options]
Options
| Option | Description |
|---|---|
-M, --machine <FQDN>
|
Only restore points for this machine. |
--newest
|
Only each machine's newest restore point, one row per domain controller. |
--rebuildable
|
Only restore points whose manifest records the hardware details that cdr dc rebuild needs. |
--gate-failing
|
Only newest restore points whose build no longer matches the machine running under that name. |
--roles
|
Show which domain controller has held each operations master role, as the backups record it, instead of the list. Cannot be combined with --newest, --rebuildable, or --gate-failing. |
--include-pruned
|
Also list backups that retention has pruned, marked as such. Their content is gone, so they are history, not restore points; without this option they are counted and left out. |
--wide
|
Add the domain, hardware shape, agent build, and content hash. |
Examples
cdr backup list --newest cdr backup list --gate-failing cdr backup list --machine dc01.corp.example.com --wide
backup show
Shows one restore point's manifest in full: the machine's identity, operating system, hardware, directory roles, and backup details. This is the record a full system recovery is planned from. The version id row is the backup's version identifier, which cdr restore plan --version and cdr recovery plan --restore take.
Requirements: The backup.view capability (every role).
Syntax
cdr backup show <ID> [options]
Arguments and options
| Argument or option | Description |
|---|---|
<ID>
|
Required. The manifest ID, as cdr backup list prints it. |
--disks
|
Add the disk and volume tables. |
--network
|
Add the adapter and persistent route tables. |
--raw
|
Write the stored manifest to standard output byte for byte. This is the document the content hash covers. Cannot be combined with --disks, --network, or --json. |
Examples
cdr backup show 412 --disks --network cdr backup show 412 --raw > dc01-manifest-412.json
backup start
Starts a backup of one domain controller now, outside its schedule. Without --wait, the command returns as soon as the Manager has queued the backup. With --wait, it follows the job until it finishes and exits on the outcome.
The Manager refuses the backup when the domain controller's agent or the storage agent is not connected (exit code 4), or when a backup of that machine is already queued or running, a recovery is working on the machine, or the Manager has no active license (exit code 3). A backup refused because a recovery is working on the machine starts by itself when the recovery is done; the Recovery Plans screen shows the plans, and cdr restore list the restore runs. With --wait, a backup that fails exits with code 4, and a job whose outcome cannot be followed exits with code 8.
Requirements: The backup.run capability (Backup Operator role).
Syntax
cdr backup start <FQDN> [options]
Arguments and options
| Argument or option | Description |
|---|---|
<FQDN>
|
Required. The domain controller to back up. |
-t, --type <CODE>
|
bmr (Full system) or systemstate (DC state). A DC state backup cannot do a full system recovery. Default: bmr. |
--wait
|
Follow the job until it finishes, and exit on its outcome. |
--poll <SECONDS>
|
How often to check the job while --wait follows it. Default: 15. |
Examples
cdr backup start dc01.corp.example.com cdr backup start dc01.corp.example.com --type systemstate --wait
jobs list
Lists recent backup jobs and their outcomes, newest first. The JOB column shows a short form of each job ID, which cdr jobs cancel accepts. A backup still waiting for a backup slot has the status queued, no start time, and waiting for a slot with how long it has waited in place of a duration.
Requirements: The backup.view capability (every role).
Syntax
cdr jobs list [options]
Options
| Option | Description |
|---|---|
-M, --machine <FQDN>
|
Only jobs for this machine. |
-s, --status <STATUS>
|
Only jobs with this exact status, for example running, completed, or failed. |
--running
|
Only jobs still in progress: queued, created, staging, running, or committing. |
--failed
|
Only jobs that finished as anything other than completed or cancelled. Cannot be combined with --running. |
--detail
|
Add the staging path, the agent's log path, and the full error message. For a backup that was not committed and whose content the storage agent has since reported in neither staging nor the vault, a content gone line says so. |
-n, --limit <N>
|
How many matching jobs to show, newest first, from 1 to 200. Default: 50. |
Examples
cdr jobs list --running cdr jobs list --failed --detail cdr jobs list --machine dc01.corp.example.com --json
jobs cancel
Asks the domain controller's agent to stop a running backup, or cancels a queued one at once. A queued backup is reported as cancelled before it started, because it was still waiting for a backup slot. Give the full job ID or the short form cdr jobs list prints; a short form must match exactly one job. A job that has already finished cannot be cancelled. If the agent is not connected, the Manager cannot ask it to stop: the backup keeps running, and the command exits with code 4.
The command asks for confirmation. In a script, pass --yes; without it, the command is refused when there is no terminal.
Requirements: The backup.run capability (Backup Operator role).
Syntax
cdr jobs cancel <JOB> [--yes]
Arguments and options
| Argument or option | Description |
|---|---|
<JOB>
|
Required. The job ID, or the short form cdr jobs list prints. |
--yes
|
Skip the confirmation. Required when standard input is not a terminal. |
Examples
cdr jobs cancel 4f3a1c9e cdr jobs cancel 4f3a1c9e-2b70-4d51-9a3e-6c8b1f0d2e44 --yes
For the console equivalent, see Monitoring and Cancelling Backup Jobs.
