Deploying

Enrolling an agent with DPLens Manager

Connect agents to your own DPLens Manager at install time or afterwards, and what happens once they enrol.

DPLens Manager is the optional central console you run yourself to monitor, configure, license and upgrade many agents. Enrolment is how an agent joins it.

Enrolment is always your decision, made on each machine. An agent that has never been enrolled behaves exactly as a standalone agent does: it opens no connection to any Manager and sends nothing anywhere except to the destinations you configure.

What you need from your Manager

Your Manager provides four values for each rollout; how you obtain them is described in the DPLens Manager documentation.

ValueWhat it isExample shape
Manager addressWhere the agent connects. HTTPS only.https://manager.example.com/
CA pinThe fingerprint of the certificate authority your Manager's certificate is issued from. The agent refuses any server that cannot prove it.sha256: followed by 64 lowercase hexadecimal characters
Pool idThe licence pool your Manager serves. The agent refuses a Manager serving a different pool.32 lowercase hexadecimal characters
Enrolment tokenA one-line credential that lets agents enrol.begins DPET1.

The address, pin and pool id are not secrets. The token is: treat it like a password until it expires.

One token enrols many agents. A token is not tied to one machine — you can put the same token on every install line in a rollout. Every token has an expiry, set when it is created in the Manager, and your Manager may also limit how many agents one token can enrol and from which networks. Keep the expiry short: a token is only needed until the rollout is done. Once an agent has enrolled it never needs a token again.

If your estate records process command lines — command-line process auditing, or a tool such as Sysmon — a token passed on an msiexec line is recorded there. That is one more reason to keep tokens short-lived.

Enrolling at install

Add the four values to the installer command line:

msiexec /i dplens.msi /qn ^
  MANAGER_URL=https://manager.example.com/ ^
  MANAGER_CA_PIN=sha256:<64 hexadecimal characters> ^
  MANAGER_POOL_ID=<32 hexadecimal characters> ^
  ENROL_TOKEN=<the token> ^
  /l*v C:\deploy\install.log

MANAGER_URL, MANAGER_CA_PIN and MANAGER_POOL_ID go together: supply all three or none. ENROL_TOKEN is a hidden property — it appears in the installer log as **********, and the installer passes it to the agent over its standard input, never on a command line a process listing could show.

You can combine these with any other installer option, including a licence key and a configuration file, and you can add them to the command line of a deployment MSI. If the agent reaches the Internet through a proxy, add MANAGER_PROXY. To let your Manager configure syslog and NetFlow receivers, or to set the disk reserve it may not go below, add the managed receiver and disk options. Every option is listed in Installing from the MSI.

The Manager options are accepted on a fresh installation only. On a machine where DPLens is already installed, an upgrade that carries them is refused by name; use the command below instead.

Enrolling an installed agent

From an elevated PowerShell prompt, stop the service, hand the agent the four values on its standard input, and start it again:

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

where enrol.json holds one line:

{"manager_url":"https://manager.example.com/","ca_pin":"sha256:<64 hex>","pool_id":"<32 hex>","enrol_token":"DPET1.<…>"}

Delete the file afterwards. The agent never prints, logs or records the token. You can add "proxy":"proxy.example.com:3128", and a "policy" object with allow_managed_receivers (true or false), receiver_bind and receiver_allow (lists of addresses or CIDR ranges) and disk_reserve_floor_bytes — the same choices as the installer options.

On a machine that was enrolled before and then detached, the Manager address, pin and pool id are kept, so {"enrol_token":"DPET1.<…>"} on its own is enough.

--enrol prints one line saying what it did, and exits:

Exit codeMeaning
0Written. Start the service.
1A step failed — the line names it — or the prompt is not elevated.
2The request was refused by name — a value is malformed or missing. Nothing was written.
4The service control manager could not be asked whether the service runs.
5The service is running. Stop it first.
6This agent is already enrolled. Detach it first.
8A detach of this agent has not finished (detach_in_progress). Start the service once so it completes, then run --enrol again. Nothing was written.

