Agent and Trust Commands

The agent commands list the agents that have enrolled with the Manager, bring agents of every kind up to the build the Manager holds, restart and uninstall agents through the Manager, install the DC agent on domain controllers, save agent packages, report what automatic updates are doing, and delete the record of an agent whose machine is gone. The recovery-host commands show whether each Isolated Recovery Host can run test restores, and approve, drain, and undrain hosts. The trust commands manage the Manager CA fingerprints that cdr has saved for your Windows account on this computer.

An agent list and a domain controller list answer different questions. cdr agent list shows what has enrolled; cdr dc list shows what the directory defines, including domain controllers with no agent. Use cdr agent deploy --without-agent to close the gap.

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

agent list

Lists the enrolled DC agents, storage agents, and Isolated Recovery Host agents: which build each runs, and whether the Manager is talking to it now. After a storage agent's kind, the list says which is the storage machine ((storage machine)) and marks any other as (candidate, no work) or (replaced). After an Isolated Recovery Host agent's kind, it marks a host (awaiting approval) or (draining); an approved host has no mark.

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

Syntax

cdr agent list [options]

Options

Option	Description
-k, --kind <CODE>	Only agents of this kind: dc, storage, or host.
-M, --domain <FQDN>	Only agents on machines in this domain. The short form is -M.
--offline	Only agents with no session open to the Manager right now.
--outdated	Only agents running a build older than the package for their kind in the Manager's package folder.
--silent-for <MINUTES>	Only agents whose last heartbeat is older than this many minutes, or that never sent one.
--wide	Add the agent ID, NetBIOS name, forest, site, enrollment date, and a CAPABILITIES column with what each connected agent's session says it can do. The column shows a dash for an agent with no session. The agent ID is what cdr config set --agent, cdr restore plan --onto, and cdr agent forget take.

Examples

cdr agent list --outdated
cdr agent list --offline --silent-for 60
cdr agent list --kind storage --wide

agent forget

Deletes an agent's record from the Manager, for a machine that is gone. It touches no machine. Without --confirm, it only says what it would delete: the agent's kind, machine, build, enrollment date, and last heartbeat, and any other record under the same name, which stays.

The Manager refuses, and the command lists why, while any of these is true:

• The agent is connected to the Manager right now.
• A restore run that has not finished names it.
• An approved, running, or halted recovery plan has bound it as a candidate machine.
• A test restore that has not finished runs on it.
• It is the storage machine. Replace it with another storage agent first, with cdr storage replace.

The record's session history and backup jobs are kept, and the audit trail keeps a copy of the record. If the machine is still running, its agent enrolls again under its own name on its next connection. On the Agents screen, Forget this agent record… in the agent's row menu does the same.

Requirements: The agents.manage capability (System Admin role).

Syntax

cdr agent forget <ID> [--confirm <ID>]

Argument or option	Description
<ID>	Required. The agent ID whose record to delete, as cdr agent list --wide shows it.
--confirm <ID>	Type the agent ID again to delete its record. Without it, cdr only says what would happen.

Examples

cdr agent forget 0847c3af-ec9c-4389-bcb1-7b706c5dc164
cdr agent forget 0847c3af-ec9c-4389-bcb1-7b706c5dc164 --confirm 0847c3af-ec9c-4389-bcb1-7b706c5dc164

agent update

Brings agents up to the build the Manager holds. The Manager chooses the route for each agent. An agent that is connected and able to update itself is sent the package over its own session and installs it after checking it (self-update). A DC agent that cannot update itself is installed remotely with an account you give (push install). A storage agent or Isolated Recovery Host agent that cannot update itself must be installed by hand (hand install). Before it starts, the command prints each agent with its current and new version and the route. It then follows the run and prints each agent's progress.

Requirements: The agents.manage capability (System Admin role).

Syntax

cdr agent update [<AGENTS>...] [options]

Arguments and options

Argument or option	Description
<AGENTS>	Agents to update, by agent ID (cdr agent list --wide shows it), or by machine name when that names only one agent. Name agents or use --outdated, not both.
--outdated	Every agent behind the package the Manager holds for its kind. Agents that must be installed by hand, and DC agents that would need a push when you give no --user, are skipped with a warning.
-k, --kind <CODE>	With --outdated, only agents of this kind: dc, storage, or host.
-u, --user <ACCOUNT>	Only for a DC agent that cannot update itself and is pushed to: a local administrator on the domain controller, as DOMAIN\user. The password is read from the CYGNADR_DEPLOY_PASSWORD environment variable, or prompted for.
--transport <NAME>	For a push install: winrm or dcom. Without it, the Manager's configured default is used.
--wait <MINUTES>	How long to follow the run before leaving it to carry on on the Manager. Default: 30.

