Agent Enrollment and Connectivity

An agent that does not appear on the Agents screen, or shows as not connected, has almost always said why in its own service log. Agents dial out to the Manager; nothing connects to them. So start on the agent's machine, with the log in %ProgramData%\Cygna Labs\Disaster Recovery Suite DC Agent\logs or %ProgramData%\Cygna Labs\Disaster Recovery Suite Storage Agent\logs. At startup the agent logs the address it dials and the CA fingerprint it trusts. See Logs and Diagnostics.

How an agent connects

It fetches the Manager's CA from the address it was installed with, and keeps it only if the CA's fingerprint matches the one it was installed with.
It enrolls with the enrollment token, and receives its own certificate.
It opens a session with that certificate, and keeps it alive with heartbeats.

Each step logs what went wrong when it fails. The sections below follow the same order.

The agent cannot connect to any Manager

If the agent's settings cannot work at all, it logs one critical entry, This agent cannot connect to a manager: …, and then waits until it is stopped, rather than restarting over and over. The rest of the entry says why:

Reason in the log	Fix
The manager address is not https	The Manager serves HTTPS only. Reinstall the agent with `MANAGERADDRESS=https://<manager IP>:5211`.
No manager CA fingerprint is configured	Reinstall with `MANAGERCAFINGERPRINT` set to the fingerprint on the Agents screen, or push-install the DC agent from the console or with `cdr agent deploy`, which writes the fingerprint for you.
The configured fingerprint is not a SHA-256 fingerprint	The fingerprint is 64 hexadecimal digits, which may be grouped. Copy it from the Agents screen and reinstall.

Reinstalling with msiexec /i <package> /qn and the corrected property replaces the stored value.

The fingerprint does not match

The agent logs that the Manager at its address has one CA fingerprint while the agent is pinned to another, and that nothing was sent. Either the address points at a different Manager, or the agent was installed with the wrong fingerprint. The agent retries, so it connects once the cause is fixed.

Compare the fingerprint in the log with the one on the Agents screen or in your recovery notes.
If the agent has the wrong fingerprint, reinstall it with the right MANAGERCAFINGERPRINT.
If the Manager was re-keyed, re-point the agent. See Maintaining Agents.
If the address reaches a different machine, check the Manager's address and the agent's MANAGERADDRESS.

The enrollment token is refused

The Manager logs Enrollment rejected for <machine> from <address>: invalid token, and the agent never appears on the Agents screen. The token the agent holds does not match the one the Manager was installed with, or the agent was installed with none. Reinstall the agent with the Manager's token:

msiexec /i CygnaDR.DcAgent.msi /qn ENROLLMENTTOKEN=<token>

The token is a credential that can enroll new agents: a valid token enrolls an agent immediately, with no approval step. Windows Installer masks it in installer logs. Keep it out of scripts and command history.

The Manager counts wrong tokens by the address they come from. After 10 different wrong tokens from one address within 15 minutes, it refuses every enrollment from that address, even one with the right token, until 15 minutes after the first of them. It logs Enrollment refused for <machine> from <address>: too many wrong tokens from that address and records the refusal in the audit trail. An agent that retries the same wrong token is counted once, so a mistyped installation does not lock out its own address. Machines behind the same NAT share an address: an agent refused because another machine guessed retries on its own, and enrolls once the period has passed.

Enrollment is refused because the name is in use

The Manager keeps one agent record for each machine name and agent kind, and refuses to enroll a machine onto the record of an agent that is connected under that name at that moment. The refusal is audited. It means two machines are answering to one name, for example an original domain controller that was not switched off after a recovery rebuilt it elsewhere. Take the machine that should not be there off the network. The refused machine retries on its own once the other session has ended.

The agent cannot reach the Manager

The agent logs that it could not fetch the Manager's CA, or that its session was lost, and retries with a growing delay. Check:

