How do I install Dynatrace OneAgent?

To install Dynatrace OneAgent go to Dynatrace.com and Login using the username and password you received from Dynatrace in your signup confirmation email. The basic installation steps are 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 may prevent Dynatrace software from reaching the Internet).
  • Permissions and credentials required for restarting all your application services.

Note

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

Step 1: Download the installer

  1. Select Deploy Dynatrace from the navigation menu.

  2. Click the Start installation button.

  3. Select one of the following installation options:

    • Windows installer (EXE file) for single-server installation. This is the most commonly used file for Windows deployments. Just click the Windows button. Then click the Download agent.exe button on the following page.

    • 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). For the group policy option, click the Windows button. Then click the Download MSI package link on the following page.

    • Linux shell script installer. Use this installation approach on any Linux system that’s supported by Dynatrace, regardless of the packaging system your distribution depends on. Click the Linux button. Then copy the command that’s provided in the Use this command on the target host text field and paste the command into your terminal. Once the download is complete, you can verify the signature by copying the command from the Verify signature text field and pasting the command into your terminal window. Make sure your system is up to date, especially SSL and related certificate libraries. If you plan to download Dynatrace OneAgent directly to a server, note that outdated or missing libraries (for example, CA certificates or OpenSSL) will prevent the installer from downloading (we use encrypted connections. OpenSSL is required to enable wget to access the server). You can also download the installer by clicking the Download OneAgent installer link and saving the installer script to any location you want (bypassing the wget command altogether).

Step 2: Install OneAgent

For Windows, run the executable file and follow the displayed instructions. You will need administrator rights to install OneAgent.

Note

On Windows, Dynatrace OneAgent runs as a system process.

For Linux, copy the command from the And run the installer with root rights text field and paste the command into your terminal. Note that you’ll need root privileges. You’ll need to make the script executable before you can run it. 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

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

Note

On Linux, Dynatrace OneAgent runs as root.

During the installation process, the installer

  • Checks the system’s global proxy settings. If your system has global proxy settings, OneAgent will discover them and prompt you for permission to use them. If a proxy is required for an Internet connection, but it’s not configured in the system’s global proxy settings, then you must configure the proxy.

  • Checks for a connection to Dynatrace Server or Security Gateway (if you installed Security Gateway and downloaded the OneAgent installer after Security Gateway was connected to Dynatrace).

What should I do if the check fails?

OneAgent is shipped with trusted Dynatrace SSL certificates, which are used to verify that OneAgent connects successfully to Dynatrace Server or Security Gateway.

If your environment uses a proxy (thereby requiring an update to the remote server’s SSL certificate), then you may encounter a Server certificate check failed message during the initial connection check. To resolve this issue, specify the trusted proxy certificate that is to be utilized by OneAgent. To do this, create a file called custom.pem in the following directory:

  • For Linux: /var/lib/dynatrace/oneagent/agent/customkeys/custom.pem
  • For Windows: C:\ProgramData\dynatrace\oneagent\agent\customkeys\custom.pem

The file custom.pem should contain the proxy’s certificate along with any intermediate certificates as required.

Note

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.

More about OneAgent 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, OneAgent 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 OneAgent 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.

Note

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

The OneAgent installer for Linux detects all SELinux-aware applications and adjusts the SELinux security policy accordingly. It also allows Dynatrace OneAgent to inject its own libraries into monitored processes.

The Dynatrace OneAgent installer also creates its own user (dtuser). For security purposes, this user is utilized by services that don’t require root privileges.

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 in Linux Programmer’s Manual.

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

Step 3: Restart your server processes

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.

Note

When you visit certain Host pages, Dynatrace may display a message telling you that you must restart the related host processes. Restart these processes to enable Dynatrace analysis of these hosts.

You can always check which process types Dynatrace supports.

Processes not detected?

One of the following may have occurred

  • The process isn’t supported by our monitoring technology.
  • The process isn’t working on your server. Please ensure that your servers are running and that the processes are operational.
  • There is delay in communication between Dynatrace and your Dynatrace OneAgent. If this is the case, please wait a few moments and try again.
  • Your Dynatrace OneAgent isn’t working properly. Go to Settings > Monitoring overview to confirm that monitoring is enabled for the host running your software.

If you’re still unable to resolve this issue, please contact us at Dynatrace answers. Also, consider installing Dynatrace OneAgent on a different machine.

You‘ve arrived!

Great, the first stage of Dynatrace setup is complete! Now take a look around your new home dashboard. You can access your new Dynatrace home dashboard anytime by going to Dynatrace website and clicking the Login button in the upper-right corner.