Install OneAgent Linux: deploying on Linux hosts in a Managed environment

Deploying OneAgent on a handful of Linux servers is trivial. Deploying it cleanly on several hundred hosts spread across data centres, segmented network zones and different application teams is another story. The tickets that come in after a sloppy rollout all look the same: hosts in the wrong group, agents that cannot reach the cluster, unexpected licence consumption because everything was installed in Full-Stack by default. To install OneAgent, Linux estates of that size need a method, not a one-liner.

In a Dynatrace Managed environment, these problems take on a particular dimension. The cluster is on your premises: your DNS, your certificates, your firewall rules and your proxies decide whether the agent reaches its communication endpoints. The host unit quota is set by your licence and shared between environments, and the slightest host group naming mistake then spreads into alerting rules, maintenance windows and permissions.

This article offers a repeatable method to install OneAgent on Linux in a Managed context: preparation, download through the environment API, parameterised installation, verification and post-installation adjustments with oneagentctl.

Understanding the communication path in Managed

A OneAgent does not send its data « to Dynatrace » in the abstract: it contacts a list of communication endpoints that the cluster gives it. In Managed, three scenarios dominate:

• Direct connection to the cluster nodes: the agent talks directly to the Managed nodes, over HTTPS on port 443; port 8443 is still used for OneAgent data on clusters older than version 1.166 or upgraded from them.
• Through an Environment ActiveGate: recommended as soon as a network zone is isolated. The ActiveGate listens on port 9999 by default and routes traffic to the cluster.
• Through a Cluster ActiveGate: useful for agents outside your internal network that must reach the cluster from outside.

Network zones let you tell the agent which ActiveGates to prefer. Defining them before the rollout stops an agent in a DMZ from trying to reach nodes it will never see.

Choosing the monitoring mode

Mode	What is collected	Use case
Full-Stack	Infrastructure, processes, injection into applications (distributed traces)	Critical application servers
Infrastructure	Host metrics, processes, network, logs depending on configuration	Databases, infrastructure servers, lower licence consumption
Discovery	Inventory and minimal visibility	Broad, low-cost mapping

The exact availability of each mode and its weight in host units depend on your licensing model and your Managed version: check them in the CMC before setting your standard.

Prerequisites

• Root or sudo access on the target hosts.
• An environment API token with permission to download OneAgent installers (PaaS integration – Installer download scope, InstallerDownload).
• The environment ID, visible in the URL https://{your-domain}/e/{environment-id}.
• A naming convention for host groups (for example {application}_{environment}) and the list of network zones.
• Enough disk space: on x86-64, about 1.3 GB for the installation under /opt/dynatrace/oneagent, and close to 12 GB in total once logs (/var/log/dynatrace/oneagent), dumps, persistence and updates are counted; at least 256 MB of free memory during installation.
• The certificate of the authority that signed the cluster’s certificate, if you use an internal PKI.

Step-by-step tutorial: install OneAgent Linux

Step 1 — Check connectivity to the cluster

Before any installation, confirm that the host reaches the environment’s entry point or the ActiveGate for its zone:

curl -sS -o /dev/null -w "%{http_code}\n" https://{your-domain}/e/{environment-id}/api/v1/time \
  -H "Authorization: Api-Token {token}"

# If the host goes through an Environment ActiveGate
curl -k -sS -o /dev/null -w "%{http_code}\n" https://{activegate-host}:9999/rest/health

The /api/v1/time call requires the DataExport scope: with a download-only token, expect a 401 or 403, which still proves that the network and TLS work. A 200 also validates the token; a timeout points to the firewall or the proxy.

Step 2 — Download the installer through the API

curl -sS -o /tmp/Dynatrace-OneAgent-Linux.sh \
  "https://{your-domain}/e/{environment-id}/api/v1/deployment/installer/agent/unix/default/latest?arch=x86" \
  -H "Authorization: Api-Token {token}"

ls -lh /tmp/Dynatrace-OneAgent-Linux.sh

The downloaded file already contains the environment ID, the agent token and the initial list of communication endpoints. Treat it as a sensitive file: do not put it in a public repository or an open share.

Step 3 — Check the installer’s integrity

The installer is signed. If your security policy requires it, fetch the root certificate supplied by Dynatrace and verify the signature with openssl following the procedure in the documentation for your version. Otherwise, at least check the size and that the file starts with a shebang:

