Restore Commands

The restore commands restore one domain controller, by DC state recovery or by full system recovery, or test-restore one of its backups on an Isolated Recovery Host. They follow the same steps as the console: plan the restore and read its preflight checks, approve it, run it, and follow it to the end. Planning, approving, and running are separate commands because approving and executing are separate capabilities: the person who approves a restore need not be the one who runs it.

A typical sequence:

cdr backup list --machine dc01.corp.example.com
cdr backup show 412
cdr restore plan dc01.corp.example.com --version 10/05/2026-02:30 --authoritative-subtree "OU=Sales,DC=corp,DC=example,DC=com"
cdr restore approve a1b2c3d4e5f6 --accept authoritative.overwrites
cdr restore run a1b2c3d4e5f6 --wait

Each run has an ID, which cdr restore plan prints and cdr restore list shows. For the lifecycle of a run, see Recovery Lifecycle; for the procedures, see Restoring a DC with DC State Recovery, Full System Recovery in Place, Full System Recovery onto a Candidate, Full System Recovery onto a New VM, and Running a Test Restore. To recover a whole domain or forest, use the recovery commands in Recovery Plan Commands.

For how to run cdr and the global options, see Command-Line Reference.

restore list

Lists the restores this installation has planned, test restores included, a page at a time: runs in progress first, then newest first. WHEN is when the run started, or when it was planned if it has not started, and DURATION is how long it took, with + after a figure that is still growing. When there are more runs than the page shows, the command says how many and how to page. If any run is waiting on an operator, the command warns you and exits with code 4, so a scripted check cannot pass over a domain controller waiting on a person.

A test restore is marked after the domain controller's name: (test, scheduled) for one the schedule started, (test, approved by operator), or (test, manual) when no approver is recorded.

Requirements: The plan.view capability (every role).

Syntax

cdr restore list [--machine <FQDN>] [--no-tests] [--limit <N>] [--skip <N>]

Options

Option	Description
--machine <FQDN>	Only runs for this domain controller. This option has no short form.
--no-tests	Leave test restores out. The command says how many it did not list. Runs waiting on an operator are still counted, test restores included.
-n, --limit <N>	How many runs to show, from 1 to 200. Default: 50.
--skip <N>	Skip this many first. With the default limit, --skip 50 is the second page.

Example

cdr restore list --machine dc01.corp.example.com

restore show

Shows one run in full: its preflight gates, its steps, and what the machine reported, including the network adapters the machine described (which --recovery-adapter and --restored-adapter refer to). With --wait, it re-reads the run until it reaches a final state.

For a full system recovery, the onto fact says where the restore goes: in place, onto a candidate machine, or onto a new VM booted from per-run recovery media. A run onto a new VM also shows:

• recovery media—The ISO's file name, its size, and when it was built.
• media sha256—The ISO's SHA-256 hash.
• media at—Where the ISO is exposed, followed by (taken back) once the media has expired.
• vault handed over—When the vault credential was handed to the recovery environment, or not yet: no VM has enrolled.

While the run waits for a VM, a hint gives the cdr dc rebuild … --restore-run command that builds and boots it.

