Command-Line Reference

The cdr command-line tool gives you the same view of your environment as the console, from a command prompt or a script. It reads the same inventory, restore points, and verdicts from the Manager, and the Manager applies the same roles and capabilities to every request, so cdr and the console never disagree about what you are allowed to do.

Use cdr when a screen is not the right tool:

  • Monitoring—cdr alert list exits with a non-zero code when any alert is raised, so a scheduled task or monitoring system can use it as a probe. cdr alert notify status exits with code 4 when alert email is on and not working.
  • Evidence and export—--json on any command, and cdr report show --json and cdr audit list --json in particular, give you machine-readable records of backup outcomes and operator activity. cdr audit export writes the whole matching audit trail to a CSV, JSON, HTML, or PDF file.
  • Scripting—Schedule, back up, plan restores, and change settings from scripts, with exit codes that say what happened.
  • Work the console does not do—Push the DC agent to many domain controllers at once, size the backup storage before you install anything, build a virtual machine shaped like a domain controller's backup, and clean up the directory metadata of domain controllers, domains, and trusts that are gone.

Where cdr is installed

cdr.exe is installed with the Manager, in the Manager's program folder. In a default installation the path is:

C:\Program Files\Cygna Labs\Disaster Recovery Suite Manager\cdr.exe

The folder is not added to the PATH environment variable. Open a command prompt in that folder, or enter the full path. The DC agent package that cdr agent deploy pushes to domain controllers is in the redist folder beside it.

cdr runs on Windows. Signing in, the session cache, cdr agent deploy, cdr cleanup, and cdr repository estimate all depend on Windows features.

Running cdr

Commands are organized into groups. Enter the group, then the command, then any arguments and options:

cdr <group> <command> [arguments] [options]

Three commands—login, logout, and whoami—have no group. For example:

cdr login --username jsmith --manager https://10.0.0.10:5210
cdr dc list --protection unprotected
cdr backup start dc01.corp.example.com --wait
cdr restore show a1b2c3d4e5f6 --wait

Help is available at every level: cdr --help lists the groups, cdr restore --help lists the commands in a group, and cdr restore plan --help lists a command's arguments and options with examples. cdr --version shows the version of the tool.

An option that a command does not recognize is an error, not something cdr ignores. A mistyped filter would otherwise return a confident answer to a different question. In the same way, options that contradict each other, or a filter value that is not in the command's list, are refused with a message that names the accepted values.

Global options

Every command accepts these options:

Option Description
-m, --manager <URL> The Manager's console address, for example https://10.0.0.10:5210. Default: the CYGNADR_MANAGER environment variable, then https://localhost:5210.
--manager-ca <FINGERPRINT> The Manager CA fingerprint to trust for this run, as shown on the console. Default: the CYGNADR_MANAGER_CA environment variable, then the fingerprint you saved for this address. Required when there is no terminal to confirm on and nothing is saved.
--json Write raw JSON to standard output instead of a table. Fields that this version of cdr does not recognize are kept.
--timeout <SECONDS> How long to wait for the Manager to answer. Default: 30.
-h, --help Show help for the group or command.

Connecting to the Manager

Each run connects to one Manager. cdr takes the address from --manager, then from the CYGNADR_MANAGER environment variable, and otherwise uses https://localhost:5210, which is correct when you run cdr on the Manager itself. To run a series of commands against the same Manager, set the environment variable once:

set CYGNADR_MANAGER=https://10.0.0.10:5210

The Manager serves HTTPS only. An http:// address is refused. If you enter a host without a scheme, cdr adds https://, and a host without a port goes to the Manager's default port, 5210. An address that starts with https:// and has no port goes to port 443, for example to a reverse proxy.

Before it sends anything, cdr checks that the address answers with the certificate authority (CA) of the Manager you trust. The first time you connect to an address, cdr shows the Manager's CA fingerprint and asks you to compare it with the fingerprint shown on the console. When you confirm, it saves the fingerprint for your Windows account and does not ask again. Scripts and scheduled tasks, which cannot answer a question, pass the fingerprint with --manager-ca or CYGNADR_MANAGER_CA.

Commands that read or change the Manager's data need an operator session. Run cdr login once; the session is saved for your Windows account until it expires or you run cdr logout. For sign-in, sessions, and trust on first use, see Connecting and Signing In.

