Getting started

Installing from the MSI

Install interactively or silently, and the full list of installer options.

Installing interactively

  1. Sign in as a local administrator.
  2. Verify the download.
  3. Open an elevated command prompt in the folder that holds the package and run it with the console password (see Setting the console password):
   msiexec /i dplens.msi ADMIN_PASSWORD=<a strong password>
  1. When it finishes, open https://localhost:8443 and sign in as admin.

Go on to Your first hour.

Setting the console password

The installer does not prompt for a password. Set it with the ADMIN_PASSWORD property, on an interactive install as above or on a silent install. Use at least 12 characters — the console requires that length when the password is changed.

ADMIN_PASSWORD is a hidden installer property: Windows Installer does not write its value to the installation log, even with verbose logging. It is, however, part of the command you type, so it can remain in that prompt's command history until you close it, and other programs running on the machine during the installation can see it. Install from a prompt you close afterwards.

Once you have signed in, change the password from Settings → Admin password so that the one used during installation is no longer valid.

Installing silently

Everything the installer can do is available from the command line, so you can script a complete, ready-to-run installation in one step.

Run from an elevated command prompt:

msiexec /i dplens.msi /qn ^
  ADMIN_PASSWORD=<a strong password> ^
  LICENCE_FILE=C:\deploy\dplens.lic ^
  CONFIG_FILE=C:\deploy\agent.yaml ^
  /l*v C:\deploy\install.log

That installs the package, creates the console account, applies and verifies the licence against this machine, installs your configuration, and starts the service.

Always capture a log with /l*v when you are installing silently. It is the only place a failure explains itself.

Passwords, secrets and licence keys passed as options are marked hidden.

They appear in the installer log as **********, never as their value.

Installer options

Pass these as PROPERTY=value on the msiexec command line.

Configuration

OptionWhat it does
CONFIG_FILEPath to a configuration file to install. It is validated before anything is written; an invalid file fails the installation and leaves the machine untouched.
CONFIG_YAMLThe same configuration embedded directly in the command as base64url text, for when the target machine cannot see your file. Up to 1 MB.
UI_PORTThe port the console listens on, 1024–65535. Default 8443.
CONSOLEon (default) or off. off means no console process runs at all — use it for machines managed entirely by configuration.

CONFIG_FILE and CONFIG_YAML cannot be combined with each other, or with UI_PORT or CONSOLE. A supplied configuration file carries its own console settings, so accepting both would leave two answers to the same question.

Licence

OptionWhat it does
LICENCE_KEYA licence key as a single line of text, beginning DPL1.
LICENCE_FILEPath to a .lic file containing that key.

The key is verified against this machine before anything is written. If it is for a different machine or a different domain, or if it has expired, the installation fails and tells you which. See Licensing.

Console account

OptionWhat it does
ADMIN_PASSWORDThe password for the console's admin account. A hidden property: never written to the installation log. Change it from the console once you have signed in — see Setting the console password.

The password is passed to the agent over its standard input, never on a command line a process listing could show. It is stored as a password hash, not recoverable.

If you do not set one, the console asks you to create an account the first time you open it.

Secrets

Configuration files never contain secret values. They contain handles — references such as secret://splunk/hec-token — and the actual value is held in the machine's protected secret store. You seed those values at install time:

OptionWhat it does
SECRET1_HANDLE … SECRET8_HANDLEThe handle a setting in your configuration refers to.
SECRET1 … SECRET8The value to store under that handle.

Up to eight pairs. For example:

msiexec /i dplens.msi /qn ^
  CONFIG_FILE=C:\deploy\agent.yaml ^
  SECRET1_HANDLE=secret://splunk/hec-token SECRET1=<the token> ^
  SECRET2_HANDLE=secret://console/tls-key  SECRET2=<the key>

Values are sealed to the machine. They cannot be read back — not from the console, not from a log, not by copying the folder to another machine.

For a fleet, do not put secrets on a command line that a policy object or a management tool stores: capture a configured machine into a deployment MSI, which carries them encrypted.

The deployment MSI

A package built by dp-deploy build-msi — named dplens-<version>-deploy.msi — is the product MSI with a configured machine's capture inside it. It installs with no properties at all:

msiexec /i dplens-26.10.912-deploy.msi /qn /norestart /l*v C:\deploy\install.log