For a DC state recovery, an authoritative subtree or authoritative object line names each entry the run marks authoritative. A DC state recovery that a domain or forest plan started shows authoritative nothing instead: it is non-authoritative. For a DC state recovery that resets krbtgt, a krbtgt line says whether the Manager holds the credentials for the reset (held in the manager's memory or not held), and, when the reset can be started again, a hint gives the cdr restore reset-krbtgt command.

For a test restore, the output adds a verification block: a line with the host and the verdict (restore verified, restore failed at a step, or no verdict yet with the reason), a line with the VM's state and heartbeat and what the restored domain controller reports, a table of the checks with the columns CHECK, RESULT, and DETAIL, and whether the VM, its disks, the ISO copy, and its private switch have been deleted. Once the VM is deleted, its line starts VM deleted (last seen with its last state, heartbeat, and time. While the run is still open and the host cannot read the VM or has stopped reporting on it, a line starting as of gives the time of the last read and the Manager's account of why, followed by the restored DC may be further along than this. If the restored copy did not apply every post-recovery directive, a warning points you to the verification verdict and checks above it, which say what failed. Unlike a real restore, there is nothing to set by hand afterward, because the copy is deleted with the run. See Test Restores.

Exit codes: 0 when the run is in progress, completed, or cancelled; 4 when it needs an operator; 7 when it failed; 8 when --wait loses track of the run.

Requirements: The plan.view capability (every role).

Syntax

cdr restore show <RUN> [options]

Arguments and options

Argument or option	Description
<RUN>	Required. The run ID.
--wait	Follow the run until it reaches a final state.
--poll <SECONDS>	How often to re-read while waiting, from 5 to 600 seconds. Default: 15.

Example

cdr restore show a1b2c3d4e5f6 --wait --poll 30

restore plan

Plans a restore of one domain controller from a chosen backup, and runs its preflight checks. It records the run and writes nothing to any machine. The output lists the gates: hard gates block approval, confirm gates block it until you accept each one by its code with cdr restore approve --accept, and advisory gates are for you to read. A plan with hard or confirm gates is still created, so that you can read what is in the way. The command then exits with code 4 and, for confirm gates, prints the approve command that accepts them. Some checks can only run against the live environment and are made when the restore executes.

You must name the backup with --version. cdr never picks one for you, because choosing the backup is choosing how far back to roll the directory. cdr backup show prints a backup's version identifier.

• DC state recovery (--mode rollback, the default)—Windows still starts on the domain controller. Its agent restores DC state from Directory Services Restore Mode, and marks the subtrees and objects you name with --authoritative-subtree and --authoritative-object authoritative, so that they go back to the backup on every domain controller of the domain. Name at least one. Works from either backup type. See Restoring a DC with DC State Recovery for what is accepted.
• Full system recovery (--mode server)—Restores the whole server from a full system backup through the recovery image. In place, the domain controller's agent stages the recovery image and restarts into it. With --onto, the restore goes onto a candidate machine instead. With --onto-new-vm, it goes onto an empty VM booted from a recovery ISO that the storage agent builds for the run when you execute it; cdr dc rebuild --restore-run then builds the VM and boots it. In both cases, the original domain controller must be powered off before you run it.
• Test restore (--verify, or cdr restore verify)—Restores the backup onto a new VM on an Isolated Recovery Host, moves it to a private switch before it starts, checks it as the first domain controller of a recovered domain, and deletes it. Nothing in production changes, so the original keeps running. Implies --mode server.

For a full system recovery you can also choose the network settings of the recovery environment and of the restored system at its first start. Each takes unchanged, original, or override; giving an address alone implies override. The recovery environment defaults to unchanged; for the restored system, leaving the option out lets the Manager choose. The Manager checks the settings—for example, that the gateway is on the address's subnet—when you plan.

Requirements: The plan.approve capability (Restore Operator role). For what a restore needs, see Recovery Requirements; for each gate, see Preflight Check Reference.

Syntax

cdr restore plan <FQDN> --version <ID> [options]

Arguments

Argument	Description
<FQDN>	Required. The domain controller to restore.

Options

Option	Description
--version <ID>	Required. The version identifier of the backup to restore, as cdr backup show prints it.
--mode <MODE>	rollback (or A) for a DC state recovery, or server (or B) for a full system recovery. Default: rollback.
--authoritative-subtree <DN>, --authoritative-object <DN>	DC state recovery only. A subtree to roll back—the object and everything beneath it—or one object, marked authoritative after the restore so that it replicates out instead of being overwritten from the other domain controllers. Repeat either option for each. A DC state recovery needs at least one; a full system recovery refuses both.
--reset-krbtgt	DC state recovery only, with a subtree that holds krbtgt, such as CN=Users,DC=…. Reset krbtgt twice once the rollback validates, the second time after the first has reached every writable domain controller. Approving then needs --admin. The Manager refuses it for a DC state recovery whose subtrees do not hold krbtgt.
--onto <AGENT_ID>	Full system recovery only. Recover onto a candidate machine, by its agent ID, instead of in place. cdr recovery candidates lists them. Requires --mode server.
--onto-new-vm	Full system recovery only. Recover onto an empty VM booted from a recovery ISO built for this run, instead of in place or onto a candidate. Nothing is installed on the VM first: when you execute the run, the storage agent builds the ISO, and cdr dc rebuild --restore-run builds the VM and attaches it. The original domain controller must be powered off before you execute. Requires --mode server, and cannot be combined with --onto.
--verify	Plan a test restore instead of a recovery: restore this version onto a new VM on an Isolated Recovery Host, isolate it, check it, and delete it. Nothing in production changes. Implies --mode server, and cannot be combined with --onto or --onto-new-vm.
--host <AGENT_ID>	With --verify: the Isolated Recovery Host to use, by its agent ID, as cdr recovery-host list shows it. Default: the host that can run it now.
--image <SHA256>	With --verify: the recovery image to boot, by its SHA-256 hash (cdr os-media list --images), instead of the one the Manager would choose. Use it to prove an untested image when a proven one would otherwise be used.
--reverify	Re-hash the whole backup before restoring it, instead of trusting the storage agent's own recent verification. Adds the time a full read takes.
--recovery-network <CHOICE>	Full system recovery only. The recovery environment's address: unchanged (DHCP), original (this machine's own static address, as it last described itself), or override (the address given with --recovery-address). Default: unchanged.
--recovery-address <CIDR>	The address the recovery environment takes instead of DHCP, with its prefix length, for example 10.99.0.10/24.
--recovery-gateway <IP>	The recovery environment's gateway. Omit it on a network segment with no route out.
--recovery-dns <IPS>	The recovery environment's DNS servers, comma-separated, in order, up to four. The recovery environment reaches the vault at the storage agent's advertised address, its IP address by default; it needs a DNS server only if the storage machine is advertised by name.
--recovery-adapter <MAC>	The adapter that takes the address, by MAC address, when the machine has more than one.
--restored-network <CHOICE>	Full system recovery only. The restored system's address at its first start: unchanged (whatever the backup had), original (the backup's own static address, put on the target's adapter—what new hardware needs), or override (the address given with --restored-address, for example on a new subnet). Applied by the restored domain controller's own agent before it reconnects to the Manager. Omitted, the Manager decides: original when the backup recorded one static address, its agent can apply it, and the target's adapter is known (onto a candidate, or in place when the machine's description names the adapter); unchanged otherwise.
--restored-address <CIDR>	The address the restored system takes at its first start, with its prefix length.
--restored-gateway <IP>	The restored system's gateway. Omit it on a network segment with no route out.
--restored-dns <IPS>	The restored system's DNS servers, comma-separated, in order—usually itself, or another domain controller on the recovery network.
--restored-adapter <MAC>	The target adapter that takes the restored system's address, by MAC address, when it has more than one.