Commands that act outside the Manager

Most commands are requests to the Manager. A few do their work directly, with your own credentials, and use the Manager only to read inventory or record a result:

  • cdr agent deploy—Connects to each domain controller with a local administrator account you supply for that run, and installs or upgrades the DC agent there. The domain controller's own security log records who installed it.
  • cdr cleanup—Removes objects from Active Directory with a Domain Admin or Enterprise Admin account. Its only change to the Manager is recording that an object is gone.
  • cdr dc rebuild—Creates a virtual machine on the Hyper-V host where you run it, or writes a script for VMware ESXi. Nothing on the Manager changes.
  • cdr repository estimate—Measures your domain controllers to size the backup storage. It needs no Manager, so you can run it before you install anything.
  • cdr trust list—Reads the fingerprints saved on this computer, without contacting any Manager.

Output

  • Standard output—Tables, or JSON with --json. When output is redirected to a file or another program, tables are laid out 200 characters wide.
  • Standard error—Errors, warnings, hints, progress, confirmation prompts, and messages such as "No restore runs." for an empty result. Standard output therefore carries only the answer, which keeps --json output clean when you redirect it.

With --json, list commands write the records the Manager returned. cdr alert list --json and cdr audit list --json write the whole response, including totals, the filter the Manager applied, and when it was evaluated. cdr backup show --raw writes a restore point's stored manifest byte for byte, which is the document its content hash covers.

Confirmations and secrets

Commands that change something you cannot easily undo ask for confirmation first. Some ask a yes-or-no question. Others ask you to type a name or code, so that you must read which object the action applies to before you approve it:

  • cdr restore run asks you to type the domain controller's short name.
  • cdr cleanup dc, domain, trust, and forget do nothing until you add --confirm with the object's own name.
  • cdr recovery ack needs --confirm with the step's code.

Commands with a yes-or-no confirmation accept --yes to skip it. When standard input is not a terminal—in a script or scheduled task—these commands refuse to run without --yes rather than assume consent, and exit with code 1.

Passwords and tokens are never command-line arguments, because arguments are kept in shell history and are visible in process listings. Each command that needs one reads it from an environment variable or prompts for it, and the prompt hides what you type. In a script with no terminal, set the variable for that run only, and clear it afterward.

Exit codes

cdr returns an exit code that a script or scheduled task can act on:

Code Meaning
0 Success.
1 Usage error: missing or contradictory arguments, or a confirmation that could not be given. Nothing was changed.
2 The Manager could not be reached at the address used.
3 The Manager refused the request, and nothing was changed. This includes a signed-in operator who lacks the capability the command needs.
4 Findings: the command ran and found something that needs attention—for example, a raised alert in cdr alert list, a failed backup with cdr backup start --wait, a plan with outstanding hard gates, or a restore that is waiting on an operator.
5 An unexpected problem in cdr itself, rather than a finding about your environment. Report it to support with the message cdr printed.
6 A local action failed—for example, creating the virtual machine in cdr dc rebuild, or writing a script file.
7 A remote action failed—for example, a cdr agent deploy target that failed, a cdr repository estimate that could not measure a domain controller, a failed restore, or a cleanup that stopped.
8 Outcome unknown: the Manager accepted a change, but its result could not be read back. Check the current state before you retry.
9 Untrusted: no Manager CA fingerprint is saved for the address, or the Manager presented a different one.
10 Not signed in, or the session has expired. Run cdr login.
130 Cancelled with Ctrl+C.

Environment variables

