Operations

Detaching an agent

Take an agent out of DPLens Manager — from the Manager, or on the machine when the Manager is unreachable — and what is kept, what is deleted, and how to enrol it again.

Detaching ends an agent's relationship with its DPLens Manager. The agent goes back to being a standalone agent that you manage on the machine, and it keeps collecting and delivering throughout.

There are two ways to do it.

From the Manager

When the Manager detaches or retires an agent, it sends the agent a signed instruction at its next check-in; the agent acts on nothing less. This is the normal route, because the agent's last check-in tells the Manager it has left, so the Manager can release its licence seat.

On the machine

When the Manager is gone, unreachable, or you need the machine back now, an administrator can detach it locally. From an elevated prompt, with the service stopped:

sc.exe stop dplens
"C:\Program Files\DPLens\dplens.exe" --detach
sc.exe start dplens

It needs no network and no Manager, takes no other argument — there is no force option — and is recorded in the audit log under the account that ran it. It refuses while the service is running, and also while any other DPLens process is still running the agent on this machine.

Exit codeMeaning
0Detaching — or the agent was already detaching. Start the service.
1A step failed — the line names it — or the prompt is not elevated.
2Wrong usage. --detach takes no options.
4The service control manager could not be asked whether the service runs.
5The service — or another DPLens process running the agent on this machine — is running. Stop it first.
7This agent is not enrolled. Nothing was changed.

What happens

At once:

A local detach does the secret conversion, and sends the last check-in, when the service next starts.

Then: the agent makes one last check-in to tell the Manager it is leaving. It keeps trying for up to 24 hours. The detach completes when the Manager acknowledges it, when the Manager reports the agent as retired, or when the 24 hours run out — whichever comes first.

If a step of the clean-up fails — a file that cannot be deleted, say — nothing is left half-done: the agent records the failure in the audit log and finishes the clean-up at every start until it succeeds. When it completes, the agent deletes what it held for the Manager: its enrolment, the Manager's trust material, its place in the Manager's command sequence, telemetry not yet sent, and cached configuration templates. Its two identity keys are deleted too, so the machine can never again present the identity it had. It keeps the Manager's address, CA pin and pool id, and everything that was never the Manager's: your configuration, local secrets, the audit log, collection positions and destination caches.

Enrolling it again

Once the detach has completed, enrol with a new token. Until it has, --enrol refuses with detach_in_progress (exit code 8): start the service once so the detach can finish, then enrol. Because the Manager address, pin and pool id are kept, the token is all the agent needs:

sc.exe stop dplens
Get-Content C:\secure\enrol.json | & "C:\Program Files\DPLens\dplens.exe" --enrol
sc.exe start dplens

with enrol.json holding {"enrol_token":"DPET1.<…>"}. The agent creates a new identity, so the Manager sees a new agent. See Enrolling an agent with DPLens Manager.

Detaching by uninstalling

Uninstalling DPLens always removes everything the agent held for the Manager, including its identity — with or without REMOVE_STATE. It does not send the final check-in, so the Manager sees the agent go silent; retire it there. See Upgrading and uninstalling.