Examples

Plan a DC state recovery of one organizational unit and one user:

cdr restore plan dc01.corp.example.com --version 10/05/2026-02:30 --authoritative-subtree "OU=Sales,DC=corp,DC=example,DC=com" --authoritative-object "CN=Bob,OU=IT,DC=corp,DC=example,DC=com"

Undo a mass password reset by rolling back CN=Users, with the krbtgt reset afterwards:

cdr restore plan dc01.corp.example.com --version 10/05/2026-02:30 --authoritative-subtree "CN=Users,DC=corp,DC=example,DC=com" --reset-krbtgt

Plan a full system recovery onto a candidate machine on an isolated network, giving the restored system its original address:

cdr recovery candidates
cdr restore plan dc01.corp.example.com --version 10/05/2026-02:30 --mode server --onto 6d2f9a1c-4b8e-4f7a-9c3d-2e1b0a9f8c7d --recovery-address 10.99.0.10/24 --recovery-dns 10.99.0.5 --restored-network original

Recover onto a new VM: plan, approve, and run the restore, which builds the recovery ISO; then, on the Hyper-V host, build the VM and boot it, and follow the run:

cdr restore plan dc01.corp.example.com --version 10/05/2026-02:30 --mode server --onto-new-vm
cdr restore approve a1b2c3d4e5f6
cdr restore run a1b2c3d4e5f6
cdr dc rebuild dc01.corp.example.com --restore-run a1b2c3d4e5f6 --switch "Recovery" --start
cdr restore show a1b2c3d4e5f6 --wait

For the whole procedure, see Full System Recovery onto a New VM.

restore verify

