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:
- Your configuration file is left exactly as it is.
- The licence stays applied.
- Secrets stay sealed in the secret store.
- Collection positions are kept, so DPLens resumes from where it stopped rather than re-reading or skipping events.
- Anything queued in a destination's disk cache is still there and is delivered once the service restarts.
- The console account and the audit log are untouched.
- The service keeps running as the same account. An upgrade that does not pass
SERVICE_ACCOUNTkeeps the account you chose when you installed. - An agent enrolled with DPLens Manager stays enrolled, with the same identity.
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:
- your configuration and licence,
- every sealed secret,
- the audit log,
- collection positions,
- anything still in a destination's disk cache, which is not delivered.
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.