It needs the deployment key staged on the machine first, and it refuses every configuration, licence, console and secret property above by name — CONFIG_FILE, CONFIG_YAML, LICENCE_KEY, LICENCE_FILE, ADMIN_PASSWORD, UI_PORT, CONSOLE and the SECRET pairs — because the package carries its own answer to each. SERVICE_ACCOUNT, REMOVE_STATE and the Manager enrolment options still apply. See The deployment MSI.

Service account

OptionWhat it does
SERVICE_ACCOUNTvsa (the default on a fresh installation) or localsystem.

vsa runs the service as the virtual service account NT SERVICE\dplens, holding only three privileges. localsystem is the fallback for environments that cannot use virtual service accounts; it is a broader account, and the choice is recorded in the audit log.

The choice is remembered: an upgrade or reinstall that does not pass SERVICE_ACCOUNT keeps the account the agent already runs as. You can change it by installing again with the other value; the service is re-created in place and your configuration and state are kept.

Manager enrolment

These enrol the agent with your own DPLens Manager during installation. They are accepted on a fresh installation only — on a machine where DPLens is already installed, use dplens.exe --enrol instead. Leave them all out and the agent is a standalone agent that never connects to a Manager. See Enrolling an agent with DPLens Manager.

OptionWhat it does
MANAGER_URLThe Manager's enrolment address: https:// + host, optionally :port, optionally a trailing /.
MANAGER_CA_PINThe fingerprint of the certificate authority the Manager's certificate is issued from: sha256: + 64 lowercase hexadecimal characters.
MANAGER_POOL_IDThe licence pool the Manager serves: 32 lowercase hexadecimal characters.
ENROL_TOKENThe enrolment token from the Manager. Hidden: never written to the installer log.
MANAGER_PROXYOptional. An HTTP proxy for reaching the Manager: host:port, optionally with http://.
ALLOW_MANAGED_RECEIVERS1 lets the Manager configure syslog and NetFlow receivers on this machine; 0 or absent forbids it.
MANAGED_RECEIVER_BINDThe addresses a Manager-configured receiver may listen on: up to 32 addresses or CIDR ranges, comma-separated.
MANAGED_RECEIVER_ALLOWThe senders a Manager-configured receiver may admit: up to 32 addresses or CIDR ranges, comma-separated.
DISK_RESERVE_FLOORThe free space, in bytes, that no Manager-configured cache may eat into. Without it the floor is the larger of 10% of the cache's volume and 2 GiB.

MANAGER_URL, MANAGER_CA_PIN and MANAGER_POOL_ID are required together. The receiver and disk options are limits on what the Manager may do; they are set only here or with dplens.exe --enrol, never by the Manager, and they make no difference to an agent that is not enrolled.

Uninstall

OptionWhat it does
REMOVE_STATE=1On uninstall, also delete C:\ProgramData\DPLens — configuration, state, cache and secrets.

Without it, uninstalling leaves your configuration and state behind so a reinstall picks up where it left off.

When an installation fails

The installer is deliberately strict: it would rather refuse than leave you with a half-configured agent. Every refusal below rolls the machine back to how it was.

What happenedWhat to do
The configuration file is not validThe log names the problem. Fix the file and run again.
The licence is for a different machine or domainCheck you are using the right key for this host. See Licensing.
The licence has expiredObtain a current key.
CONFIG_FILE was combined with UI_PORT or CONSOLEPut the console settings in the configuration file and drop the separate options.
A newer version is already installedDowngrades are refused. Uninstall the newer version first, or install the newer package.
The state folder was written by a newer versionThe machine previously ran a newer build. Install that version, or uninstall with REMOVE_STATE=1 and start fresh.
A Manager enrolment option was refusedThe log names the option and the reason — see When enrolment is refused. An upgrade carrying Manager options is refused by name: use dplens.exe --enrol.

What is installed where

ProgramC:\Program Files\DPLens\dplens.exe
ConfigurationC:\ProgramData\DPLens\config\agent.yaml
LicenceC:\ProgramData\DPLens\config\licence.key
Working stateC:\ProgramData\DPLens\state\
Servicedplens, automatic start
Update runnerC:\Program Files\DPLens\update\runner\ and the scheduled task \DPLens\UpdateRunner

The program folder contains the executable and the update runner's copy of it. The runner and its task exist on every installation and stay idle unless the agent is enrolled with a DPLens Manager that asks it to upgrade — see Automatic upgrades from the Manager. Everything else DPLens writes lives under C:\ProgramData\DPLens, with permissions set so that only administrators and the service account can read it.

For the full layout, see How DPLens is configured.

Next

Your first hour.