DEV Community

Cover image for OneAgent Windows silent install: deploying on Windows Server with PowerShell
Span Observer
Span Observer

Posted on Originally published at span.observer

OneAgent Windows silent install: deploying on Windows Server with PowerShell

#automation #dynatrace #dynatracemanaged #monitoring

On a Windows Server estate, interactive OneAgent installation quickly shows its limits. Clicking « Next » on three test servers is fine; repeating the same operation on two hundred IIS servers, .NET hosts and Windows service hosts, without a host group mistake or a forgotten proxy, is wishful thinking. You need a silent, parameterised rollout that your usual tools can drive: GPO, SCCM/MECM, Ansible WinRM or a simple PowerShell script. That is exactly what a OneAgent Windows silent install provides.

With Dynatrace Managed, the stakes are twofold. On one side, the agent must reach a cluster hosted in your own infrastructure, with your internal certificates, your outbound proxies and sometimes dedicated ActiveGates per zone. On the other, the licence quota is a fixed budget that you manage yourself in the Cluster Management Console (see environments and licence quotas): an uncontrolled Full-Stack rollout on servers that do not need it costs you straight away.

This guide details a silent OneAgent installation on Windows Server connected to a Managed environment, from fetching the installer to verification, including the essential parameters and post-installation adjustments.

What changes on Windows

The principle is the same as for OneAgent on Linux: an installer specific to your environment, command-line parameters to set the monitoring mode, the host group and the network zone, then an oneagentctl tool to change the configuration. A few practical differences deserve attention, though:

  • The installer is an executable (.exe) that wraps an MSI package. It accepts a silent mode and the same --set-… parameters as on Linux.
  • The agent runs as a Windows service; the installation session must have local administrator rights.
  • IIS applications, .NET applications and Windows services that are already running must be restarted to be instrumented in Full-Stack.
  • Antivirus and EDR tools can block or slow down injection: plan the exclusions recommended by your security team in line with the documentation.

Prerequisites

  • Windows Server in a version supported by your OneAgent version (see the compatibility matrix).
  • A local administrator account and Windows PowerShell (the examples below were written for version 5.1).
  • An environment API token with permission to download installers.
  • The environment ID, found in the URL https://{your-domain}/e/{environment-id}.
  • The target value for the host group and the network zone.
  • About 775 MB for the installation under %PROGRAMFILES%\dynatrace\oneagent and close to 11.5 GB in total once logs, dumps, persistence and updates are counted (under %PROGRAMDATA%\dynatrace\oneagent).
  • If the cluster certificate is issued by an internal PKI, the root authority must be in the machine’s certificate store.

Step-by-step tutorial: OneAgent Windows silent install

Step 1 — Test connectivity

In an administrator PowerShell console:

$headers = @{ Authorization = "Api-Token {token}" }
Invoke-WebRequest -UseBasicParsing `
  -Uri "https://{your-domain}/e/{environment-id}/api/v1/time" `
  -Headers $headers | Select-Object StatusCode

# If the zone goes through an Environment ActiveGate
Test-NetConnection -ComputerName {activegate-host} -Port 9999
Enter fullscreen mode Exit fullscreen mode

The /api/v1/time call requires the DataExport scope: with a download-only token, a 401 or 403 error already proves that the network and TLS work, and a 200 also validates the token. If there is a certificate error, the missing piece is almost always the internal root authority.

Step 2 — Download the installer 

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
$out = "C:\Temp\Dynatrace-OneAgent-Windows.exe"
New-Item -ItemType Directory -Force -Path C:\Temp | Out-Null

Invoke-WebRequest -UseBasicParsing `
  -Uri "https://{your-domain}/e/{environment-id}/api/v1/deployment/installer/agent/windows/default/latest" `
  -Headers $headers -OutFile $out

Get-Item $out | Select-Object Name, Length
Enter fullscreen mode Exit fullscreen mode

The executable embeds the environment ID and the agent’s connection token. Store it on a share whose access is restricted to deployment accounts.

Step 3 — Verify the signature 

Get-AuthenticodeSignature $out | Format-List Status, SignerCertificate
Enter fullscreen mode Exit fullscreen mode