What the agent does next

  1. The installer creates the agent's identity: two keys held by Windows that cannot be copied off the machine — in its security hardware where it has it, otherwise in Windows' software key storage. Agents that are never enrolled never have these keys.
  2. Within about a minute of the service starting — a random delay of up to a minute, so a whole rollout does not arrive at once — the agent connects to the Manager. The connection is outbound only, TLS 1.3, and the agent checks the Manager's certificate against the CA pin before it sends anything.
  3. It presents the token and its public keys. Depending on how your Manager is set up, the answer is accepted, awaiting a licence seat, or pending approval.
  4. Once the enrolment is accepted, the agent deletes the token. It keeps it only while an answer is outstanding, so a lost reply is retried with the same token.
  5. It checks in on a fixed schedule — every five minutes by default; your Manager can set anything from one to five minutes. A check-in is never brought forward by anything happening on the machine.
  6. When the Manager grants it a licence lease, the agent becomes managed. From then on its configuration comes from the Manager — see What changes when an agent is managed.

While an agent is pending approval or waiting for a seat, it receives no configuration, no licence and no secrets, and it keeps running exactly as before under its local configuration and licence.

What the Remote tab shows

Settings and audit → Remote shows what the agent holds, read-only:

FieldWhat it tells you
Stateunmanaged, enrolling, pending, awaiting_seat, active, detaching or refused
ManagerThe Manager host this agent was set up with
Agent IDA short digest of the identifier the Manager assigned
Identity key, Encryption keyWhere each key is held: in the machine's security hardware, or software_nonexportable for Windows' software key storage
Last check-in, Next check-inWhen the agent last reached the Manager, and when it will next try
Last codeThe most recent outcome, by name
AlertA condition that stops enrolment or check-in until you resolve it
Pin stateWhich Manager certificate pin the last connection proved
RefusalsSetup refusals, token refusals and missing-token waits since the service started

The sidebar reads Managed by your Manager once the agent is managed.

When enrolment is refused

At install

The installer refuses before it changes anything, and names the reason in the log and the error dialog:

RefusalWhat to do
FleetPartialSupply MANAGER_URL, MANAGER_CA_PIN and MANAGER_POOL_ID together.
TokenWithoutManager, PolicyWithoutManagerA token, proxy or receiver option was given without the Manager values. Add them, or drop the option.
BadUrlMANAGER_URL must be https:// + host, with an optional port and trailing /.
PinMissingMANAGER_CA_PIN must be sha256: and 64 lowercase hexadecimal characters. There is no trust on first use.
PoolMissingMANAGER_POOL_ID must be 32 lowercase hexadecimal characters.
BadProxyMANAGER_PROXY must be host:port, optionally with http://.
TokenMalformedThe token is not a DPLens enrolment token. Its value is never shown.
BadPolicyA receiver or disk option is malformed; the message names it.
FleetOnUpgradeDPLens is already installed. Use dplens.exe --enrol.

Afterwards

The Remote tab's Last code and Alert name what happened:

CodeMeaningWhat to do
pin_missing, pool_missing, bootstrap_invalid, token_malformedThe Manager values on this machine are unusable. No connection is made.Re-run --enrol with correct values.
pin_mismatchThe server did not present the certificate authority you pinned. The connection was closed before anything was sent.Check the pin. A proxy that inspects TLS cannot work with DPLens Manager — exempt the Manager's address from inspection.
pool_id_mismatchThe Manager serves a different licence pool. Nothing was saved.Check the pool id, or that you are pointing at the right Manager.
token_expired, token_revoked, token_exhausted, token_cidrThe Manager refused the token. The agent has deleted it.Create a new token in the Manager and run --enrol with it.
token_missingThe agent is waiting to enrol but has no token.Run --enrol with a token.
enrol_rejected, enrol_expiredAn administrator rejected the request, or it stayed pending longer than the Manager allows. The agent keeps running under its local configuration and asks again only once an hour.To enrol it again, uninstall DPLens (this removes its Manager identity; your configuration and state stay unless you remove them) and reinstall it with a new token.
rate_limited, shedThe Manager is busy.Nothing: the agent waits as long as the Manager asks, then tries again.
capacity, pending_queue_full, tenant_suspendedThe Manager cannot take the agent now.Nothing on the agent: it keeps the token and tries again after an hour. Resolve the condition in the Manager.

Every refusal is counted and recorded in the audit log. A refusal never changes how the agent collects and delivers events.

Removing an agent from the Manager

Detach it — see Detaching an agent. Uninstalling DPLens also removes everything the agent held for the Manager, including its identity; a later reinstall enrols as a new agent.