How do I install Dynatrace OneAgent?

When you register and log into Dynatrace for the first time, you see the tiles on your new Dynatrace homepage in a demo state. You can click any of the tiles to see what’s ahead. Each of the pages you’re directed to contains a link to our installer, which guides you through entire Dynatrace OneAgent installation. Just select Install Dynatrace OneAgent or Monitor my applications to begin installation.

You can get to our installer anytime via the Dynatrace menu, even after you’ve installed your first OneAgent. This works from demo pages as well.

The basic installation steps are very simple. Still we’ll guide you each step of the way.

Before you begin

What you need:

  • Your Dynatrace password for login.

  • Administrator credentials for the servers where Dynatrace OneAgent will be installed.

  • Administrator rights for changing firewall settings (necessary only if your internal routing policy could prevent Dynatrace software from talking to the Internet).

All hosts that are to be monitored require full Internet access.

Step 1: Download the installer

There are three types of installers you can download:

  • Windows installer for single server installation (EXE file).This is the most commonly used file for Windows deployments.
  • Windows installer for Group Policy deployments. You get a ZIP package that includes an MSI file and an example command line in the form of a batch file (you can copy and paste the command line when configuring Group Policy for Dynatrace installation).
  • Linux shell script installer. Use this on any Linux system supported by Dynatrace, no matter what packaging system your distribution depends on.

How you download your installer depends on your setup and needs. You can choose to download the installer directly to the server where you plan to install Dynatrace OneAgent or you can download the installer to a different machine and then transfer the installer to the server.

Get the Linux installer

Downloading the installer for Linux is fairly easy—just copy the command line for wget from your web browser and paste it into your terminal window. Wait for the download to complete and begin installation.

Make sure your system is up to date, especially SSL and related certificate libraries. If you plan to download Dynatrace directly to a server, note that outdated libraries (for example, CA certificates) or no OpenSSL will prevent the installer from downloading (we use encrypted connections and OpenSSL is needed to enable wget to access the server).

You can also download the installer by clicking the link and saving the installer script to any location you want (bypassing the wget command altogether).

Get the Windows installer

You can download the Dynatrace installer for Windows with a single click—click the Download agent.exe button to download the installer directly to the server that you intend to monitor, or to any other suitable location.

The OneAgent download page for Windows gives you access to the standard installer (for manual installation to a server) and an installer for Group Policy deployment.

Step 2: Install OneAgent

You’ll need administrator rights to install OneAgent:

On Windows, run the executable file and follow the displayed instructions.

On Windows, Dynatrace OneAgent runs as a system process.

On Linux, you’ll need root privileges. You can use su or sudo to run the installation script. To do this, type one of the following commands into the directory where you downloaded the installation script.

If you’re on an Ubuntu Server, use the following command:

sudo /bin/sh Dynatrace-Agent-Linux-1.0.0.sh

If you’re using Red Hat Enterprise Linux:

su -c '/bin/sh Dynatrace-Agent-Linux-1.0.0.sh'

If you start a root session:

/bin/sh Dynatrace-Agent-Linux-1.0.0.sh

On Linux, Dynatrace OneAgent runs as root.

During the installation process, the installer:

  • Checks for an Internet connection. If the check fails, you’ll be assisted in configuring proxy details. If your system has global proxy settings, your agent will discover them and prompt you for permission to use them.
  • Connects to Security Gateway (assuming you’ve downloaded the OneAgent file after Security Gateway connected to Dynatrace).
What happens during installation?

Dynatrace 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.

There are slight differences between OneAgent installations on Windows and Linux, but they are essentially the same: they install executable code and libraries that are used by Dynatrace OneAgent.

The Windows installer creates entries in the Windows Registry that start Dynatrace OneAgent as a SYSTEM service. Additionally, the oneagentmon device and WinPcap are installed to allow better integration with the operating system and to facilitate the capture of network statistics.

On Linux, agent binaries are installed in the /opt/dynatrace/oneagent directory and startup scripts are created in /etc/init.d (on systemd systems, startup scripts are created in /etc/systemd/system/). One of the Linux agent components, liboneagentproc.so , is located in the system library directory (/lib or /lib64 depending on your architecture) and is enabled at /etc/ld.so.preload .

For Dynatrace OneAgent versions 102 and earlier, Linux agent binaries are installed at /opt/ruxit/agent/ and the specified Linux agent component is called libruxitagentproc.so.

