Getting started

Automatic upgrades from the Manager

How a managed agent upgrades itself when your DPLens Manager asks — what it checks, how it installs, how it decides the upgrade worked, and how it rolls back.

An agent enrolled with your DPLens Manager can be upgraded from the Manager: the Manager names a release to an agent, and the agent downloads, checks and installs it itself. Agents that are not enrolled never upgrade themselves — you upgrade them by running the newer package, as described in Upgrading and uninstalling.

What the agent checks before it installs anything

The Manager only names a release. The agent decides whether to trust it, against facts built into the agent itself — the Manager cannot vouch for a package.

The agent refuses the release, and tells the Manager why, unless every one of these holds:

  1. The release is newer than the version installed.
  2. No other upgrade is in progress, and the volume has room for it.
  3. The downloaded package matches, byte for byte, the fingerprint the Manager named — checked before the package is opened at all.
  4. The package is signed by the DPLens publisher — the identity built into the agent — through a certificate chain your machine trusts, with a trusted timestamp. An unsigned package, an untimestamped signature, or a signature by anyone else is refused.
  5. It is a DPLens package, and its version is the one the Manager named.
  6. DPLens's own signed list of withdrawn releases is newer than the release, and does not name it.
  7. The machine's update runner is in place (below).

The update runner

The DPLens service runs with very few privileges, deliberately, and cannot install software. The installation is done by a separate, short-lived process running as SYSTEM:

The runner trusts nothing it is handed. It copies the package into its own folder and repeats every check above on its copy before installing.

How an upgrade runs

  1. The agent downloads the package in pieces, alongside normal work. A download interrupted by a restart or a network fault carries on from where it stopped.
  2. It checks the package (above) and hands it to the runner.
  3. The runner checks it again, saves a copy of the configuration and the agent's state, and installs the package — keeping the service account the agent already runs as.
  4. The health check. The new version must be running within a minute, then stay healthy for the period the Manager chose — between one minute and one hour: the service up, collection running (or held for a reason it reports), no component restarted. The Manager's own view is not part of the decision; the check is made on the machine.
  5. Healthy: the upgrade is done, and the Manager is told the new version.

Rolling back

If the new version fails the health check, the runner puts the previous version back:

There is one case in which it will not roll back: if the new version had already converted the agent's state to a newer format, the previous version could not read it. The runner then leaves the new version in place and reports that it rolled forward, so that you can decide.

The first release that supports automatic upgrades cannot roll back to a release from before it — the earlier release never kept a package to return to.

Machines installed from a deployment MSI

A machine installed from a deployment MSI has no package the runner can roll back to: the deployment MSI is unsigned or signed by you, not by the DPLens publisher, so the agent cannot verify it as a rollback package and does not keep it as one. Automatic upgrades are therefore unavailable on such a machine until a product MSI is installed on it. The agent refuses each upgrade before it stops or installs anything, and reports to the Manager that the update runner is unavailable; the runner's log names the reason, and the installer's log said so at install time. The Manager may still offer the upgrade, in which case the agent downloads the package before it refuses it.

On those machines, change the configuration with a push, and upgrade by running a newer deployment MSI or the product MSI yourself. Once a product MSI is installed, the runner keeps its package and automatic upgrades work again.

DPLENS_ROLLBACK

The runner passes the installer property DPLENS_ROLLBACK=1 on both halves of a rollback. It makes the removal keep the agent's identity, state and the update runner, and makes the reinstall refuse a state folder written in a newer format than it understands. It is reserved for the runner: downgrading by hand remains refused, as described in Upgrading and uninstalling.

What you see

Upgrading the runner itself

Every installation, including one the runner performed, puts the new version's copy in the runner folder and refreshes the scheduled task, so the runner is always the version that is installed.