3.2 Host Installation on Linux, Windows & Containerized Hosts
Key Takeaways
- OneAgent installation requires administrative privileges (root on Linux, Administrator on Windows) to install system services and hook OS dynamic linkers.
- The Linux installer script and Windows MSI support extensive command-line flags (--set-<parameter>=<value>) to configure host groups, network zones, proxies, and monitoring modes at install time.
- The oneagentctl command-line utility enables post-installation configuration changes (such as reassigning host groups or switching monitoring modes) without reinstalling the agent, requiring a service restart to apply.
- On standalone containerized hosts (Docker/Podman), OneAgent runs as a privileged container requiring --privileged, --net=host, --pid=host, --ipc=host, and -v /:/node_root to inspect host-level namespaces.
Host Installation on Linux, Windows & Containerized Hosts
Exam Focus: Mastering the installation workflows, command-line parameter syntax, file path conventions, and post-installation management commands (
oneagentctl) across Linux, Windows, and containerized environments is heavily emphasized on the Dynatrace Certified Associate exam.
Deploying Dynatrace OneAgent across enterprise infrastructure involves several distinct operational scenarios: interactive installations on single virtual machines, mass unattended rollouts via configuration management tools (Ansible, Puppet, Chef, Terraform), and containerized deployments on minimal operating systems. Regardless of the deployment vehicle, understanding the prerequisites, parameter flags, and configuration utilities is vital for production readiness.
Installation Prerequisites and Network Communication Architecture
Before executing the OneAgent installer, administrators must verify administrative privileges and network egress paths:
- Administrative Privileges: Installing OneAgent in Full-Stack mode requires
rootprivileges on Linux or localAdministratorprivileges on Windows. These elevated rights are required to install system daemons (systemdunits or Windows Services), modify/etc/ld.so.preloador Windows AppInit/registry keys, and attach network packet capture drivers. - Outbound Network Connectivity: OneAgent establishes strictly outbound connections. It does not require any inbound firewall ports to be opened on the monitored host. Communication occurs over encrypted TLS via:
- Port 443: Direct outbound connection to Dynatrace SaaS or a Dynatrace Managed Cluster.
- Port 9999 (or 443): Outbound connection to an Environment ActiveGate or Cluster ActiveGate proxy.
- Default Installation Directories:
- Linux: Binaries reside in
/opt/dynatrace/oneagent, runtime configuration in/var/lib/dynatrace/oneagent, and agent logs in/var/log/dynatrace/oneagent. - Windows: Binaries reside in
C:\Program Files\dynatrace\oneagent, while configuration and logs are stored inC:\ProgramData\dynatrace\oneagent.
- Linux: Binaries reside in
Linux Host Installation and Deployment Parameters
The Linux installation package is delivered as a self-extracting shell script (Dynatrace-OneAgent-Linux-<version>.sh). It can be downloaded directly from the Dynatrace web UI (Deploy Dynatrace > Start installation > Linux) or fetched programmatically via the Dynatrace Deployment API:
wget -O Dynatrace-OneAgent-Linux.sh "https://<environment-id>.live.dynatrace.com/api/v1/deployment/installer/agent/unix/default/latest?Api-Token=<paas-token>&arch=x86"
Code Signature Verification
Enterprise security compliance frequently mandates verifying the cryptographic integrity of installation binaries before execution. Dynatrace signs its Linux installers using an official X.509 certificate. Administrators verify the signature using OpenSSL:
# Download Dynatrace root certificate
wget https://ca.dynatrace.com/dt-root.cert.pem
# Verify installer package signature
openssl cms -verify -CAfile dt-root.cert.pem -in Dynatrace-OneAgent-Linux.sh -inform PEM
Linux Installation Command-Line Parameters
The OneAgent installer accepts extensive command-line flags to customize the deployment. In modern OneAgent versions, all configuration parameters utilize the standardized --set-<parameter>=<value> syntax:
| Installer Parameter | Values / Syntax | Description |
|---|---|---|
--set-infra-only | true | false (default: false) | Enables Infrastructure Monitoring mode. When true, OneAgent collects OS, network, and process metrics but disables deep code-level injection. |
--set-host-group | <group_name> | Assigns the host to a specific Host Group for collective configuration, filtering, and management zone routing. |
--set-network-zone | <zone_name> | Configures the host's preferred Network Zone to route traffic to local ActiveGates before falling back to other zones. |
--set-host-name | <custom_name> | Overrides the detected operating system hostname displayed in the Dynatrace web console. |
--set-host-tag | <key> or <key>=<value> | Assigns static metadata tags to the host entity at install time. Multiple tags are separated by spaces. |
--set-proxy | http://proxy.corp:8080 | Specifies an outbound HTTP/HTTPS proxy server for OneAgent communication. |
--set-server | https://activegate:9999 | Configures explicit ActiveGate or cluster communication endpoints. |
--set-app-log-content-access | true | false (default: true) | Controls whether OneAgent can read and stream log file contents to Dynatrace Log Management / Grail. |
--install-dir | /custom/path | Overrides the default binary installation directory (/opt/dynatrace/oneagent). |
Example Unattended Enterprise Execution
/bin/sh Dynatrace-OneAgent-Linux.sh \
--set-infra-only=false \
--set-host-group=Production_Ecomm \
--set-network-zone=us-east-dc1 \
--set-proxy=http://proxy.internal:8080 \
--set-app-log-content-access=true
Once executed, the installer creates a systemd service unit (oneagent.service), starts the agent daemons, registers /etc/ld.so.preload, and establishes an outbound TLS tunnel to the configured ActiveGate or Dynatrace environment.
Post-Installation Management with oneagentctl
In enterprise operations, host configurations frequently evolve after initial deployment: hosts are moved between environments, network routing zones change, or proxy servers are upgraded. Dynatrace provides a dedicated command-line administration utility called oneagentctl to manage OneAgent settings without requiring uninstallation or reinstallation.
Utility File Paths
- Linux:
/opt/dynatrace/oneagent/agent/tools/oneagentctl - Windows:
C:\Program Files\dynatrace\oneagent\agent\tools\oneagentctl.exe
Core oneagentctl Operations
| Task | Linux Command Example | Windows Command Example |
|---|---|---|
| Check Agent Version | ./oneagentctl --version | .\oneagentctl.exe --version |
| Check Monitoring Mode | ./oneagentctl --get-monitoring-mode | .\oneagentctl.exe --get-monitoring-mode |
| Set Monitoring Mode | ./oneagentctl --set-monitoring-mode=infra-only | .\oneagentctl.exe --set-monitoring-mode=fullstack |
| Query Host Group | ./oneagentctl --get-host-group | .\oneagentctl.exe --get-host-group |
| Update Host Group | ./oneagentctl --set-host-group=Payment_Backend | .\oneagentctl.exe --set-host-group=Payment_Backend |
| Query Network Zone | ./oneagentctl --get-network-zone | .\oneagentctl.exe --get-network-zone |
| Update Network Zone | ./oneagentctl --set-network-zone=dc-west | .\oneagentctl.exe --set-network-zone=dc-west |
| Configure Proxy | ./oneagentctl --set-proxy=http://gw.corp:8080 | .\oneagentctl.exe --set-proxy=http://gw.corp:8080 |
| Toggle Log Access | ./oneagentctl --set-app-log-content-access=true | .\oneagentctl.exe --set-app-log-content-access=false |
Exam Rule on oneagentctl Changes: Modifying host groups, network zones, proxy settings, or monitoring modes via
oneagentctlwrites the new parameters to local configuration storage. However, these changes take effect only after restarting the OneAgent service (systemctl restart oneagenton Linux, or restarting theDynatrace OneAgentservice on Windows).
Windows Host Installation and Silent MSI Automation
On Windows Server platforms, OneAgent is distributed as a Microsoft Installer package (Dynatrace-OneAgent-Windows-<version>.msi). While administrators can install the agent interactively via the MSI setup wizard, enterprise automation mandates silent, unattended installation using msiexec.exe.
Unattended Windows Command Syntax
Windows MSI properties are supplied as uppercase key-value pairs following the msiexec command:
msiexec.exe /i Dynatrace-OneAgent-Windows.msi /quiet /qn /l*v C:\oneagent_install.log ^
SERVER="https://activegate.corp.internal:9999/communication" ^
TENANT_TOKEN="dt0c01.sampletoken..." ^
INFRA_ONLY=0 ^
HOST_GROUP="Finance_Windows" ^
NETWORK_ZONE="us-east-zone" ^
PROXY="http://proxy.internal:8080" ^
APP_LOG_CONTENT_ACCESS=1
Key MSI Parameter Mappings
/quiet /qn: Enforces non-interactive, silent execution without displaying graphical user interface dialogs./l*v <path>: Generates an exhaustive verbose installation log for troubleshooting.INFRA_ONLY=1(or0): Sets Infrastructure Monitoring (1) or Full-Stack Monitoring (0).HOST_GROUP: Assigns the host group identifier.NETWORK_ZONE: Configures network routing preferences.
Following installation, OneAgent registers as a Windows service named Dynatrace OneAgent configured for automatic startup (service_type=SERVICE_AUTO_START). Administrators can query or restart the service using PowerShell:
Get-Service -Name "Dynatrace OneAgent"
Restart-Service -Name "Dynatrace OneAgent"
Standalone Containerized Host Deployment (Docker & Podman)
In cloud environments running minimal, container-optimized Linux distributions (such as CoreOS, AWS Bottlerocket, or Google Container-Optimized OS), the host operating system root filesystem is often read-only, and standard package managers (yum, apt) are omitted. In these environments, OneAgent can be deployed as a containerized agent running directly on Docker or Podman.
The Mandatory Container Run Command
docker run -d \
--restart=unless-stopped \
--net=host \
--pid=host \
--ipc=host \
--privileged \
-v /:/node_root \
-e ONEAGENT_INSTALLER_SCRIPT_URL="https://<env>.live.dynatrace.com/api/v1/deployment/installer/agent/unix/default/latest?Api-Token=<token>" \
-e ONEAGENT_INSTALLER_ARGS="--set-host-group=ContainerHosts --set-network-zone=us-east" \
dynatrace/oneagent
Why Every Flag Is Mandatory
A favorite topic on the Dynatrace Certified Associate exam is the technical rationale behind the required container execution flags:
--privileged: Grants the container full Linux kernel capabilities (CAP_SYS_ADMIN,CAP_SYS_PTRACE,CAP_NET_ADMIN). Without this flag, OneAgent cannot inspect process memory or attach dynamic hooking libraries.--net=host: Attaches the container directly to the host operating system's network stack. This allows OneAgent to discover all physical and virtual interfaces, capture TCP socket statistics, and measure round-trip times across host workloads.--pid=host: Places the container inside the host's root PID namespace. This allows OneAgent to discover and monitor all processes running on the bare-metal or virtual machine host, as well as processes inside sibling containers.--ipc=host: Shares the inter-process communication namespace, enabling shared memory inspection.-v /:/node_root: Mounts the host's entire root filesystem into the container at/node_root. This allows the containerized OneAgent to deploy/etc/ld.so.preloadentries, write kernel module drivers, and inject libraries into container mount namespaces.
Non-Privileged and Application-Only Monitoring
In specialized deployment environments where infrastructure teams cannot obtain root or administrative access—such as Platform-as-a-Service (PaaS) clouds, AWS Elastic Beanstalk, or strict regulatory silos—Full-Stack OneAgent host installation is prohibited.
For these use cases, Dynatrace supports Application-Only Monitoring:
- The OneAgent archive is extracted directly into the application's user-space directory.
- Instrumentation is invoked manually via language-specific startup parameters: for example, appending
-javaagent:/opt/dynatrace/oneagent/agent/bin/any/oneagentjava.jarto Java startup options, or requiring the Dynatrace loader in Node.js viaNODE_OPTIONS="--require /opt/dynatrace/oneagent/index.js". - Trade-offs: Application-Only monitoring captures PurePaths, database queries, and service metrics for the specific instrumented process. However, it does not collect host operating system metrics, cannot monitor CPU/memory of uninstrumented sibling processes, cannot inspect host network interfaces, and requires manual maintenance during application build and deployment pipelines.
An automation engineer is developing an unattended Ansible playbook to deploy Dynatrace OneAgent across hundreds of Linux application servers. The company's compliance policy dictates three mandatory constraints: the servers must be assigned to the Host Group "Production-Payments", outbound agent telemetry must traverse an internal corporate proxy at "http://proxy.corp.internal:3128", and the agent must operate strictly in Infrastructure Monitoring mode without injecting into running application runtimes. Which installer command line satisfies all three constraints?
A systems administrator has deployed Dynatrace OneAgent on a fleet of Windows Server 2022 virtual machines. Post-deployment, the enterprise architecture team reorganizes network zones and host groups, requiring the administrator to change the host group to "Finance-Core" and the network zone to "us-east-dc2" across these Windows hosts. The administrator wants to apply these configuration updates directly on each host using the command line without performing a complete reinstallation of the agent. Which procedure using oneagentctl must the administrator execute?
An operations team is deploying Dynatrace OneAgent onto bare-metal servers running a lightweight container-optimized Linux distribution where all services run in Docker containers. The team runs the official OneAgent container image using the command: docker run -d --restart=unless-stopped --net=host --pid=host --ipc=host --privileged -v /:/node_root dynatrace/oneagent. Why is the combination of --privileged, --net=host, --pid=host, and -v /:/node_root mandatory for this deployment model to function properly?