head -c 64 /tmp/Dynatrace-OneAgent-Linux.sh; echo

Step 4 — Install with your standard parameters

sudo /bin/sh /tmp/Dynatrace-OneAgent-Linux.sh \
  --set-monitoring-mode=fullstack \
  --set-host-group={application}_{environment} \
  --set-network-zone={network-zone} \
  --set-app-log-content-access=true

For an infrastructure host, change the value to --set-monitoring-mode=infra-only. If hosts go out through a proxy, add --set-proxy={proxy-host}:{port}.

Step 5 — Check the service

systemctl status oneagent
journalctl -u oneagent --since "15 min ago"
ls /var/log/dynatrace/oneagent/

The service must be active (running). Application processes that were already running must be restarted for Full-Stack injection to take effect: schedule this restart with the teams concerned.

Step 6 — Adjust the configuration with oneagentctl

oneagentctl lets you view and change the configuration without reinstalling:

cd /opt/dynatrace/oneagent/agent/tools

sudo ./oneagentctl --get-host-group
sudo ./oneagentctl --get-server
sudo ./oneagentctl --get-network-zone

# Fix a wrong host group (service restart required)
sudo ./oneagentctl --set-host-group={new-group} --restart-service

Be careful: changing the host group changes the host’s logical identity in Dynatrace (rules, alerts, tags). Preferably do it before going into production.

Step 7 — Check in the environment

In the environment UI, open the hosts view and filter on the group you just used. You can also query the API:

curl -sS -G "https://{your-domain}/e/{environment-id}/api/v2/entities" \
  --data-urlencode 'entitySelector=type(HOST),fromRelationships.isInstanceOf(type(HOST_GROUP),entityName("{application}_{environment}"))' \
  -H "Authorization: Api-Token {token}"

The token used here must have the entities.read scope. The --data-urlencode option takes care of encoding the selector.

Automating the rollout

Beyond a few hosts, script the procedure in your configuration management tool (Ansible, Puppet, Salt…). A few principles:

1. Store the token in a vault (Vault, Ansible secrets) and never in plain text in an inventory.
2. Host the installer in an internal repository if hosts have no direct access to the environment API: download it once, then distribute it.
3. Derive the host group and network zone from inventory variables to avoid manual entry.
4. Make the task idempotent: if systemctl is-active oneagent returns active, do not reinstall.

Best practices

• Define network zones and ActiveGates before deploying, not after.
• Use tokens dedicated to deployment, with minimal scope, and rotate them regularly.
• Fix a host group convention and document it: it drives alerting profiles and maintenance windows, as well as tagging and management zones.
• Keep Full-Stack for hosts that need it and monitor host unit consumption in the CMC.
• Leave automatic agent updates enabled at environment level, or schedule them explicitly if your change policy requires it (see planning cluster and OneAgent updates).
• Keep the installation logs (under /var/log/dynatrace/oneagent) for analysis if something fails.

Frequently asked questions

Do applications need restarting after installation?

Yes for Full-Stack: processes that were already running must be restarted for injection to take effect. Check first that the oneagent service shows active (running).

How do I fix a host group without reinstalling?

With oneagentctl --set-host-group={new-group} --restart-service. The change alters the host’s logical identity (rules, alerts, tags), so preferably do it before going into production.

What should I check if the agent cannot reach the cluster?

Test the network path with curl against the environment API or the ActiveGate’s /rest/health: a 401 or 403 means a wrong token or one lacking the required scope, a timeout points to a firewall or proxy. Then check the communication endpoints with oneagentctl --get-server.

Conclusion

On Linux, installing OneAgent takes one command, but success in a Managed environment depends on what comes before it: a validated network path, consistent network zones, a token with limited scope and a shared host group convention. By combining download through the environment API, explicit installation parameters and oneagentctl for adjustments, you get a rollout that is repeatable, auditable and easy to automate at scale.

span.observer is an independent community blog, not affiliated with Dynatrace LLC. Dynatrace is a trademark of Dynatrace LLC. Always check values (ports, versions, sizes) in the official documentation for your version of Managed.

---

Originally published on span.observer. French version: https://span.observer/fr/oneagent-linux-managed/.