Redirect OneAgent to SaaS: oneagentctl without reinstalling

To redirect OneAgent to SaaS without reinstalling it, the Dynatrace documentation provides the oneagentctl command-line tool, which changes the communication endpoint of an agent that is already in place. For an SRE team moving from Managed to SaaS, it is the least intrusive way to switch a fleet, provided you know what really changes and how to check the result.

The problem is a familiar one. Hosts are running, applications are instrumented, and nobody wants to replay a full deployment across hundreds of machines just to change a destination. This guide complements the overall Managed to SaaS migration plan and the configuration replay described in Monaco Managed to SaaS: only the agents are covered here.

The content relies on the official oneagentctl documentation (SaaS and Managed versions of the page) and on the Deployment API reference. It applies to Dynatrace Managed (source) and Dynatrace SaaS (target).

Redirect OneAgent to SaaS: what to know first

According to the documentation, oneagentctl configures OneAgent at the level of an individual host. The --set-server parameter sets the communication endpoint: an address or name followed by the /communication suffix. The endpoint can be a Dynatrace server, a Managed cluster or an ActiveGate.

Three parameters go together when pointing an agent to another environment:

• --set-server: the new communication endpoint;
• --set-tenant: the environment ID. The documentation states that by default it is already correct; here it must change because the target environment is different. It is always used with --set-tenant-token;
• --set-tenant-token: the token that authenticates communication with the defined endpoint (not to be confused with an API token).

set parameters require a restart of the OneAgent service. The same page adds that these settings also require, in some cases, a restart of the monitored applications. The --restart-service parameter restarts the service in the same command. Several set parameters can be combined in one command.

Prerequisites

• A Dynatrace SaaS environment reachable from the hosts over outbound HTTPS (directly or through an ActiveGate).
• Root access on Linux or administrator access on Windows: the documentation requires it to run oneagentctl.
• A SaaS API token with the InstallerDownload scope to read the connection information (or, with an OAuth client or platform token, the fleet-management:oneagent.connection-info:read scope).
• An inventory of hosts per wave, as in the migration guide, and a test host for the first wave.

Step 1: get the SaaS connection information

The Deployment API reference describes the request GET https://{your-environment-id}.live.dynatrace.com/api/v1/deployment/installer/agent/connectioninfo. The response is a JSON object with four fields: communicationEndpoints (sorted by descending priority), formattedCommunicationEndpoints, tenantToken and tenantUUID. These are exactly the values to feed into oneagentctl.

The optional networkZone parameter returns the endpoints of a given network zone; version (format 1.221) asks for the best list format for that agent version. Treat the tenantToken as a secret: keep it in your vault, not in a Git repository.

Step 2: redirect a Linux host

On Linux, the tool is by default in /opt/dynatrace/oneagent/agent/tools (or <INSTALL_PATH>/agent/tools if the installation was customised). The redirection command looks like this, with example values:

cd /opt/dynatrace/oneagent/agent/tools
sudo ./oneagentctl --set-server="https://<env-id>.live.dynatrace.com/communication" \
    --set-tenant=<env-id> \
    --set-tenant-token=<tenant-token> \
    --restart-service

If hosts go through an ActiveGate, the communication endpoint is the ActiveGate one, with its port: the documentation gives the example https://<activegate-endpoint>:9999/communication. For several endpoints, the documentation says to separate them with a semicolon and quote the whole value. Port problems are covered in OneAgent and ActiveGate on port 9999.

On Windows the syntax is the same with .\oneagentctl.exe, run from an administrator console; the tool is in %PROGRAMFILES%\dynatrace\oneagent\agent\tools by default. Without administrator rights, the documentation notes that Windows shows a User Account Control prompt and the command fails.

Step 3: restart applications if needed

Restarting the service is not always enough. The documentation mentions that these parameters require, in some cases, a restart of the monitored applications. For an already injected process, plan that restart with the application team, outside peak hours. It affects MTTR: an application that was not restarted may still be missing from the target environment while its host is visible.

How to check that it works

The get parameters read the current state. They change nothing and suit an automated check after each wave.

1. --get-server shows the endpoints OneAgent sends data to. Since OneAgent 1.207, the output groups endpoints of equal priority in braces, sorted by connection priority, and an asterisk marks the endpoint currently used.
2. --get-tenant shows the environment ID: it must match the SaaS environment.
3. --get-tenant-token shows the defined token. Do not paste this output into a ticket or a shared log.
4. In the SaaS environment, the host must appear; compare the number of visible hosts with the wave inventory (a measurable success criterion, for example 100% within 30 minutes).

For CI or a deployment tool, these three reads make a simple test: a host whose server or tenant does not match the target is a host that has not been migrated.

Best practices and common pitfalls

• Test first: redirect a non-critical host, check, then widen by waves with a rollback plan (the same command with the Managed values).
• One environment per agent: --set-server replaces the communication endpoint; do not count on dual reporting to compare. Keep control hosts on Managed.
• Secrets: the tenant token travels through your scripts. Inject it from a vault.
• Firewall: open the flows to SaaS or the ActiveGate before the wave, not during it.
• Entity IDs: to be confirmed on the test host, since anything that hard-codes an ID (dashboards, scripts) must be reviewed. The oneagentctl page does not detail this point.
• OpenTelemetry: OTLP exporters and Collectors target the environment, not OneAgent; their URLs and tokens change separately (see OneAgent and OpenTelemetry: avoiding duplicates).

For large-scale automation, a clean reinstall through your deployment tool remains an option, and the choice depends on your context; deployment basics are described in OneAgent on Linux.

Frequently asked questions

Do I need to reinstall OneAgent to go from Managed to SaaS?

Not necessarily: oneagentctl changes the communication endpoint, environment and token of an installed agent. Check the agent version and test on one host before generalising.

Where do I find the tenant token and the communication URL?

In the response of the connectioninfo Deployment API: tenantToken, tenantUUID and the communicationEndpoints list. It requires the InstallerDownload scope.

Do applications need a restart?

The documentation says set parameters require a restart of the OneAgent service and, in some cases, of the monitored applications. Plan for it in the wave calendar.

Conclusion

To redirect OneAgent to SaaS, one command is enough: --set-server, --set-tenant, --set-tenant-token, then a restart. The real work is around it: fetching the right values, moving by waves, checking with the get parameters and keeping a rollback.

span.observer is an independent community blog, not affiliated with Dynatrace LLC. Dynatrace is a trademark of its owner. Parameters and versions change: check them in the official oneagentctl and Deployment API documentation.

Originally published on span.observer. French version: https://span.observer/fr/rediriger-oneagent-vers-saas/.