The port—Agents connect to the Manager on TCP 5211, or the port given to the Manager with GRPCPORT. See Ports and Protocols.
The Manager's firewall rules—The Manager installer adds an inbound rule for the agent port on every network profile. Check that it exists and is enabled with Get-NetFirewallRule -DisplayName 'Cygna DR Manager*'. A Group Policy that does not apply local firewall rules ignores it; in that case, allow the port in the policy.
Firewalls between the machines—The heartbeat keeps the connection open. A firewall that drops idle connections faster than the Heartbeat interval breaks sessions.
The Manager service—Check that CygnaDRManager is running on the Manager.

The Manager address is a name

An agent given a host name rather than an IP address logs a warning at startup that the address is a name. The Manager is normally not domain-joined, so its name may be in no zone the agent's machine queries. When Active Directory is down, DNS usually is too. If the agent cannot enroll, reinstall it with MANAGERADDRESS set to the Manager's IP address, and give the Manager a static address or a reserved DHCP lease.

Clocks

Keep the clocks of the Manager, the storage machine, and the domain controllers correct. Certificates are only valid within their dates, so a machine whose clock is far wrong can treat a valid certificate as expired or not yet valid. Full system recovery preflight also warns when a machine's clock differs from the Manager's by more than five minutes, because Kerberos on a restored DC refuses beyond that.

Cygna Forest Recovery does not change any machine's clock. The Manager measures how far each connected agent's clock is from its own, and when the difference is more than five seconds it corrects the times that agent reports onto the Manager's clock. A recovery environment starts without the time settings of the Windows it came from, so its clock is often hours out. The restore's timeline says once that the agent's times were corrected, and by how much.

Certificate problems

Agents renew their certificates automatically. If the agent logs that its certificate can no longer be used and that it is re-enrolling, no action is needed. This happens when a certificate has expired, or when the Manager was restored from a snapshot that predates the agent or was re-keyed. The agent enrolls again with its token. A renewal that fails is logged as a warning and retried, and the current certificate stays in use. Re-enrollment needs the agent's token to match the Manager's; see The enrollment token is refused.

Storage agent problems

Symptom	Cause and fix
The storage agent service stops at startup	The storage root is unreachable, for example because its volume is not yet present. The installer does not check the path. Once the volume is present, start the service by hand.
The log says no non-administrative share publishes the staging folder	No share exposes `<storage root>\staging`, so remote domain controllers cannot reach staging and their backups fail. Create a share over the staging folder (never over the storage root, and never an administrative share like `E$`). If staging is reached some other way, set Staging share override (UNC).
The log says a share named by the staging share override does not exist	Staging share override (UNC) names a share that is not on the machine. Correct the setting, or clear it to let the agent find the share.
The log says the machine has several candidate addresses	The storage machine has more than one network address, cannot tell which one the domain controllers reach, and advertises its machine name instead, so backups depend on DNS name resolution. Set Advertised host to the address domain controllers should use, and restart the storage agent.
The share's permissions are reported at startup	The agent grants the staging writers group Change on the share when Manage the staging share's permissions is on, but never removes entries. It reports anything else that can write, and any deny entry, which it cannot repair. Review the reported entries, and remove a deny entry by hand.

Push installation failures

A push installation from the console or with cdr agent deploy reports one outcome per target, with a sentence and a transcript of each step:

Outcome	Meaning and common causes
Installed, Upgraded, Reinstalled	The agent is installed at the package's version and its service restarted.
Already current	The target already runs this build; nothing was changed. Use `--force` to reinstall anyway, as when re-pointing.
Planned only	A `--plan` run; nothing was changed.
Refused before starting	The deployment declined before it touched the target: the target has a newer agent and `--force` was not given; a fresh install has no Manager address, CA fingerprint, or enrollment token to write; the address is not https; or this machine already has a connection to the target under different credentials (Windows error 1219), which you must close first.
Unreachable	The target did not answer on a port the installation needs (TCP 445, and 5985 for WinRM or 135 for DCOM), or a service it needs, such as Remote Registry, did not answer. When WinRM is refused because the target is not in TrustedHosts, the result says so and gives the `Set-Item WSMan:\localhost\Client\TrustedHosts` command to run on the machine doing the install, which is the Manager for console installs. Or use DCOM, which needs no TrustedHosts entry but does need the Windows Management Instrumentation (WMI-In) firewall group enabled on the target.
Credential refused	The target rejected the account, or the account cannot write to the registry or `ADMIN$`. Use an account that is a local administrator on the domain controller, as `DOMAIN\user` or `user@domain`.
Install failed	The installer ran but the installation did not succeed, or it reported success but the target does not list the new version, or the agent service did not restart. The result gives the reason and the path of the installer log, which is kept in `%SystemRoot%\Temp` on the target when an installation fails.