Plans a test restore of one version on an Isolated Recovery Host: the backup is restored onto a new VM, isolated on a private switch, checked as the first domain controller of a recovered domain, and deleted. Nothing in production changes. cdr restore verify is the same as cdr restore plan --verify, and takes all of its options, including --host and --image. Approve and run the plan as any other, and follow it with cdr restore show --wait.

If no host can run it, the Manager refuses the plan and names the host and what stops it; cdr recovery-host list shows each host and its state.

Requirements: The plan.approve capability (Restore Operator role), and an Isolated Recovery Host that is ready. See Setting Up an Isolated Recovery Host.

Syntax

cdr restore verify <FQDN> --version <ID> [options]

Example

cdr restore verify dc01.corp.example.com --version 10/05/2026-02:30
cdr restore approve a1b2c3d4e5f6
cdr restore run a1b2c3d4e5f6 --wait

For the procedure and how to read the result, see Running a Test Restore.

restore survey

Asks the machine a planned restore will run on to describe itself again—its disks, firmware, adapters, and the other facts the preflight checks compare with the backup—and re-evaluates the gates. Use it after you change something on the target, such as adding a disk, so that the plan reflects the machine as it is now. The machine has up to 90 seconds to answer.

Requirements: The plan.approve capability (Restore Operator role). The target's agent must be connected.

Syntax

cdr restore survey <RUN>

Argument	Description
<RUN>	Required. The run ID cdr restore plan printed.

Example

cdr restore survey a1b2c3d4e5f6

restore approve

Approves a planned restore whose hard gates are clear. The approval is recorded under your name in the audit trail, with each confirm gate you accept. A confirm gate is something that failed from where the Manager looked but may not fail from where the recovery environment runs, such as a storage machine name the target cannot resolve now. Read its remediation in cdr restore show first, and accept it only if you know the restore will get past it safely; otherwise cancel or discard the run. There is no option to accept every gate at once. A DC state recovery raises its own confirm gates: authoritative.overwrites, which lists what is rolled back on every domain controller, and, when a subtree holds krbtgt, authoritative.krbtgt. If a forest or domain plan is waiting on this run and you also hold plan.execute, the plan carries on at once.

For a DC state recovery planned with --reset-krbtgt, pass --admin with a domain administrator. cdr prompts for its password, or reads it from the CYGNADR_RESTORE_ADMIN_PW environment variable; with no terminal to prompt on and no variable set, the command stops. The password is never an argument. The Manager holds the credentials only in memory, until the reset is done or fails, for at most 8 hours. It forgets them if it restarts. You can leave --admin out when the Manager already holds credentials for the run.

Requirements: The plan.approve capability (Restore Operator role).

Syntax

cdr restore approve <RUN> [--accept <GATE>]... [--admin <USER>]

Argument	Description
<RUN>	Required. The run ID cdr restore plan printed.
--accept <GATE>	A confirm gate to accept, by its code. Repeat for each. Only gates the preflight raised count.
--admin <USER>	For a rollback that resets krbtgt: a domain administrator, as DOMAIN\user or user@domain. Its password is prompted for, or read from CYGNADR_RESTORE_ADMIN_PW.

Examples

cdr restore approve a1b2c3d4e5f6
cdr restore approve a1b2c3d4e5f6 --accept target.vault-unresolved
cdr restore approve a1b2c3d4e5f6 --accept authoritative.overwrites --accept authoritative.krbtgt --admin CORP\admin

restore run

Executes an approved restore. This replaces the domain controller's directory with the copy from the chosen backup, and anything written to it since that backup and not replicated elsewhere is lost. For a recovery onto a new VM, running it builds the recovery ISO; nothing is restored until a VM boots it.

Before it starts, cdr describes what will happen and asks you to type the domain controller's short name—the first part of its name, for example DC01 for dc01.corp.example.com. A test restore changes nothing in production, so for one the command only asks you to confirm. In a script, pass --yes; without it, the command is refused when there is no terminal, rather than assume consent.

With --wait, the command follows the run to its end and exits as cdr restore show --wait does.

Without an active license, the Manager refuses to execute the run, and the command exits with code 3. See Licensing.

Requirements: The plan.execute capability (Restore Operator role).

Syntax

cdr restore run <RUN> [options]

Arguments and options