When the run ends, the command prints a table with the columns AGENT, KIND, ROUTE, OUTCOME, BEFORE, AFTER, and MESSAGE. The Manager refuses to update an agent while it is busy, for example while its domain controller is being backed up or a test restore runs on its host; the message says so.

Exit codes: 0 when every agent was updated or was already current; 7 when any agent refused, failed, or needs a hand install; 8 when the run was still going when --wait ran out; 4 when nothing could be selected because every candidate was skipped; 3 when the Manager did not start the run; 1 for a usage error.

Examples

cdr agent update --outdated
cdr agent update --outdated --kind storage
cdr agent update storage01
cdr agent update --outdated --kind dc --user CORP\admin

agent auto-update

Says what automatic agent updates are doing: whether they are on, the interval and how many agents are updated at once, when the Manager last checked and will next, and how many outdated agents are updating, queued, and waiting. It then lists the agents that need an operator: those that cannot update themselves and those whose last automatic update failed. Turning automatic updates on and off is a setting: cdr config set CygnaDR:Deployment:AutoUpdate true. See Updating agents automatically.

Requirements: The environment.view capability (every role). --check-now needs agents.manage (System Admin role).

Syntax

cdr agent auto-update [options]

Options

Option	Description
--all	List every outdated agent and why it is waiting, not only those that need an operator.
--check-now	Check now rather than at the interval, starting updates for the agents that can take one. Starts nothing while automatic updates are off.

The table has the columns MACHINE, KIND, RUNNING, PACKAGE, STATE, and WHY. The state is started, updating, queued, busy, later, away, later, next check, needs an operator, or failed, retrying later, with when a failed update is tried again.

Exit codes: 4 when an outdated agent needs an operator, because it cannot update itself or its automatic update failed; 0 otherwise; 3 when a --check-now did not run. With --json, the counts cover every outdated agent, and the list holds those that need an operator, or every one with --all.

Examples

cdr agent auto-update
cdr agent auto-update --all
cdr agent auto-update --check-now

agent restart

Restarts agents' services through the Manager, so settings that take effect at restart come into force without signing in to each machine. The console's Agents and Configuration screens send the same request.

The Manager refuses an agent that is not connected, an agent that is not running as its service, and an agent whose work a restart would cut short. That work is, for a DC agent, a backup or restore on its domain controller, or any running recovery plan; for the storage agent, any backup or restore; for an Isolated Recovery Host agent, a test restore on its host.

Requirements: The agents.manage capability (System Admin role).

Syntax

cdr agent restart [<AGENTS>...] [options]

Arguments and options

Argument or option	Description
<AGENTS>	Agents to restart, by agent ID (cdr agent list --wide shows it), or by machine name when that names only one agent. Name agents or use --restart-pending, not both.
--restart-pending	Every connected agent holding a saved setting that takes effect at restart. An agent that is not running as its service is skipped with a warning.
-k, --kind <CODE>	With --restart-pending, only agents of this kind: dc, storage, or host.

The command prints a table with the columns AGENT, KIND, OUTCOME, and DETAIL. The outcome is restarting when the agent has scheduled its restart; it reconnects within a few seconds, and cdr agent list shows its new session. Any other outcome, such as not-connected, not-supported, busy, refused, or no-answer, comes with the reason.

Exit codes: 0 when every agent is restarting, or when --restart-pending finds no agent waiting; 7 when any agent was not restarted; 4 when every agent waiting for a restart was skipped because it is not running as its service; 3 when the Manager did not restart anything; 1 for a usage error.

Examples

cdr agent restart --restart-pending
cdr agent restart --restart-pending --kind dc
cdr agent restart dc01.corp.example.com storage01

agent uninstall

Has an agent uninstall itself from its machine, as the row menu on the console's Agents screen does. Without --confirm, the command only says what it would do; give the agent ID again with --confirm to uninstall it.

The Manager refuses a DC agent on a domain controller that is neither retired nor excluded, an agent that is not connected, any agent with work in flight, and the storage machine, which is replaced with cdr storage replace instead. Retire the domain controller with cdr cleanup retire or exclude it with cdr exclusion add first. The agent itself refuses when it was not installed by its own package or its machine's AllowRemote policy is false. The agent's record stays on the Manager; once it shows as disconnected, delete it with cdr agent forget.

Requirements: The agents.manage capability (System Admin role).

Syntax

cdr agent uninstall <AGENT> [--confirm <ID>]

Argument or option	Description
<AGENT>	Required. The agent to uninstall, by agent ID, or by machine name when that names only one agent.
--confirm <ID>	Type the agent ID to uninstall the agent. Without it, cdr only says what would happen.

