Installing from the MSI

Installing interactively

1. Sign in as a local administrator.
2. Verify the download.
3. Double-click dplens.msi and follow the prompts.
4. When it finishes, open https://localhost:8443.

Because no administrator password was supplied, the console has no account yet and will ask you to create one the first time you open it. Go on to Your first hour.

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

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

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

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:

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-1.0.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 and REMOVE_STATE still apply. See The deployment MSI.

Service account

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.

You can change this by installing again with the other value; the service is re-created in place and your configuration and state are kept.

Uninstall

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 is installed where

The program folder contains the executable and nothing else. Everything 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.