The expected status is Valid. Any other status must block the rollout until it has been analysed.

Step 4 — Run the silent installation 

$installArgs = @(
  "--set-monitoring-mode=fullstack",
  "--set-host-group={application}_{environment}",
  "--set-network-zone={network-zone}",
  "--set-app-log-content-access=true",
  "--quiet"
)
$p = Start-Process -FilePath $out -ArgumentList $installArgs -Wait -PassThru
"Exit code: $($p.ExitCode)"
Enter fullscreen mode Exit fullscreen mode

An exit code of 0 means the installation succeeded. For a server that only needs infrastructure-level monitoring, use --set-monitoring-mode=infra-only. If a proxy is needed: --set-proxy={proxy-host}:{port}. The default installation directory can be changed with the MSI parameter INSTALL_PATH="D:\dynatrace", accepted by the executable but not by the installer’s graphical interface.

Step 5 — Check the service and the logs 

Get-Service | Where-Object { $_.DisplayName -like "*Dynatrace*" } |
  Select-Object Name, DisplayName, Status, StartType

Get-ChildItem "C:\ProgramData\dynatrace\oneagent\log" -Recurse |
  Sort-Object LastWriteTime -Descending | Select-Object -First 10 FullName
Enter fullscreen mode Exit fullscreen mode

The service must be Running and set to start automatically. The agent logs are under %PROGRAMDATA%\dynatrace\oneagent\log by default.

Step 6 — Restart the instrumented applications 

iisreset /restart
# or, for a specific application service
Restart-Service -Name {service-name}
Enter fullscreen mode Exit fullscreen mode

Coordinate this restart with the application teams: without it, existing processes stay visible but are not traced.

Step 7 — Adjust with oneagentctl 

$ctl = "C:\Program Files\dynatrace\oneagent\agent\tools\oneagentctl.exe"
& $ctl --get-host-group
& $ctl --get-network-zone
& $ctl --set-host-group={new-group} --restart-service
Enter fullscreen mode Exit fullscreen mode

These commands must be run as administrator. As on Linux, changing the host group affects the associated rules and alerts.

Deploying at scale

Tool Recommended approach Watch out for
SCCM / MECM Application with a silent command line and detection based on the service Never embed the token in plain text in the console
GPO (startup script) Idempotent PowerShell script reading the installer from a share Read rights on the share for machine accounts
Ansible (WinRM) win_get_url then win_command with the parameters Group variables for host group and zone

In every case, check whether the service is present before running the installer again, to avoid pointless reinstallations on every cycle.

Best practices

  • Validate the cluster’s certificate chain on a pilot server before any mass rollout.
  • Use a token dedicated to downloads, with minimal scope, stored in a vault.
  • Standardise host groups and network zones in your deployment variables, never by hand.
  • Agree antivirus/EDR exclusions with the security team upfront.
  • Schedule IIS/service restarts within a change window.
  • Monitor host unit consumption in the CMC after each rollout wave.

Frequently asked questions

How do I know the silent installation succeeded?

The exit code must be 0, then the Dynatrace service must be Running and set to start automatically. If it fails, check the logs under %PROGRAMDATA%\dynatrace\oneagent\log.

Why does the API call fail with a certificate error?

Almost always because the root authority of the internal PKI that signed the cluster certificate is missing from the machine’s certificate store.

Does IIS need restarting after installation?

Yes for Full-Stack: without a restart, IIS applications, .NET applications and services that were already running stay visible but are not traced. Schedule it within a change window.

Conclusion

A silent OneAgent installation on Windows Server comes down to one command line, but it is only reliable in a Managed context if the environment is ready: known internal certificates, ActiveGates and network zones in place, shared naming conventions and a protected token. With an idempotent PowerShell script and a few systematic checks, you turn a risky manual operation into a repeatable, auditable rollout.

span.observer is an independent community blog, not affiliated with Dynatrace LLC. Dynatrace is a trademark of Dynatrace LLC. Always check values (ports, versions, sizes) in the official documentation for your version of Managed.

Originally published on span.observer. French version: https://span.observer/fr/oneagent-windows-managed/.

Top comments (0)