When the agent accepts, the command prints what it is removing and the path of the installer log on the machine. Exit codes: 0 when the agent is uninstalling, or when nothing was confirmed; 7 when the Manager or the agent refused; 3 when the request failed; 1 for a usage error, including a --confirm value that is not the agent's ID.

Examples

cdr agent uninstall spare01.corp.example.com
cdr agent uninstall 0847c3af-ec9c-4389-bcb1-7b706c5dc164 --confirm 0847c3af-ec9c-4389-bcb1-7b706c5dc164

agent package download

Saves an agent installer that the Manager holds, and checks the saved file against the package's SHA-256 hash. If the hashes differ, the file is removed. An existing file is never overwritten.

Requirements: The agents.manage capability (System Admin role).

Syntax

cdr agent package download <KIND> [-o|--output <PATH>]

Argument or option	Description
<KIND>	Required. dc, storage, or host.
-o, --output <PATH>	A file name, or a folder to save the package in under its own name. Default: the current folder.

Examples

cdr agent package download storage
cdr agent package download host --output C:\Install

recovery-host list

Lists each Isolated Recovery Host, whether it is connected, and what stops it running test restores.

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

Syntax

cdr recovery-host list [--json]

The table has the columns HOST, USE (approved, awaiting approval, draining, or drained), STATE (ready, not ready, or unknown), CONNECTED, HYPER-V (for example running, not installed, or restart needed), SWITCHES, FREE FOR VMS, MEMORY, and REPORTED. Under each host, it shows the host's agent ID; for a host awaiting approval or draining, what to do next; the folder for test restore virtual machines and the recovery network; the test restore running now, the last one and its result, and what the schedule last decided for this host; and each problem or warning the host reported, with what to do about it.

With no host enrolled, the command says so. Test restores are optional; install the Isolated Recovery Host agent on a Hyper-V host to offer them. See Setting Up an Isolated Recovery Host.

recovery-host approve, drain, and undrain

Decide whether test restores go to a host. approve approves a host for test restores; a host is given none until it is approved. drain stops new test restores going to a host so that it can be removed; the test restore running on it finishes, and cdr recovery-host list says drained once nothing runs on it. undrain puts a draining or drained host back in use. See Moving an Isolated Recovery Host.

Requirements: The agents.manage capability (System Admin role). Each action is recorded in the audit trail.

Syntax

cdr recovery-host approve <ID>
cdr recovery-host drain <ID>
cdr recovery-host undrain <ID>

<ID> is the host agent's ID, as cdr recovery-host list shows it under each host. The command says what changed, or why the Manager refused, and exits with code 3 when nothing was changed.

Examples

cdr recovery-host approve 3f2a91c4-0d7e-4b8a-9c1f-5e6d7a8b9c0d
cdr recovery-host drain 3f2a91c4-0d7e-4b8a-9c1f-5e6d7a8b9c0d

agent deploy

Installs or upgrades the DC agent on domain controllers from the computer where you run cdr. Use it for a first install; to update agents that are already installed, cdr agent update is simpler, because agents that can update themselves need no credential. Name the domain controllers, select them from the Manager's inventory with --all, --without-agent, or --outdated, or combine both.

For each target, cdr connects with the account you give in --user, copies the package over the ADMIN$ share, reads the installed version from the registry, and runs the installer through WinRM or DCOM. It decides per target whether to install, upgrade, or leave the agent alone. A target already at the package's version is reported as current, and a downgrade is refused, unless you add --force. The password is used for this run only; it is never sent to the Manager or stored.

A new agent needs the Manager's agent address, the Manager CA fingerprint, and the enrollment token:

• Address—cdr uses --manager-address, or derives it from --manager with port 5211. It cannot derive one from localhost, so when you run cdr on the Manager, give --manager-address with the address the domain controllers will reach, for example https://10.0.0.10:5211. Use the Manager's IP address: the Manager is usually not in the domain controllers' DNS, and the agents must reach it when DNS is down.
• Fingerprint—cdr seeds each agent with the fingerprint that this run trusts: --manager-ca, the fingerprint you saved for the Manager, or a confirmation on first use. It checks the fingerprint against what the Manager's agent port presents, so the agents trust exactly the Manager you reached.
• Enrollment token—Read from the CYGNADR_ENROLLMENT_TOKEN environment variable, or prompted for. It is written only where no agent is installed yet, and, with --repoint, to every target. Treat the token as a secret: anyone who has it can enroll an agent.

Upgrades need no token. To move existing agents to a new Manager address, add --repoint with --manager-address. With --repoint, the enrollment token is optional: one you give is written to every target, which is how agents get a new token after the Manager is re-keyed; with none, each agent keeps its own. When you name the targets and use no selector, cdr does not need the Manager's inventory, so you can re-point agents at a Manager that is not answering yet.

The command prints a table of each target's action, version before and after, and result, and exits with code 7 if any target failed.

