Install OneAgent on Windows

Latest Dynatrace
How-to guide
7-min read

Follow this guide to download and install Dynatrace OneAgent on Windows.

To get started, log in to your Dynatrace SaaS environment at Dynatrace.com using the credentials provided during signup. Then follow the installation steps.

Dynatrace provides an Ansible collection that you can use to orchestrate OneAgent deployment in your environment. For more information, see Install OneAgent using Ansible.

Requirements and prerequisites

You need administrator rights for the servers where OneAgent will be installed as well as for changing firewall settings (necessary only if your internal routing policy may prevent Dynatrace software from reaching the Internet).
You need permissions and credentials to restart all your application services.
Check the disk space requirements.
The host on which you install OneAgent needs at least 200 MB RAM.
OneAgent installation isn't supported on networked storage mount points that are managed by standards such as NFS or iSCSI.
All hosts you want to monitor must be able to send data to the Dynatrace cluster. Depending on your Dynatrace deployment and on your network layout and security settings, you may choose to either provide direct access to the Dynatrace cluster or set up an ActiveGate.
For OneAgent version 1.253 and earlier, we recommend that you uninstall any existing WinPcap driver to allow Npcap installation—do this on all Windows versions, except for Windows Server 2019 build 1809 without hotfix KB5066187. For OneAgent version 1.255+, Npcap is installed by default and may cause a network disruption on Windows Server 2016, Windows Server 2019 build 1809, and Windows Server 2019 build 1809 without hotfix KB5066187. To prevent it, upgrade your hosts with the hotfix KB5066187 or use other documented options.

Allow connections through firewall

Ensure that your firewall settings allow communication to Dynatrace.
Depending on your firewall policy, you may need to explicitly allow certain outgoing connections. The remote Dynatrace addresses to add to the allow list are given on the installation page for OneAgent.

Installation

Go to Discovery & Coverage and select Install > Install OneAgent.
Enter or select the following parameters.
- OS type
  
  Choose Windows as your operating system.
- Architecture
  
  The field is only applicable to Linux installations.
- Monitoring mode
  
  Options are Full-Stack, Infrastructure, or Discovery.
  
  If you are using a free Dynatrace trial, select Full-Stack to see everything that Dynatrace is capable of observing. You can always change the monitoring mode after installation. For details, see OneAgent monitoring modes.
- Optional parameters
  - Add a custom host name for easier identification.
  - Set a network zone for this host.
  - If your environment is segmented (for example, into development and production), consider organizing your hosts into host groups.
  - Apply tags to the host to organize your monitored environments in a meaningful way.
  - Add host properties to automate the addition of metadata to your hosts.
  OneAgent command-line installer provides more options to customize your installation.
  
  If you have not specified any custom options, run the executable file and follow the instructions as displayed.
  If you have specified custom options above, use the generated command, and run it from the download directory. The command will contain all the installation parameters reflecting the custom settings you have specified.
Paste an access token with the Download OneAgent and ActiveGate installers (InstallerDownload) scope into Installer download token, or select Generate token to create one now and automatically paste it. This token is required to download the OneAgent installer from your environment. The token is automatically appended to the download and installation commands you'll use later.
Download OneAgent

Download the installer. There are two options:
- Select Download to download the installer for Windows (EXE file) for single-server installation.
- Download via Windows Command Prompt. Copy the generated powershell command and run it in your Command Prompt window. The command is generated automatically when you provide the access token.
  This command will only work with PowerShell 3.0 and TLS 1.2 (or later).
Get MSI package
If you want to use Group Policy to automatically distribute OneAgent to your Windows hosts, you'll need the MSI package along with the batch file. To get the MSI package:
1. Download the OneAgent installer provided as an EXE file.
2. Run it with the --unpack-msi parameter. This extracts the MSI package and the installation batch file. Optionally, you can specify an existing path. If you skip the path, the files are saved to a working directory. For example:
```
C:\Downloads\Dynatrace-OneAgent-Windows.exe --unpack-msi "C:\installers"
```
When using the --unpack-msi parameter, no other installation parameters are allowed. Add the --quiet parameter to run the MSI package extraction in quiet mode. Use the --help parameter to display a pop-up window with a list of available parameters.
Copy and paste the MSI package and the batch file when configuring Group Policy for Dynatrace installation. The default installation should work in most cases, but if you need to customize it, you can modify the installation parameters. Then, you have to create a distribution point, assign a package (the OneAgent MSI package with parameters), specify a command to install the MSI package as silent installation, and publish your policy.
Install OneAgent as the privileged user

Depending on your environment, you can choose whether OneAgent is installed using a privileged user. For details, see administrator rights.
Show deployment status

Displays the recently connected hosts.
Restart all processes that you want to monitor.

You'll be prompted with a list of the processes that need to be restarted. Note that you can restart your processes at any time, even during your organization's next planned maintenance period. Though until all processes have been restarted, you'll only see a limited set of metrics, for example, CPU or memory consumption.

What happens during installation?

OneAgent is a set of specialized services that have been configured specifically for your monitoring environment. The role of these services is to monitor various aspects of your hosts, including hardware, operating system, and application processes.

During the installation process, the installer:

Installs executable code and libraries that are used by OneAgent.
Creates entries in the Windows Registry that start OneAgent as a SYSTEM service. Additionally, the oneagentmon device and (optionally) Npcap or WinPcap are installed to allow better integration with the operating system and to facilitate the capture of network statistics.
Checks the system’s global proxy settings.
Checks for a connection to Dynatrace Server or ActiveGate (if you installed ActiveGate and downloaded the OneAgent installer after ActiveGate was connected to Dynatrace).
OneAgent version 1.193 and earlier Creates its own user (dtuser) to run OneAgent extensions. This user is a member of the Performance Monitoring Users group, and can only log in as a service. The password is randomly generated during installation and stored encrypted. You can't change the password. For security purposes, the dtuser is not allowed to:
- Access computer from the network.
- Log in as a batch job.
- Log in locally.
- Log in through Remote Desktop Services.
  The dtuser is required for Dynatrace to operate properly; do not delete it. If the dtuser was deleted, the next update will recreate it.
For fresh OneAgent installations, the default LocalSystem account is used for running OneAgent extensions. For a summarized view of the changes made to your system by OneAgent installation, see OneAgent security on Windows.

You've arrived!

Great, the setup is complete! You can now take a look around your new monitoring environment.

You can access your monitoring environment anytime by going to Dynatrace website and selecting Login in the upper-right corner.

One last thing: to monitor your processes, you need to restart them. You can restart your processes at any time, even during your organization's next planned maintenance period. For details, see Infrastructure & Operations and Processes.

Reinstallation or repair of installation

The OneAgent installer for Windows doesn't support the modify and repair operations. You can't reinstall OneAgent using the same installer version that was used to install the currently installed OneAgent. To reinstall OneAgent, uninstall it first or install a newer version.

Troubleshooting

Uninstall WinPcap driver to allow Npcap installation

If you have the WinPcap driver installed, we recommend that you remove it prior to OneAgent installation and let the OneAgent installer install the appropriate packet capture driver as packaged with the OneAgent installer: Npcap is the recommended packet capture driver for OneAgent.

Npcap is the successor to WinPcap and is best suited for Dynatrace network analysis. The Npcap driver provided with the OneAgent installer is packaged in such a way that its DLL library files are integrated with Dynatrace software, which allows for unattended updates.

For more information, see:

During the upgrade from WinPcap to Npcap, you might encounter network disruptions that can be mitigated by upgrading your Windows Server version or disabling Microsoft Network Monitor Driver. For details, see Potential network disruptions during OneAgent installation on Windows.