How do I install Dynatrace OneAgent?

Your Dynatrace journey begins with OneAgent installation. Dynatrace OneAgent performs all tasks related to the monitoring of your hosts, processes, applications, infrastructure, and real user experience. OneAgent keeps you informed of each aspect of your application’s health and performance, tracking the response times of all service requests and user actions in real time and immediately raising alerts when variations to baseline performance are detected.

A single Dynatrace OneAgent can monitor all the technologies, services, and applications that run across your servers. For details on operating systems supported by Dynatrace OneAgent, see supported operating systems.

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.

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.

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.

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.

Run the installer

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.

Once you’ve confirmed that your OneAgent has been deployed to all relevant hosts, continue with monitoring setup.

Installing Security Gateway?

Because OneAgent has no direct access to Dynatrace, if you decide to install Security Gateway, perform installations in the following order:

  1. Download and install Security Gateway.
  2. Ensure that Security Gateway is connected to Dynatrace.
  3. Download and install OneAgent.

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.

Next steps

Following Dynatrace OneAgent installation you need to 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. For more information, see How do I enable deep process monitoring?