Argument or option	Description
<RUN>	Required. The approved run ID to execute.
--yes	Skip the confirmation. Required when standard input is not a terminal.
--wait	Follow the run until it reaches a final state.
--poll <SECONDS>	How often to re-read while waiting, from 5 to 600 seconds. Default: 15.

Examples

cdr restore run a1b2c3d4e5f6 --wait
cdr restore run a1b2c3d4e5f6 --yes --wait

restore reset-krbtgt

Starts the krbtgt reset of a completed DC state recovery again: after the reset failed, after the second reset was not made because the first had not reached every writable domain controller in time, or after the Manager forgot the credentials given at approval because 8 hours passed or it restarted. It does only what is left: if the first reset was applied, only the second is made, once the first has reached every writable domain controller. Follow it with cdr restore show, where it is step R-04.

cdr prompts for the domain administrator's password, or reads it from the CYGNADR_RESTORE_ADMIN_PW environment variable. The Manager refuses a run that was not planned to reset krbtgt, one that has not validated, one whose reset is already running, and one where krbtgt has already been reset twice.

Requirements: The plan.execute capability (Restore Operator role).

Syntax

cdr restore reset-krbtgt <RUN> --admin <USER>

Argument or option	Description
<RUN>	Required. The rollback whose krbtgt reset to start again. cdr restore list prints the IDs.
--admin <USER>	Required. A domain administrator, as DOMAIN\user or user@domain.

Example

cdr restore reset-krbtgt a1b2c3d4e5f6 --admin CORP\admin

restore cancel

Asks a running restore to stop. This is possible only until the restore starts writing to the machine, and, for a DC state recovery, while the machine's agent can still be reached: once the machine has restarted into DSRM and its agent is away, the restore may be running there. After that, the Manager refuses: the restore runs to its end, and the command warns you and exits with code 4. Follow it with cdr restore show --wait. A test restore can be cancelled at any point, even after it has started writing: it changes nothing in production, its VM is torn down, and the version stays unverified. For a recovery onto a new VM whose recovery environment is connected, the Manager refuses with cancel-refused-recovery-environment and the command exits with code 4: power the VM off from its hypervisor before wbadmin starts writing, and cancel again once the run has gone quiet.

Requirements: The plan.execute capability (Restore Operator role).

Syntax

cdr restore cancel <RUN>

Argument	Description
<RUN>	Required. The run ID to stop.

Example

cdr restore cancel a1b2c3d4e5f6

restore discard

Discards a planned or approved restore that was never executed—for example, one whose preflight failed. The Manager refuses to discard a run that has already been executed (use cdr restore cancel), or a run that a domain or forest recovery plan owns (abort the plan with cdr recovery abort).

Requirements: The plan.approve capability (Restore Operator role).

Syntax

cdr restore discard <RUN>

Argument	Description
<RUN>	Required. The run ID of the planned restore to discard.

Example

cdr restore discard a1b2c3d4e5f6

restore abandon

Closes a run that cannot be cancelled because its machine is gone or will be rebuilt—for example, a candidate virtual machine that was deleted. The reason is required and is recorded in the audit trail.

Requirements: The plan.execute capability (Restore Operator role).

Syntax

cdr restore abandon <RUN> --reason <TEXT>

Argument or option	Description
<RUN>	Required. The run ID to close.
--reason <TEXT>	Required. Why the run is being given up. Recorded in the audit trail.

Example

cdr restore abandon a1b2c3d4e5f6 --reason "Candidate VM deleted; rebuilding on new hardware"

restore validate

Asks a restored machine to check that its domain controller works—AD DS running, SYSVOL ready, replication converging, and dcdiag clean—and records the result on the run. Use it after a DC state recovery whose first check came too early for replication, or after fixing what made a check fail. For a DC state recovery, it also imports any back-link file that failed to import and reads the marks again; a DC state recovery counts as restored only once its marks are read back. Otherwise it changes nothing on the machine. The machine waits up to 15 minutes for replication to converge, then reports; cdr restore show shows the result.

The run must have finished, or failed on its checks, and the machine's agent must be connected and able to make the checks. Otherwise the command says why it cannot.

Requirements: The plan.approve capability (Restore Operator role).

Syntax

cdr restore validate <RUN>

Argument	Description
<RUN>	Required. The run whose restored domain controller to check. cdr restore list prints the IDs.

Example

cdr restore validate a1b2c3d4e5f6