Install OneAgent using Puppet


Dynatrace provides a Puppet module that you can use to orchestrate OneAgent deployment in your environment. The OneAgent Puppet module is released as a Preview.

Prerequisites and requirements

  • OneAgent version 1.199+
  • Dynatrace version 1.204+
  • PaaS token to download the module
  • Puppet 6.0+
  • Puppet modules:
    • puppet/archive
    • puppetlabs/powershell (for Windows deployment)
  • Supported on Windows, Linux and AIX.

Download the module

Select Deploy Dynatrace from the navigation menu and then select Start installation.

Select Puppet module to download the module tarball.
This is a safe archive hosted in your environment. Place the resulting artifact in your Puppet Server node.

optional On Linux, you can verify the authenticity of the archive using the detached signature file.

  • Select Signature to download the sig file.
  • Make sure the downloaded Puppet module tarball and the signature file are stored in the same directory.
  • Navigate to the directory where you saved the files and run the following command, substituting the name of the module to the actual name as downloaded:
    wget; openssl cms \
    -verify -binary \
    -in dynatrace-oneagent-puppet- \
    -inform PEM \
    -content dynatrace-oneagent-puppet- \
    -CAfile dt-root.cert.pem >/dev/null
    Successful verification will result in the following output:
    --2020-09-25 12:40:47--
    Resolving (,,, ...
    Connecting to (||:443... connected.
    HTTP request sent, awaiting response... 200 OK
    Length: 2172 (2.1K) [application/x-pem-file]
    Saving to: ‘dt-root.cert.pem’
    dt-root.cert.pem 100%[========================>]   2.12K  --.-KB/s    in 0s
    2020-09-25 12:40:48 (102 MB/s) - ‘dt-root.cert.pem’ saved [2172/2172]
    Verification successful

Install the module

Save the module tarball to a directory on your Puppet server.

Navigate to the directory where you saved the module tarball and run the following command:

puppet module install dynatrace-oneagent-puppet-

This will install the dynatrace/oneagent module that deploys OneAgent using a dedicated configuration and ensures that the OneAgent service maintains a running state. For more information, see Puppet module documentation.

Configure the module

The module requires access to the OneAgent installer. Depending on whether your Puppet server has access to your Dynatrace environment, you can either

  • configure the module to download the installer directly from your Dynatrace environment, or
  • download it yourself and upload it to the server node.

Direct download from your environment

The module utilizes the Dynatrace Deployment API to download a platform-specific installer to the target machine. You will need to specify the variables to supply the information required to authenticate the API call in your environment:

  • environment_url:

    • SaaS: https://{your-environment-id}
    • Managed: https://{your-domain}/e/{your-environment-id}
  • paas_token

    For example

class { 'oneagent':
    # Set environment variables
    paas_token => 'abcdefjhij1234567890',
    environment_url => '',
    # (...)

See Examples.

Local installer

You can use the Dynatrace web UI to download OneAgent and then upload it to a directory on the server node. Use the local_installer variable to point the module to the directory. For example,

class { 'oneagent':
     # Set environment variables
     local_installer => mounting_point/path/to/
     # (...)

This feature requires a configured file server on the server node. Use the Dynatrace UI to download OneAgent and upload it to proper mounting point on the server node. During execution, the module will then download the installer from the Puppet server to the Puppet agent(s). Note that Windows, Linux, and AIX require their dedicated installers. Original installer names indicate the target platform. If you need to change the installer names, make sure the module can distinguish them. If you don't specify the installer, the module will attempt to use the direct download from the Dynatrace environment.


The OneAgent module supports the variables:

Name Default Required1 Description
environment_url unset ✔️ URL of the target Dynatrace environment (SaaS or Managed).
paas_token unset ✔️ The PaaS token retrieved from the Deploy Dynatrace installer page.
local_installer unset ✔️ Path to the OneAgent installer at the configured mounting point.
installer_arch unset Specifies the installer architecture
version latest The required OneAgent version in the form See how to list available versions of OneAgent installer for more details.
download_dir Linux/AIX: $TEMP or /tmp
Windows: %TEMP% or C:\Windows\Temp
Installer's download directory. The directory must be available to the module. For Linux and AIX, the directory must not contain spaces.
install_args unset Dynatrace OneAgent installation parameters defined as a list of items.
platform_install_args unset Additional list of platform-specific installation parameters, appended to `install_args' when run on a respective platform.
preserve_installer false Preserves installers on secondary machines after deployment.
package_state present OneAgent package state; use present or latest to make sure it's installed, or absent in order to uninstall.
validate_certs true If set to false, allows you to download OneAgent from a server with insecure SSL certificate (expired, self-signed, etc).
proxy_server unset Proxy server to be used for downloading the OneAgent installer.

1 Depending on the way your module accesses the OneAgent installer, one of the two is required: environment_url plus paas_token, or local_installer.


This example manifest

  • downloads the OneAgent installer in a specific version (version) and saves it to a custom directory (download_dir)
  • instructs the module to deploy OneAgent to the Linux and Windows hosts with given configuration
  • instructs the script to use the ppcle installer architecture
  • uses install_args to pass the OneAgent installation parameters that assign the hosts to the My.HostGroup_123-456 host group and network zone, and enable the Infrastructure Monitoring mode.
# Download OneAgent installer in specific version to a custom 
# directory with additional OneAgent install parameters

$env_url = ''
$paas_token = 'abcdefghijk1234567890'
$install_args = [ '--set-host-tag="common_tag"', '--set-host-property="prop1=value1"' ]
$preserve_installer = true
$version = ''

if $::osfamily == 'Windows' {
  class { 'oneagent':
    environment_url => $env_url,
    paas_token => $paas_token,
    preserve_installer => $preserve_installer,
    install_args => $install_args,
    platform_install_args => [ 'INSTALL_PATH=C:\\dynatrace', 'USER=LocalService' ],
    download_dir => 'C:\\temp',
    version => $version
} else {
  class { 'oneagent':
    environment_url => $env_url,
    paas_token => $paas_token,
    preserve_installer => $preserve_installer,
    install_args => $install_args,
    platform_install_args => [ 'INSTALL_PATH=/opt/dynatrace', 'USER=linux_user' ],
    download_dir => '/tmp',
    version => $version,
    installer_arch => 'ppcle'

You can find more example manifests in the examples directory. The directory contains the following manifests:

  • local_installer.pp - basic configuration with local installers.
  • advanced_config.pp - shows advanced configuration as in the example above.

Since Windows paths are different from those on Linux systems, see Path Formatting for Windows to avoid issues related to paths.