Install OneAgent on Windows
This page describes how to download and install Dynatrace OneAgent on Windows.
- If you're a Dynatrace SaaS customer, go to Dynatrace.com, click SaaS login, and sign in using the username and password you received from Dynatrace in your signup confirmation email.
- If you're a Dynatrace Managed customer, access the Cluster Management Console and choose the environment you want to monitor.
Then continue with the installation steps below.
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 for restarting all your application services.
- You need to check also 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 that are to be monitored need to be able to send data to the Dynatrace cluster. Depending on whether your Dynatrace deployment is on SaaS, or on Managed environment, and on your network layout and security settings, you may choose to either provide a direct access to Dynatrace cluster, or to set up an ActiveGate.
- For OneAgent version 1.253 and earlier, we recommend that you uninstall any existing
WinPcapdriver to allow
Npcapinstallation—do this on all Windows versions, except for
Windows Server 2019 build 1809 without hotfix KB4571748.
For OneAgent version 1.255+,
Npcapis 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 KB4571748. To prevent it, upgrade your hosts with the hotfix KB4571748 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.
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 seamlessly integrated with Dynatrace software, enabling unattended updates.
For more information, see:
During the upgrade from
Npcap, you might encounter network disruptions that can be mitigated by upgrading your Windows Server version and/or disabling
Microsoft Network Monitor Driver. For more details, see Potential network disruptions during OneAgent installation on Windows
Re-installation or repair of installation
OneAgent installer for Windows doesn't support the
repair operations. You can't reinstall OneAgent using the same installer version as was used to install the currently installed OneAgent. To reinstall OneAgent, uninstall it first or simply install a newer version.
In Dynatrace Hub, select OneAgent.
Select Set up (latest Dynatrace) or Download OneAgent (previous Dynatrace) > Windows.
Provide a PaaS token. The token is required to download OneAgent installer from your environment. If you don't have a PaaS token, you can generate one right in the UI. The token is automatically appended to the download command you'll use later.
Download the installer. There are two options:
- Select Download OneAgent installer to download the installer for Windows (EXE file) for single-server installation.
- Download via Windows Command Prompt. Copy and run the
powershellcommand. It is generated automatically when you provide the PaaS token.
This command will only work with PowerShell 3.0 and TLS 1.2 (or .later).
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:
1C:\Downloads\Dynatrace-OneAgent-Windows.exe --unpack-msi "C:\installers"
Download the OneAgent installer provided as an EXE file.
- Run it with the
--unpack-msiparameter. 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:
When using the
--unpack-msiparameter, no other installation parameters are allowed. Add the
--quietparameter to run the MSI package extraction in quiet mode. Use the
--helpparameter 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.
optional Customize your installation
At this point, the Dynatrace UI allows you to customize your OneAgent installation: You can specify a number of customizations interactively on-screen. Based on your entries, an installation command will be generated and displayed, for use in the next step of installation (see below).
- Set a network zone for this host.
- Organize your hosts into host groups, if your environment is segmented (for example, into development and production).
- Override automatically detected host name. This is useful in large and dynamic environments, where defined host names can be unintuitive or can change frequently.
- Apply tags to the host to organize your monitored environments in a meaningful way.
- Change the OneAgent mode to Infrastructure Monitoring or Discovery in place of Full-Stack Monitoring. For more information, see Infrastructure and Discovery monitoring modes.
- Disable Log Monitoring.
If further customizations are required, you can specify additional options on the command line.
If you have not specified any custom options, simply 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.
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.
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
SYSTEMservice. Additionally, the
oneagentmondevice and (optionally)
WinPcapare 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
dtuseris not allowed to:
Access computer from the network.
Log in as a batch job.
Log in locally.
- Log in through Remote Desktop Services.
dtuseris required for Dynatrace to operate properly, therefore you must not delete it. If, for some reason, the
dtuserwas deleted, next update will recreate it.
OneAgent version 1.195+ For fresh OneAgent 1.195+ installations, the default
LocalSystem accountis used to run OneAgent extensions. For a summarized view of the changes made to your system by OneAgent installation, see OneAgent security on Windows.
Great, setup is complete! You can now take a look around your new monitoring environment. If you are a SaaS customer, you can access your monitoring environment anytime by going to Dynatrace website and clicking the Login button in the upper-right corner. If you are a Dynatrace Managed customer, you can access your monitoring environment through the Cluster Management Console.
One last thing: to monitor your processes, you need to restart them. At any time, you can check which processes aren't monitored and need to be restarted. Just go to Deployment Status, switch to the All hosts or Recently connected hosts tab, and expand the host you are interested in.