The agent installation program modifies the SELinux security policy. It allows Dynatrace OneAgent to add its own library between the system and the monitored processes.

The Dynatrace OneAgent installer also creates its own user (dtuser), which is used for services that don’t require root privileges to increase the security of those services.

The Dynatrace OneAgent installer for Linux also modifies the core pattern configuration so that Dynatrace OneAgent can detect and report process crashes. The original core_pattern configuration will still work following installation and be preserved in /opt/dynatrace/oneagent/agent/.original_core_pattern. To define your own core settings, you can modify the core_pattern configuration at /opt/dynatrace/oneagent/agent/.original_core_pattern, using the same format as specified here: http://man7.org/linux/man-pages/man5/core.5.html

Finally, when Dynatrace discovers a pre-existing non-OneAgent agent in your system, the OneAgent installer disables the third-party agent to avoid conflicts. You can reverse this action at any time by disabling host monitoring at Settings > Monitoring overview.

oneagentmon device on Windows

“oneagentmon device” appears in your Windows system during Dynatrace OneAgent installation. It’s used by Dynatrace for deep process monitoring. It works like a monitoring driver and allows Dynatrace OneAgent to add its own library between the operating system and processes it is running.

WinPcap on Windows

It’s recommended that you install the version of WinPcap that is packaged with the Dynatrace OneAgent installer. Its library is the cornerstone of Dynatrace network analysis. We’ve packaged the library in such a way that its DLLs are seamlessly integrated with Dynatrace software, thereby enabling unattended updates and other advantages. If you already have WinPcap installed, please remove it before Dynatrace OneAgent installation. The installer includes the latest, unmodified version of the library—so any other software you have that relies on WinPcap won’t suffer from library loss.

Each successful OneAgent installation is recorded by Dynatrace. You’ll see that your OneAgent has been successfully deployed once communication is established between your OneAgent and Dynatrace.

Installing Security Gateway?

If you’re concerned that your security policy or network configuration may block monitoring data that Dynatrace OneAgent sends to Dynatrace, use a proxy server or install Security Gateway to direct monitoring data to the Internet. This way, when the OneAgent installer discovers that Dynatrace can’t be reached, it will help you configure a connection using a proxy server.

It’s recommended that you install Security Gateway to manage how your servers forward encrypted monitoring data to the Dynatrace in the cloud. With Security Gateway you avoid configuring individual firewall settings and modifying routing tables. If you decide to install Security Gateway later, that’s fine—your OneAgent will be reconfigured to use it automatically.

It’s crucial that you download the OneAgent installer when Security Gateway is connected to Dynatrace. Otherwise, the OneAgent installer won’t be updated with your Security Gateway information and OneAgent won’t be able to connect to Dynatrace via your Security Gateway.

Step 3: Restart your server processes

What you need:

  • Administrator credentials for the servers where you’ve installed Dynatrace OneAgent.
  • Permission and credentials required for restarting all your application services.

While still logged into the systems where your server processes run, you need to restart each process so that its command line can be modified. The processes that require restart are listed for you during setup.

To restart your server processes, you’ll need to restart your web or application server. If your server is operating in a production environment, you may want to hold off on restart until the next scheduled maintenance period.

You’ve arrived!

Great, the first stage of Dynatrace setup is complete! Now take a look around your new home dashboard.

There’s a lot you can do to customize your home dashboard, including adding and arranging your monitoring tiles, but you’ll probably want to wait on that until after you’ve completed Dynatrace setup. If you’re impatient , you can read about 4 things you’ll absolutely love about Dynatrace.

Virtualization monitoring is indispensable if you depend on virtualized infrastructure in your data center. Once you include virtualization in your Dynatrace performance monitoring, you gain insight into your complete infrastructure stack and see how the virtual machines in your environment affect the performance of your applications.

Before connecting Dynatrace to your virtualization platform you should install Security Gateway. Security Gateway polls your vCenter or standalone ESXi hosts to obtain metrics for all the important resources that have been provisioned for your virtual machines (for example CPU usage, memory consumption, and data-store related activity).

Once you’re done with Security Gateway installation, enter the connection details that Dynatrace needs to connect to your VMware platform.

For full details on this step, see How do I start VMware monitoring?

Log into Dynatrace

You can now access your new Dynatrace home dashboard. Just go to and click the Login button in the upper-right corner.