How DPLens is configured

DPLens is configured by one file, agent.yaml. The console reads and writes that file, so you can work in whichever way suits you: click through the console, edit the file and deploy it centrally, or do both.

Where everything lives

Everything DPLens writes is under C:\ProgramData\DPLens. The program folder holds the executable and nothing else.

These folders are protected: only administrators and the agent's own service account can read them. The agent checks those permissions every time it starts and puts them back if they have been changed.

Back up config\agent.yaml and config\licence.key. Everything else can be rebuilt. See Backup and recovery.

How a change takes effect

Nothing you change in the console takes effect when you save it. Changes are staged until you review and apply them, as one set.

1. You edit something — a source, a stage, a destination, a setting.
2. The pending changes indicator counts it.
3. You open it, read what will change, and Apply.
4. The agent validates the whole configuration. If anything is wrong, the apply is refused and the running configuration is untouched.
5. The new configuration starts. If the agent does not come back healthy, you get a countdown and a Roll back button.

Editing the file on disk instead? Restart the service to load it:

sc.exe stop dplens
sc.exe start dplens

Check it first, so a typo does not stop the service from starting:

"C:\Program Files\DPLens\dplens.exe" --validate-only --config "C:\ProgramData\DPLens\config\agent.yaml"

The shape of the file

utc_timestamps: true

settings:
  # agent-wide settings

sources:
  # where events come from

destinations:
  # where events go

pipelines:
  # which source flows through which stages to which destinations

All five sections are optional except that you need at least one pipeline for the agent to do anything.

Values are written as text

Settings inside a params block are written as strings:

params:
  batch_size: "256"
  read_existing: "true"

Quoting is not always required, but it is always safe, and it avoids YAML reading values such as on, off, no or y as true and false when you meant the words.

utc_timestamps

utc_timestamps: true

Timestamps are normalised to UTC as soon as an event is collected, and stay in UTC everywhere inside DPLens. This setting controls how they are written out. Leave it on unless you have a receiver that insists on local time.

settings

Agent-wide settings. Every one is optional.

settings:
  cost_per_gb: 2.50
  ui:
    port: 8443
    enabled: true
    remote_access: false
    allow_ips: []
    tls_cert_handle: secret://console/tls-cert
    tls_key_handle: secret://console/tls-key
  diagnostics:
    file_log: false
    max_file_mb: 16
    keep: 4

Unknown keys under settings are an error rather than being ignored, so a typo is caught at validation instead of silently doing nothing.

sources and destinations

Both are lists of components. Each one has a type, a name you choose, and its settings:

sources:
  - type: wel
    name: security-log
    channels: [Security]
    params:
      read_existing: "false"

destinations:
  - type: tls
    name: siem
    params:
      address: "siem.example.com:6514"
      format: "syslog-5424"

Names must be unique across sources and destinations, because pipelines refer to them by name.

A source may carry enabled: false to keep it in the file without running it. Destinations and stages cannot — to stop delivering, disable the pipeline.

Some components take a structured block beside params — channels: and filter: on a Windows Event Log source, watch_items: on a file-integrity source, rules: on a filter or mask stage. These are richer than a flat list of values, which is why they sit outside params.

Every type and every setting is listed in the Configuration reference.

pipelines

A pipeline joins one source to one or more destinations, through stages that run in the order you list them.

pipelines:
  - name: security-to-siem
    source: security-log
    destinations: [siem]
    backpressure: spill
    stages:
      - type: filter
        name: drop-noise
        rules:
          action: drop
          rule:
            pred: { field: event_id, op: in, values: ["4688", "5156"] }
      - type: mask
        name: redact-pii
        rules:
          - detector: email
            fields: ["*"]
            action: redact

You can have up to 32 pipelines, each delivering to up to 8 destinations.

When a destination cannot keep up

If several pipelines share a destination they must all choose the same policy, because they share one queue.

pause_source cannot be used with a destination that waits for acknowledgement from the receiver.

Fanning out and sharing

• One pipeline, several destinations: list them all. Each receives the same processed events.
• One destination, several pipelines: it is a single queue, fed by both.
• A source can feed only one enabled pipeline. To send one source to two different processing paths, use one pipeline with several destinations.

Secrets are never in the file

A configuration file never contains a password, token, or private key. It contains a handle:

params:
  token_handle: "secret://splunk/hec-token"

The value lives in the machine's protected secret store, sealed so it can only be read on that machine by that service. You put it there at install time, or from the console, or with a command:

"C:\Program Files\DPLens\dplens.exe" --set-secret secret://splunk/hec-token

The value is read from standard input, never from the command line.

This is what makes a configuration file safe to check into source control and push to a fleet: the same file works on every machine, and the secret values differ per machine without the file ever knowing them.

Next

• Configuration reference — every setting.
• Configuration examples — worked configurations to copy.