Deployment errors that stop a whole run, such as No package folder configured, No DC agent package in the folder, or A deployment is already running there, are shown before any target is touched. A missing DC agent package stops the run only when some target needs a push. Set the Package folder on the Configuration screen, or wait for the other deployment to finish. For prerequisites, see Accounts and Permissions.

Self-update failures

When an agent updates itself, from the Agents screen or with cdr agent update, the result uses the same outcomes as a push installation, and the transcript gives the Manager's or the agent's own sentence. A refusal from the agent follows the agent refused it:. Common messages:

Message	Meaning and fix
`the agent is not connected to the manager`	Unreachable. The agent is offline. Check its service and its connection, as described earlier in this topic.
`the agent does not update itself: this machine's Policy switches it off`, or `this storage agent cannot update itself — …` (or `this Isolated Recovery Host agent …`)	Refused before starting. `AllowRemote` is `false` in its machine's policy. A DC agent can be pushed to instead. A storage agent or Isolated Recovery Host agent must be installed by hand: download its package from the Agents screen or with `cdr agent package download`, and run `msiexec /i <package> /qn` on the machine. See Maintaining Agents.
`updates from the manager are switched off on this machine (Policy)`	The agent's machine has `AllowRemote` set to `false`. Remove the policy value, or update the agent by another route.
`the package is not signed …`, `the package is not signed by Cygna Labs Corp.: …`, `the package's signature carries no timestamp …`, or `the package's signature is not valid: …`	The package in the Manager's package folder is not an original, signed release package. Replace it with the package from the Cygna Forest Recovery release.
`the package is '…', not this … agent's package`	The package folder holds the wrong product under this agent kind's file name. Put the right package back.
`the package folder holds no … package to update it with`	The package folder has no package for this agent's kind. The Manager's installer puts all three agent packages in `redist`. Restore the folder, or correct the Package folder setting.
`the agent runs …, newer than the package's …; an agent never updates itself to an older version`	The package folder holds an older build than the agent runs. Nothing is changed. A self-update never downgrades and never reinstalls the build an agent already runs.
folder `has … MB free and a … MB package needs … MB with room to install`	The drive that holds the agent's data folder needs room for the package plus 256 MB. Free some space and try again.
A message that a backup, restore, recovery plan, or test restore is in progress, ending with when to update	Refused before starting. The machine has work in flight. Update it when that work has finished.
`another update is being checked or installed`, `update … is still installing`, or `a deployment is already running on …`	An earlier update of the same agent has not finished. Wait for it.
`the agent did not answer the offer within a minute`, `the agent received the package and said nothing more within five minutes`, or `no word from the agent within 20 minutes of starting the install of …`	The agent stopped responding during the update. Check the machine: whether the agent service is running and which version it reports, and the installer log in the `update` subfolder of the agent's data folder.
`still … after installing …; the installer rolled back or did not run`, or `the installer finished and … is still running …`	Install failed. The installer failed and Windows Installer rolled it back. The old build is still running. The transcript lists the installer's status and the log lines before the failure. The full log is in the `update` subfolder of the agent's data folder. See Installer Messages.
`no agent is enrolled with id …`	The agent ID is wrong, or the agent's record was deleted. Check the ID with `cdr agent list --wide`.

Unlike a push installation, a self-update leaves no log in %SystemRoot%\Temp. Its installer log stays in the agent's data folder, under update, and a summary of it comes back in the transcript.