Operations

Backup and recovery

What to back up, what cannot be backed up, and how to rebuild a machine.

What to back up

C:\ProgramData\DPLens\config\agent.yaml
C:\ProgramData\DPLens\config\licence.key

Two files. That is the whole of your configuration.

Everything else under C:\ProgramData\DPLens is working state that rebuilds itself: collection positions, caches, baselines, metrics.

If you want the change history too, add:

C:\ProgramData\DPLens\state\audit\audit.jsonl

Better still, deliver the audit log to your SIEM as it is written — see Logs and health — so the record survives the machine.

What cannot be backed up

Sealed secrets. Values in the secret store are sealed to the machine they were set on, so restoring the folder onto a different, separately-installed machine does not bring the values with it. A restore therefore needs its secrets seeding again.

Keep the source of every secret somewhere you control — your password manager or vault — so you can seed it into a rebuilt machine. DPLens deliberately cannot give it back to you.

The console password. Stored as a hash. Set a new one after a rebuild:

"C:\Program Files\DPLens\dplens.exe" --set-admin-password

Rebuilding a machine

  1. Install DPLens.
  2. Restore agent.yaml and licence.key into C:\ProgramData\DPLens\config\.
  3. Seed every secret the configuration refers to:
   "C:\Program Files\DPLens\dplens.exe" --set-secret secret://splunk/hec-token

Every handle in the file needs one. Validating the file lists them:

   "C:\Program Files\DPLens\dplens.exe" --validate-only --config "C:\ProgramData\DPLens\config\agent.yaml"
  1. Set the console password.
  2. Start the service.

Or do all of it in one step at install time — see Installing from the MSI.

If the machine name or domain changed

A licence is bound to a machine or a domain. If the rebuilt machine is not the one the key was issued for, it will not verify and the data plane stays held. You need a key for the new machine. See Licensing.

Recovering events, not configuration

Two things hold data rather than settings.

Collection positions, in state\checkpoints\. They record how far through each channel and file DPLens has read. Losing them is not a disaster: the agent resumes from the current end rather than re-reading everything, so you lose the gap, not the history — the events are still in Windows.

To deliberately re-read a channel from the beginning, turn on Read events already in the log on the source.

Undelivered events, in state\cache\<destination>\. These are events that have been collected and processed but not yet accepted by the destination.

Before decommissioning a machine, drain its caches. Check the

Destinations page: each card shows its cache

depth, and you want that at zero. Uninstalling with REMOVE_STATE=1, or

deleting the folder, discards whatever is still queued.

If a destination is permanently gone and its cache cannot drain, you have a choice: point the destination at somewhere that can receive, or accept the loss and remove it. There is no third option — the events are in a format for that destination and nothing else will read the queue.

Moving a configuration to another machine

agent.yaml is portable by design: it holds no secret values and no machine-specific identity, only handles and settings.

  1. Copy the file.
  2. Seed the secrets on the new machine.
  3. Apply a licence valid for the new machine.

For more than a handful of machines, build a deployment bundle instead — see Deployment options.

Verifying a backup

Test a restore on a spare machine:

"C:\Program Files\DPLens\dplens.exe" --validate-only --config C:\restore\agent.yaml
"C:\Program Files\DPLens\dplens.exe" --verify-licence C:\restore\licence.key

The first checks the configuration is intact and tells you which secret handles it needs. The second checks the licence verifies against that machine — which, for a machine-bound key, it will not unless it is the same machine.