Requirements: An account that is a local administrator on each target, given as DOMAIN\user or user@domain. Each target must allow the ADMIN$ share and the Remote Registry service, and either WinRM (TCP 5985) or DCOM (TCP 135 and the dynamic RPC range, with the Windows Management Instrumentation (WMI-In) firewall rules enabled). Over WinRM from a computer outside the domain, the targets must be in that computer's TrustedHosts list; DCOM needs no TrustedHosts entry. The selectors read the inventory, which needs the environment.view capability. Runs on Windows only. For details, see Deploying DC Agents.

Syntax

cdr agent deploy [TARGET ...] --user <ACCOUNT> [options]

Arguments

Argument	Description
[TARGET ...]	Domain controllers to deploy to, by name. Combine with the selectors, or use instead of them. Either a target or a selector is required.

Options

Option	Description
-u, --user <ACCOUNT>	Required. An account that is a local administrator on the targets, as DOMAIN\user or user@domain. The password is read from CYGNADR_DEPLOY_PASSWORD, or prompted for.
--package <MSI>	The CygnaDR.DcAgent.msi to deploy. Default: the package in the redist folder beside cdr.exe, then one directly beside it.
--manager-address <URL>	The agent address a new agent connects to, for example https://10.0.0.10:5211. Default: derived from --manager; required when that is localhost.
--repoint	Also write --manager-address, the CA fingerprint, and the enrollment token to targets that already have an agent, so that they follow the Manager to a new address, or to a new CA and token after a re-key. With no token given, each agent keeps its own. Requires --manager-address.
--all	Every domain controller in the inventory.
--without-agent	Every domain controller in the inventory that has no agent.
--outdated	Every domain controller whose agent reports a version older than the package's.
-d, --domain <FQDN>	Restrict the selectors to one domain. Only with --all, --without-agent, or --outdated.
--transport <NAME>	How the installer is started on the target: winrm (TCP 5985) or dcom (TCP 135 and RPC; needs no TrustedHosts entry). Default: winrm.
--parallel <N>	How many targets to work on at the same time. Default: 4.
--install-timeout <MINUTES>	How long the installer may run on a target. Default: 10.
--force	Reinstall on a target already at this version, or attempt a downgrade.
--plan	Connect, read each target's installed version, and report what would happen. Nothing is changed, and no token or fingerprint is needed.

Examples

See what would happen across the inventory, then install on every domain controller in one domain that has no agent, from the Manager:

cdr agent deploy --all --user CORP\admin --plan
cdr agent deploy --without-agent --domain corp.example.com --user CORP\admin --manager-address https://10.0.0.10:5211

Upgrade every outdated agent, and reinstall one domain controller over DCOM:

cdr agent deploy --outdated --user CORP\admin
cdr agent deploy dc02.corp.example.com --user CORP\admin --transport dcom --force

After the Manager moves to a new address, point every agent at it:

cdr agent deploy --all --user CORP\admin --manager-address https://10.0.0.20:5211 --repoint --force

trust list

Lists the Managers whose CA fingerprint is saved for your Windows account, with the fingerprint and when it was saved. It reads only the local file and contacts no Manager, so it works when every Manager is down.

Requirements: None.

Syntax

cdr trust list [options]

Takes the global options only.

Example

cdr trust list

trust pin

Trusts the Manager at --manager and saves its fingerprint. With --manager-ca or CYGNADR_MANAGER_CA, cdr checks that the Manager presents that fingerprint and saves it without asking—the way to prepare a computer or account that will run scripts. Without one, cdr shows the fingerprint and asks you to confirm it, even if one is already saved for the address.

Requirements: None. Without a fingerprint, a terminal to confirm on.

Syntax

cdr trust pin --manager <URL> [--manager-ca <FINGERPRINT>]

Takes the global options only.

Examples

cdr trust pin --manager https://10.0.0.10:5210
cdr trust pin --manager https://10.0.0.10:5210 --manager-ca 3F2A-91C0-5B7E-04D8-C1A6-2E9F-7B30-D4C2-8E15-6A9B-F0D3-1C47-B8E2-5D90-A6F1-E7F8

trust remove

Forgets the saved fingerprint for the Manager at --manager, so that the next connection asks you to confirm the CA again. Use it when a Manager has been deliberately rebuilt or its CA re-keyed and now presents a different CA. If nothing is saved for the address, the command warns you and exits with code 1.

Note: A Manager that presents a different CA when you did not change it is a warning sign, not something to clear. Confirm what happened before you remove the saved fingerprint.

Requirements: None.

Syntax

cdr trust remove --manager <URL>

Takes the global options only.

Example

cdr trust remove --manager https://10.0.0.10:5210

For re-keying, see Re-Keying the Manager CA.