Getting started

Upgrading and uninstalling

Upgrade in place, repair a damaged installation, or remove DPLens cleanly.

Upgrading

Install the newer package over the older one. There is no need to uninstall first.

msiexec /i dplens.msi /qn /l*v C:\deploy\upgrade.log

An upgrade keeps everything you have configured:

The service stops, the files are replaced, and the service starts again. On a busy machine expect a short gap in collection while that happens. Because positions are checkpointed, DPLens resumes from where it stopped rather than skipping the gap — the events wait in the Windows log or the file meanwhile.

Upgrades driven by DPLens Manager

An agent enrolled with your own DPLens Manager can also be upgraded from the Manager, and rolls itself back if the new version fails its health check. See Automatic upgrades from the Manager.

Every installation — enrolled or not — places a copy of the program in C:\Program Files\DPLens\update\runner\ and registers the idle scheduled task \DPLens\UpdateRunner that performs those upgrades. Each upgrade refreshes both. On an agent that is not enrolled nothing ever starts them.

Supplying a new configuration during an upgrade

Pass CONFIG_FILE or CONFIG_YAML to replace the configuration as part of the upgrade. Without them, your existing file is kept.

Downgrades are refused

Installing an older package over a newer one fails. This is deliberate: a newer version may have written state an older one cannot read, and silently proceeding would risk your collection positions.

The one exception is the automatic rollback an enrolled agent performs after a failed Manager-driven upgrade. It removes the new version and reinstalls the previous one, and only when the new version has not changed the format of the agent's state. The installer property DPLENS_ROLLBACK that makes this possible is reserved for that rollback; see Automatic upgrades from the Manager.

To go back to an earlier version, uninstall the current one first. If you need to keep your configuration, copy C:\ProgramData\DPLens\config\agent.yaml somewhere safe, uninstall without REMOVE_STATE, and install the older package.

Repairing

If the executable has been damaged or removed but your configuration is intact:

msiexec /f dplens.msi /qn /l*v C:\deploy\repair.log

This restores the program files, the service registration and the folder permissions. It does not touch your configuration, licence or state.

If the permissions on the data folders are what is wrong, you do not need a repair — the agent checks and re-applies them every time the service starts. Restarting the service is enough:

sc.exe stop dplens
sc.exe start dplens

Uninstalling

From Apps & features, or:

msiexec /x dplens.msi /qn /l*v C:\deploy\uninstall.log

This stops and removes the service, removes its account, removes the update runner and its scheduled task, and deletes the program folder. It keeps C:\ProgramData\DPLens: your configuration, licence, secrets, audit log, collection positions and anything still queued in a disk cache.

Keeping that folder means a later reinstall picks up exactly where you left off.

Uninstalling an enrolled agent

If the agent was enrolled with DPLens Manager, every uninstall — with or without REMOVE_STATE — also removes everything it held for the Manager: its identity keys, its enrolment, the Manager's trust material, any secrets the Manager delivered, and the local account its Manager connection ran under. A later reinstall is a standalone agent; enrol it again with a new token and the Manager sees a new agent. Detach the agent first if you want the Manager to release its licence seat cleanly — see Detaching an agent.

Removing everything

msiexec /x dplens.msi /qn REMOVE_STATE=1 /l*v C:\deploy\uninstall.log

This deletes C:\ProgramData\DPLens as well. That includes:

If a destination has been unreachable, drain the cache before uninstalling this way — or copy the folder aside first. Check the Destinations page: each card shows its cache depth, and you want that at zero.

Checking what is installed

Get-CimInstance Win32_Product -Filter "Name='DPLens'" | Select-Object Name, Version

Or read the version from the console — it is shown at the bottom of the navigation panel — or from the executable's file properties.