Variable Used for
CYGNADR_MANAGER The Manager address, when --manager is not given.
CYGNADR_MANAGER_CA The Manager CA fingerprint to trust, when --manager-ca is not given.
CYGNADR_PASSWORD Your operator password for cdr login.
CYGNADR_DEPLOY_PASSWORD The password of the --user account for cdr agent deploy.
CYGNADR_ENROLLMENT_TOKEN The enrollment token that cdr agent deploy gives new DC agents.
CYGNADR_CLEANUP_PASSWORD The password of the --user account for cdr cleanup.
CYGNADR_ESTIMATE_PASSWORD The password of the --user account for cdr repository estimate.
CYGNADR_RECOVERY_ADMIN_PW The domain administrator password for cdr recovery secrets.
CYGNADR_RECOVERY_RID500_PW Optional. The password the domain's built-in Administrator account had at the backup point, for cdr recovery secrets. Without it, --rid500 prompts for the password.
CYGNADR_RECOVERY_DSRM_PW The new DSRM administrator password for cdr recovery plan --dsrm and cdr recovery secrets --dsrm.
CYGNADR_RESTORE_ADMIN_PW The domain administrator password for cdr restore approve --admin and cdr restore reset-krbtgt --admin, for a DC state recovery that resets krbtgt.
CYGNADR_SETTING_SECRET The value of a password setting for cdr config set.
CYGNADR_TRUST_FILE A different file for saved Manager fingerprints. Default: %LOCALAPPDATA%\Cygna Labs\Disaster Recovery Suite\cdr-trusted-managers.json.
CYGNADR_SESSION_FILE A different file for cached sessions. Default: %LOCALAPPDATA%\Cygna Labs\Disaster Recovery Suite\cdr-sessions.json.

Permissions

The Manager checks every request against the capabilities of the operator who signed in. The reference for each command states the capability it needs and the role that grants it. When you lack it, the Manager refuses the request and cdr exits with code 3. When the Manager refuses for a reason of its own—for example, because you tried to remove your own account—cdr shows the Manager's message instead, and also exits with code 3. The break-glass account holds every capability. For the roles and what each grants, see Managing Operators and Roles.

Commands that act outside the Manager also need rights on the machines they reach—for example, local administrator rights on the domain controllers for cdr agent deploy. Those are listed with each command.

Manager maintenance commands

A few maintenance tasks are not part of cdr. They are commands of the Manager program itself, CygnaDR.Manager.exe. Run them locally on the Manager as an administrator; they cannot be reached over the network:

  • CygnaDR.Manager.exe ca status—Shows whether the Manager's CA key is usable on this machine and whether an escrow copy exists.
  • CygnaDR.Manager.exe ca recover—Recovers the CA key from its escrow copy with the recovery passphrase.
  • CygnaDR.Manager.exe ca rekey—Replaces the Manager's CA.
  • CygnaDR.Manager.exe db snapshot [path]—Takes an on-demand snapshot of the Manager database.
  • CygnaDR.Manager.exe support package [path] [--days N | --all-logs]—Builds the Manager's part of a support package without the service, for when the service does not start.

For when and how to use them, see Recovering the Manager, Re-Keying the Manager CA, and Logs and Diagnostics.

Command groups

Group Description
login, logout, whoami, operator Sign in as an operator, sign out, and see who you are signed in as; list operator accounts, remove someone who has left, and restore someone who returns. See Connecting and Signing In.
dc, domain, forest, site List the directory inventory with each object's protection, coverage, or readiness verdict, and build a virtual machine shaped like a domain controller's backup. See Inventory Commands.
agent, recovery-host, trust List, deploy, update, restart, and uninstall agents, follow automatic agent updates, check, approve, and drain Isolated Recovery Hosts, and manage the Manager fingerprints saved on this computer. See Agent and Trust Commands.
policy, backup, jobs Schedule backups, list and inspect restore points, start a backup now, and follow or cancel backup jobs. See Backup Commands.
repository, storage, request, os-media Check vault capacity and retention depth, follow up backups that did not reach the vault and changes to committed backups, estimate the storage you need, replace the storage machine and decide requests that wait for a second operator, and check OS media coverage. See Storage and Media Commands.
restore Plan, approve, run, and follow the restore of one domain controller, and start a DC state recovery's krbtgt reset again. See Restore Commands.
recovery Plan and drive a domain or forest recovery. See Recovery Plan Commands.
alert, audit, report List raised alerts, check alert email, read the audit trail, and report backup outcomes and coverage. See Alert, Audit, and Report Commands.
config, exclusion Read and change settings, and put objects out of scope. See Configuration and Exclusion Commands.
cleanup Remove the directory metadata of domain controllers, domains, and trusts that are gone, and record objects as removed. See Directory Cleanup Commands.
support Gather the evidence for a support case from the Manager and every agent into one file, and list the support packages the Manager holds. See Support Commands.

In this chapter