Configuration and Exclusion Commands
The config commands read and change the settings the Manager holds for itself, the storage agent, the DC agents, and the Isolated Recovery Host agents, and show which machines are running the current settings. The config backup commands show and take the Manager's configuration backups. The license commands show the installed license and apply or remove a license key. The exclusion commands put objects out of scope, so that they stop counting toward alerts, and bring them back.
For how to run cdr and the global options, see Command-Line Reference.
config show
Shows every setting with its current value, product default, where the value comes from, and what it applies to. Settings are grouped in four scopes: manager, storageAgent, dcAgent, and hostAgent. With --agents, it shows instead what each machine reports it is running: the configuration revision, any values the agent has clamped to a safer limit, and restarts pending.
A password setting, such as CygnaDR:Email:SmtpPassword, is never shown: its value reads (set) or (not set).
The keys it prints, such as CygnaDR:Vault:Retention:MaxVersionsPerDc, are what cdr config set takes. For what each setting does, see Settings Reference.
Requirements: The environment.view capability (every role).
Syntax
cdr config show [options]
Options
| Option | Description |
|---|---|
-s, --scope <CODE>
|
Only one scope: manager, storageAgent, dcAgent, or hostAgent. |
--set
|
Only settings that have been changed from the product default. Cannot be combined with --agents. |
--agents
|
List what each machine reports it is running instead: configuration revision, clamped values, and restarts pending. |
--behind
|
With --agents, only machines that are not running the current revision. |
Examples
cdr config show --set cdr config show --scope storageAgent cdr config show --agents --behind
config set
Changes one setting, for the whole fleet or, with --agent, for one agent. The Manager validates the value and saves a new configuration revision; connected agents receive it at once, and agents that are offline fetch it when they reconnect. If the value was already set, nothing changes. cdr config show --agents --behind shows which machines have not applied the change yet.
The scope is worked out from the key when only one scope has it. If more than one does, name it with --scope. If you mistype a key, cdr suggests keys with a similar name.
Some settings can delete backups. For example, shortening a retention limit deletes the versions that fall outside it, and they cannot be brought back. For these destructive settings, cdr warns you and asks for confirmation, including when you reset one to its default. In a script, pass --yes; without it, the change is refused when there is no terminal.
To set a setting to an empty string, pass "" as the value. This is how some settings are switched off, such as the OS media folder. Omitting the value is not the same; use --reset to go back to the product default.
A password setting, such as CygnaDR:Email:SmtpPassword, is never taken on the command line, where it would be kept in the shell's history and shown in process listings. cdr refuses a value given there. Omit the value: cdr reads it from the CYGNADR_SETTING_SECRET environment variable when that is set, and otherwise prompts for it without echoing it. With no terminal and no variable, the command is refused. Pressing Enter at the prompt without typing anything changes nothing; --reset clears the password. The confirmation says only whether the password was set before and whether a new value is being set, never what it is.
Requirements: The config.manage capability (System Admin role).
Syntax
cdr config set <KEY> [VALUE] [options]
Arguments
| Argument | Description |
|---|---|
<KEY>
|
Required. The setting's key, as cdr config show prints it. |
[VALUE]
|
The new value. Required unless you give --reset. For a password setting, omit it: cdr prompts for the password, or reads CYGNADR_SETTING_SECRET. |
Options
| Option | Description |
|---|---|
-s, --scope <CODE>
|
The scope the key belongs to: manager, storageAgent, dcAgent, or hostAgent. Default: worked out from the key when only one scope has it. |
--agent <ID>
|
Set the value for one agent instead of fleet-wide. Takes the agent ID from cdr agent list --wide. |
--reset
|
Go back to the product default instead of storing a value. Cannot be combined with a value. |
--yes
|
Skip the confirmation. Required for a destructive setting when standard input is not a terminal. |
Examples
cdr config set CygnaDR:MaxConcurrentBackups 4 cdr config set CygnaDR:Vault:Retention:MaxAgeDays 60 cdr config set CygnaDR:HeartbeatSeconds 30 --scope dcAgent cdr config set CygnaDR:Media:Folder --reset cdr config set CygnaDR:Email:SmtpHost smtp.corp.example.com cdr config set CygnaDR:Email:SmtpPassword
config backup
Shows whether the Manager's configuration backups are running, where the copies are, and how the recent attempts ended: the same as the Configuration backups card on the License screen. cdr config backup and cdr config backup show are the same command.
When backups are not running, the command first prints a warning with the reason. It then prints the schedule and when a backup was last stored, a warning if the storage machines hold backups written under an earlier recovery passphrase, a table of storage machines with the columns STORAGE, CONNECTED, HELD, NEWEST, and FOLDER, and the last ten attempts with the columns STARTED, OUTCOME, BY, STORAGE, SIZE, and DETAIL. The FOLDER column is where to find the backups when you rebuild the Manager.
The command exits with code 0 when configuration backups are running, and 4 when they are not, for example because the recovery passphrase is not set. With --json, it writes the Manager's whole answer. For what a configuration backup is, see Manager Configuration Backups.
Requirements: The config.manage capability (System Admin role).
Syntax
cdr config backup [show] [options]
Examples
cdr config backup cdr config backup show --json
config backup run
Takes a configuration backup now, as Back up now does on the Configuration backups card. The Manager writes the backup and sends it to the storage machine, and the command waits until it has finished and lists how each storage machine's attempt ended.
If the Manager does not start a backup because one is already running, the command says so and exits with code 3. It exits with 0 when every storage machine stored the backup, and 7 when any did not or the backup could not be taken, for example because the recovery passphrase is not set; the DETAIL column says why. If the backup is still running when the wait ends, the command says so and exits with 8; the backup carries on on the Manager, and cdr config backup shows how it ended. With --json, it writes whether the backup is still running and this run's attempts.
Requirements: The config.export capability (System Admin role).
Syntax
cdr config backup run [options]
Options
| Option | Description |
|---|---|
--wait <MINUTES>
|
How long to wait for the backup to be stored. At least 1. Default: 10. |
Examples
cdr config backup run cdr config backup run --wait 30
license show
Shows the installed license, where it stands today, and the enabled user accounts beside its licensed count. The LICENSE table lists the state (licensed, expiring, grace period, expired, does not license Cygna Forest Recovery for Active Directory, or none installed) with the license's sentence. Then come licensed to and issued for the whole key, then module with the module's name and, indented below it, its type, people, ends, operations stop, and maintenance ends, and last installed. When new backups and recovery operations are refused, the command says so.
A second table lists each forest with ENABLED USERS, DOMAINS COUNTED, and OLDEST COUNT, followed by the total against the licensed people. The total is a guide only: the license counts people, and one person often holds several accounts. Domains with no DC agent are not counted. For what the license enforces, see Licensing.
The command exits with code 0 whatever the license's standing. With --json, it writes the Manager's whole answer, including the state, whether operations are allowed, the days to the end date and to the stop, and the per-forest counts.
Requirements: A signed-in session (every role).
Syntax
cdr license show [options]
Examples
cdr license show cdr license show --json
license preview
Shows what a license key says—its standing and terms—without installing it. The command prints the same LICENSE table as cdr license show. If the Manager cannot use the key, the command prints the reason and exits with code 3.
Requirements: The config.manage capability (System Admin role).
Syntax
cdr license preview <KEY> [options]
Arguments
| Argument | Description |
|---|---|
<KEY>
|
Required. The license key, as Cygna sent it. Quote it if your shell would split it. |
license apply
Installs a license key in place of the installed one, if there is one. On success, the command prints Installed the license key. and the LICENSE table for the new key. If backups and recovery operations were stopped, they resume at once. The installation is recorded in the audit trail.
The Manager refuses a key that is not a Cygna version 2 license key, or that does not license Cygna Forest Recovery for Active Directory; the command prints the reason and nothing is installed.
Requirements: The config.manage capability (System Admin role).
Syntax
cdr license apply <KEY> [options]
Arguments
| Argument | Description |
|---|---|
<KEY>
|
Required. The license key, as Cygna sent it. Quote it if your shell would split it. |
Exit codes
| Code | Meaning |
|---|---|
0
|
The key was installed. |
3
|
The key was refused, or the Manager refused the request. Nothing was installed. |
Examples
cdr license apply "<KEY>"
license remove
Removes the installed license. New backups, restores, recovery plans, and test restores are then refused until a key is applied; work already under way finishes. The command warns you and asks for confirmation. If no license is installed, it says so and exits with code 0. The removal is recorded in the audit trail.
Requirements: The config.manage capability (System Admin role).
Syntax
cdr license remove [options]
Options
| Option | Description |
|---|---|
--yes
|
Skip the confirmation. Required when standard input is not a terminal. |
Examples
cdr license remove --yes
About exclusions
An exclusion records that you know about an object and have deliberately put it out of scope—for example, a domain controller that is being decommissioned, or an orphaned domain partition that will never have a domain controller. An excluded object stops counting toward alerts. It is still discovered and still listed, and its verdict is still computed and shown: an exclusion changes what is counted, never what is shown.
- A reason is required—The reason is kept with the exclusion, so that anyone can see later why the object stopped counting.
- Review date or permanent—Give a review-by date, after which the exclusion lapses and the object raises alerts again, or record it as permanent on purpose with
--permanent. You must choose one. - Containers pass it down—Excluding a forest makes every domain, site, and domain controller in it inherit the exclusion. Excluding a domain controller does not change its domain's coverage verdict; exclude the domain itself to stop the domain raising alerts.
For when to use exclusions and retirements, see Excluding and Retiring Objects.
exclusion list
Lists every exclusion with its state, review-by date, when and by whom it was set, and the reason. Exclusions that have lapsed or been voided are listed too, because their objects raise alerts again. One on a domain controller or domain since recorded as removed is marked (retired) and counted apart, under on retired objects: nothing can alert for it and no review is due, and cdr exclusion remove clears it.
Requirements: The environment.view capability (every role).
Syntax
cdr exclusion list [options]
Options
| Option | Description |
|---|---|
-k, --kind <CODE>
|
Only exclusions on this kind of object: dc, domain, site, or forest. |
--active
|
Only exclusions still in effect. |
--spent
|
Only exclusions that have lapsed or been voided: due for review, or on an object since retired. Cannot be combined with --active, --due, or --permanent. |
--due <DAYS>
|
Only active exclusions whose review-by date falls within this many days. |
--permanent
|
Only active exclusions recorded with no review-by date. Cannot be combined with --due. |
Examples
cdr exclusion list --due 30 cdr exclusion list --permanent cdr exclusion list --spent
exclusion add
Puts an object out of scope. If the object is already excluded, the new exclusion replaces the old one; both are audited.
Requirements: The backup.manage capability (Backup Operator role).
Syntax
cdr exclusion add <KIND> <KEY> --reason <TEXT> (--review-by <DATE> | --permanent)
Arguments
| Argument | Description |
|---|---|
<KIND>
|
Required. What is being excluded: dc, domain, site, or forest. |
<KEY>
|
Required. The object: a domain controller's FQDN, a domain's FQDN, a site's distinguished name, or a forest's FQDN. |
Options
| Option | Description |
|---|---|
-r, --reason <TEXT>
|
Required. Why the object is out of scope. |
--review-by <DATE>
|
When to reconsider, as yyyy-MM-dd or a full timestamp such as 2027-03-01T09:00:00Z. Give this or --permanent. |
--permanent
|
Record the exclusion with no review date, on purpose. Give this or --review-by. |
Examples
cdr exclusion add dc dc09.corp.example.com --reason "Decommissioned; awaiting metadata cleanup" --review-by 2026-12-01 cdr exclusion add domain blue.corp.example.com --reason "Orphaned partition, no DCs and never will have" --permanent cdr exclusion add site "CN=Branch-Test,CN=Sites,CN=Configuration,DC=corp,DC=example,DC=com" --reason "Test site with no production DCs" --review-by 2027-01-15
exclusion remove
Clears an exclusion. The object counts again from the next time the Manager reads it. If the object has no exclusion of its own but inherits one from its domain or forest, clear the exclusion on the container instead; cdr exclusion list shows where each exclusion is recorded.
Requirements: The backup.manage capability (Backup Operator role).
Syntax
cdr exclusion remove <KIND> <KEY>
| Argument | Description |
|---|---|
<KIND>
|
Required. What was excluded: dc, domain, site, or forest. |
<KEY>
|
Required. The object: a domain controller's FQDN, a domain's FQDN, a site's distinguished name, or a forest's FQDN. |
Example
cdr exclusion remove dc dc09.corp.example.com
