OneAgent configuration via command-line interface

Use the oneagentctl command-line interface to perform some post-installation OneAgent configuration at the individual host level.

Location

The tool location depends on whether you customized the OneAgent installation using the <INSTALL_PATH> parameter:

Parameter types

The oneagentctl command accepts the get parameter to check the state or value of a setting, and the set parameter to change a setting. Note that you can use multiple set parameters in a single command.

OneAgent restart

When you use the set parameters, you need to restart OneAgent service to apply changes. You can use the --restart-service parameter with the command that triggers the restart automatically. In some cases you'll also need to restart monitored applications. You can also use the restart parameter on its own, without other parameters. See an example command below.

Display help

Use the --help parameter to display all supported parameters.

Display OneAgent version

Use the --version parameter to display the OneAgent version.

OneAgent communication

Set OneAgent communication settings

Use the --set-server parameter to set a OneAgent communication endpoint. Use the IP address or name, combined with the /communication suffix. Depending on your deployment, it can be a Dynatrace Server, Dynatrace Managed Cluster, or ActiveGate.

Run the following command to adjust OneAgent connection settings:

These parameters require restart of OneAgent, as well as restart of all the applications monitored with deep code modules. Add --restart-service to the command to restart OneAgent automatically (version 1.189+) or stop and start OneAgent process manually. For OS-specific instructions, see Linux, Windows, or AIX.

This command will immediately change the OS module connection endpoint, but the code modules won't be able to read the new setting until the next restart.

OneAgent and Dynatrace Cluster automatically maintain a working connection. If an endpoint detail changes, the cluster notifies OneAgent of the change and OneAgent automatically updates the endpoint you set using the --set-server to the new working value.

Show current communication endpoints

Use the --get-server parameter to display the endpoints that OneAgent is to send the data to. These can be Dynatrace Server, Dynatrace Managed Cluster or ActiveGate.

Starting with OneAgent version 1.207, endpoints are reported using a format in which endpoints of equal priority are grouped using braces ({...}) and sorted according to connection priority. An asterisk (*) indicates the endpoint to which OneAgent currently sends the data. Endpoints are separated by a semicolon (;). For example:

{https://endpoint1.com/communication;https:/10.0.0.0/communication;*https://endpoint3.com/communication}{https://endpoint4.com:9999/communication}

Set environment ID

Use the --set-tenant parameter to set an environment ID. By default, this is already set to the correct value. If you're selling Dynatrace-based services, use this option to set your customers' IDs from the pool of IDs you purchased from Dynatrace.

Always use in combination with --set-tenant-token, which defines the tenant token for internal authentication.

Show environment ID

The Dynatrace environment ID you received with your activation email.

Use the --get-tenant parameter to display the environment ID:

Set tenant token

Use the --set-tenant-token parameter to set the tenant token, which is used to authenticate communication with the defined endpoint. Always use in combination with --set-tenant.

Show tenant token

Use the --get-tenant-token parameter to display the currently defined token:

Set proxy configuration

Use the --set-proxy parameter to set a proxy server:

Clear proxy configuration

Use the --set-proxy parameter set to an empty value to clear proxy configuration:

Restart OneAgent service to apply changes.

Show current proxy

Use the --get-proxy parameter to display the currently defined proxy OneAgent connects through:

Exclude specific IPs from proxy

Use the --set-no-proxy parameter to exclude certain domains or IP addresses from using the proxy:

Show current no-proxy settings

Use the --get-no-proxy parameter to view the currently configured settings for domains and IP ranges excluded from using the proxy:

Check current port range

OneAgent consists of different processes that communicate via a TCP port with a watchdog. At startup, OneAgent watchdog attempts to open the first available port between port 50000 and 50100. In some cases you may need this port for your own applications that are started after OneAgent.

Use the --get-watchdog-portrange parameter to check the current port range defined for the watchdog.

Set a new port range

deprecated

Watchdog is a binary used for starting and monitoring OneAgent monitoring processes:

Use the --set-watchdog-portrange=arg parameter to change the watchdog listening port range to <arg>. The <arg> must contain two port numbers separated by a colon (:). For example 50000:50100. The maximum supported port range is from 1024 to 65535. The port range must cover at least 4 ports. The port number starting the range must be lower.

Automatic updates

For more information, see update OneAgent topics for Linux, Windows, and AIX.

Check if auto-update is enabled

Use the get-auto-update-enabled parameter to check whether OneAgent auto-update is enabled:

Enable or disable auto-update

Set the --set-auto-update-enabled parameter to true or false to disable or enable OneAgent auto-update:

Log monitoring

For more information, see Log Monitoring.

Check if Log Monitoring is enabled

Use the --get-app-log-content-access parameter to check whether Log Monitoring is enabled:

Enable or disable Log Monitoring

Set the --set-app-log-content-access parameter to true or false to disable or enable Log Monitoring:

Create support archive

OneAgent version 1.225+

If you don't have access to Dynatrace or you would like to script diagnostic data collection, you can use the oneagentctl command to collect a subset of the full OneAgent diagnostics data right on the host where OneAgent is installed. With the diagnostic data collected for OneAgent, you can:

The command requires the OneAgent service to be running.

To create a support archive with diagnostic data, run oneagentctl with the --create-support-archive parameter. By default, the support archive contains the data for a 7-day time frame and is created in the current working directory. Optionally, you can set a custom directory and timeframe with the directory and days parameters. Note that onegentctl won't create a directory; you must point it to an existing directory with a relative or absolute path. For example:

The command saves the archive as the support_archive_agent_YYYY-MM-DD_hhmmss.zip file. For example:

Creating support archive from last 30 days in C:\data\support-archive
Waiting 30s for archive request to be processed
Processing archive, waiting up to 15m 0s
Archive saved as C:\data\support-archive\support_archive_agent_2021-09-07_121619.zip

Contents of diagnostic data

All the collected diagnostic data is compressed into a support_archive_agent_YYYY-MM-DD_hhmmss.zip archive that includes the following subset of the full OneAgent diagnostics data:

Access to system logs for proactive support

OneAgent downloads specific system logs so that Dynatrace can diagnose issues that may be caused by conditions in your environment. The logs are also saved in the support archive. Most often such issues are related to deep monitoring or auto-update installations.

Check if access to system logs is enabled

Use the --get-system-logs-access-enabled parameter to check whether access to system logs is enabled:

Enable or disable access to system logs

Set the --set-system-logs-access-enabled parameter to true or false to disable or enable access to system logs:

Note that the --set-system-logs-access-enabled and --get-system-logs-access-enabled parameters refer to a self-diagnostics setting and are not related to Log Monitoring.

Host ID

Dynatrace assigns a unique ID to each host monitored in your environment. Host IDs can be used as parameters in Dynatrace API requests, for example Topology and Smartscape API - Hosts API. The host ID also constitutes the URL of the Host overview page, for example, https://environment.org/#newhosts/hostdetails;id=HOST-6E56EE455C84E232.

Display your host ID

To find a host ID, use the --get-host-id parameter. For example:

Define the host ID source

Available on all supported platforms for OneAgent version 1.223+. For OneAgent version 1.221 and earlier, this feature is supported only for Citrix Virtual Apps and Desktops.

It's particularly important to keep your host ID static in dynamic virtual environments where hosts are recreated on a daily basis.

To define the source for host ID generation, use --set-host-id-source and set it to one of the predefined values:

For example, to set the host ID source to ip-addresses and assign it to a namespace called test, run oneagentctl with the following parameter:

After you change the host ID source, you must restart all your monitored applications and then restart the OneAgent service to create the new host entity in your environment. You can use the --restart-service parameter with oneagentctl to restart OneAgent automatically or stop and start OneAgent process manually. For OS-specific instructions, see Linux, Windows, or AIX.

To check the host ID source, use the --get-host-id-source parameter:

For host ID source set to ip-addresses and the test namespace, the command will return the following result:

ip-addresses;namespace=test

Host groups

For an overview of how to use host groups, see Organize your environment using host groups.

Alternatively, to modify host group assignment centrally from the Dynatrace Cluster, you can use Remote configuration management (select the modify host group action).

Change host group assignment

Use the --set-host-group parameter to change the host group assignment.

To assign the host to MyHostGroup:

Using --set-host-group requires restart of OneAgent, as well as restart of all the monitored services. Add --restart-service to the command to restart OneAgent automatically (version 1.189+) or stop and start OneAgent process manually. For OS-specific instructions, see Linux, Windows, or AIX.

Changing the host group assignments results in recalculation of process group IDs, which impacts data aggregation. To read more about the impact of host group changes on process group detection, see Organize your environment using host groups.

Clear host group assignment

Use the --set-host-group parameter with an empty value to clear the host group assignment:

Display host group assignment

Use the --get-host-group parameter to display the current host group assignment:

Host tags and metadata

Within dynamic or large environments, manual host tagging can be impractical. For dynamic deployments that include frequently changing host instances and names (for example, AWS or MS Azure), you can use dedicated oneagentctl parameters to apply custom tags, names, and metadata to your hosts.

The oneagentctl methods listed below allow only for editing the metadata added using oneagentctl itself or previously using the configuration files. Tags and metadata added using Dynatrace, as well as retrieved from a monitored environment (for example the AWS tags) are not editable with oneagentctl and won't be displayed using --get-host-tags and --get-host-properties parameters.

Cloud metadata detection

By default, the oneagentos process automatically detects cloud environments such as AWS, Azure, and Google Compute Engine. It sends requests to the dedicated Metadata API located at the internal IP address 169.254.169.254. The OneAgent uses the retrieved metadata to provide additional context about the monitored resources within these environments.

Custom host name

Use the oneagentctl command-line tool with the --set-host-name parameter to override an automatically detected host name. A host name must not contain the <, >, &, CR (carriage return), or LF (line feed) characters. The maximum length is 256 characters.

To change the host name:

To revert to the auto-detected host name, set the --set-host-name parameter to an empty value, as in --set-host-name="". For example:

The change might not be reflected in the Dynatrace web UI for up to 6 minutes.

Using --set-host-name requires restart of OneAgent. Add --restart-service to the command to restart OneAgent automatically (version 1.189+) or stop and start the OneAgent process manually. For OS-specific instructions, see Linux, Windows, or AIX.

To show the host name:

Custom host metadata

Once configured, custom metadata is displayed as a set of properties at the bottom of the Properties and tags section of the host overview page. The property values must not contain an = character (unless used as a key-value delimiter) or whitespace characters. The maximum length is 256 characters, including the key-value delimiter. The key name must not start with a # character.

Alternatively, to modify host metadata centrally from the Dynatrace Cluster, you can use Remote configuration management (select the modify host properties action).

For versions earlier than 1.189, use a host metadata configuration file.

To add or change host properties, run the following command:

You can add or change more than one property in the same command.

To remove host properties, run the following command:

You can remove more than one property with a single command. If a property key that's passed in the command doesn't exist, a non-zero exit code will be returned, but all the existing properties passed in the command will be removed. After you remove host properties, they remain visible in Dynatrace for up to 7 hours.

To show all properties configured for the host, run the following command:

Custom host tags

After you configure custom host tags, they are displayed at the top of the Properties and tags section of the host overview page. A property value must not contain = (unless used as a key-value delimiter) or whitespace characters. The maximum length is 256 characters, including the key-value delimiter. A key name must not start with #.

Alternatively, to modify host tags centrally from the Dynatrace Cluster, you can use Remote configuration management (select the modify host tags action).

To add or change host tags, run the following command:

You can add or change more than one tag in the same command. It is allowed to define tags with the same key but different values.

To remove tags, run the following command:

You can remove more than one tag with the same command. If a tag passed in the command doesn't exist, a non-zero exit code is returned, but all the existing tags passed in the command are removed. After you remove tags, they remain visible in Dynatrace for up to 6 hours.

To show all tags configured for the host, run the following command:

Monitoring modes

Activates one of the OneAgent monitoring modes:

To enable a specific monitoring mode, set the --set-monitoring-mode parameter to one of the values:

For example:

--set-monitoring-mode=infra-only

Use Infrastructure Monitoring mode or Discovery mode in place of Full-Stack Monitoring mode. With this approach, you receive infrastructure health data, with no application or user performance data. For details, see Monitoring modes.

Check which monitoring mode is enabled

Use the --get-monitoring-mode parameter to check which monitoring mode is enabled:

The command returns one of the following:

Changing the Infrastructure Monitoring mode requires restart of OneAgent, as well as restart of all monitored services. Add --restart-service to the command to restart OneAgent automatically (version 1.189+) or stop and start the OneAgent process manually. For OS-specific instructions, see Linux, Windows, or AIX.

Automatic injection for Infrastructure Monitoring mode

OneAgent version 1.213

Automatic OneAgent injection is enabled by default in Infrastructure Monitoring mode. It's required to collect JMX/PMI metrics and to handle Application Security in Infrastructure Monitoring mode.

For more information, see Infrastructure and Discovery monitoring modes.

Check if auto-injection is enabled

Use the get-auto-injection-enabled parameter to check whether OneAgent auto-injection is enabled:

Enable or disable auto-injection

Set the --set-auto-injection-enabled parameter to true or false to enable or disable OneAgent auto-injection:

To enable auto-injections:

To disable auto-injections:

For more information, see Disable auto-injection.

Metric ingestion

Local metric ingestion is currently supported only on Windows and Linux.

You can use the oneagentctl command to check or change communication ports used for local metric ingestion using the OneAgent metric API, Scripting integration, Telegraf, or DynatraceStatsd. Changing the metric ingestion port requires restart of OneAgent. Add --restart-service to the command to restart OneAgent automatically.

See Metrics ingestion to learn more.

OneAgent API, scripting integration, and Telegraf

The default metric ingestion port is 14499. If necessary, you can use the oneagentctl command to check or change the port. Changing the metric ingestion port requires restart of OneAgent. Add --restart-service to the command to restart OneAgent automatically.

Check the ingestion port

Use the --get-extensions-ingest-port parameter to show the current local ingestion port, 14499 by default.

Set a custom ingestion port

Use the --set-extensions-ingest-port=<arg> parameter to set a custom local ingestion port.

Configure proxy

Configure your host proxy to allow localhost traffic going to the metric ingestion port, 14499 by default.

StatsD

OneAgent listener

The default DynatraceStatsD UDP listening port for the OneAgent listener is 18125. If necessary, you can use the oneagentctl command to check or change the metric ingestion port. Changing the port requires restart of OneAgent. Add --restart-service to the command to restart OneAgent automatically.

Check the ingestion port

Use the --get-extensions-statsd-port parameter to show the current DynatraceStatsd UDP listening port (default = 18125).

Set a custom ingestion port

Use the --set-extensions-statsd-port=<arg> parameter to set a custom DynatraceStatsd UDP listening port.

Remote StatsD

The default DynatraceStatsD UDP listening port for a remote listener is 18126.

To change the default 18126 listening port, modify the StatsdPort parameter in the ActiveGate extensionsuser.conf file:

StatsdPort=18126

Network zones

To learn about network zone naming rules and other reference information, see Network zones.

Alternatively, to modify network zone assignment centrally from the Dynatrace Cluster, you can use Remote configuration management (select the modify network zone action).

Set a network zone

Use the --set-network-zone parameter to instruct OneAgent to communicate via the specified network zone. The name of a network zone is a string of alphanumeric characters. You can also use hyphens (-), underscores (_), and a dot (.) as a seperator. The network zone name must not start with a dot. The length of the string is limited to 256 characters. Network zone names are not case-sensitive. Dynatrace stores these names in lowercase. For more information, see the section on network zone naming

Reset a network zone

You can reset the network zone setting by passing an empty network zone name:

Display network zone setting

Use the --get-network-zone parameter to display the current network zone configuration:

Passing configuration parameters during installation

You can pass the --set-* parameters at installation time. The configuration parameters are applied right before OneAgent service starts and there's no need to restart it to apply your configuration.

/bin/sh Dynatrace-OneAgent-Linux.sh –-set-host-group=test_group

Dynatrace-OneAgent-Windows.exe --set-host-group=test_group

Dynatrace-OneAgent-Windows.msi ADDITIONAL_CONFIGURATION="--set-host-group=test_group"

FIPS 140 cryptographic algorithms

OneAgent version 1.245+

OneAgent uses the FIPS mode to be compliant with the FIPS 140-3 computer security standard.

Check if FIPS 140 is enabled

Use the --get-fips-enabled to check if OneAgent uses FIPS 140 validated cryptographic algorithms.

Enable or disable FIPS 140

Set the --set-fips-enabled parameter to true or false to enable or disable the FIPS 140 validated cryptographic algorithms on OneAgent.

To enable FIPS mode:

To disable FIPS mode:

If you want to enable FIPS mode for application-only deployment, go to /paas/package/agent and delete dt_fips_disabled.flag.

cap_setuid for OS Agent

Check if cap_setuid for OS Agent is enabled

Use the get-osagent-cap-setuid-enabled parameter to check whether cap_setuid for OS Agent is enabled:

./oneagentctl --get-osagent-cap-setuid-enabled

Enable or disable cap_setuid for OS Agent

Set the --set-osagent-cap-setuid-enabled parameter to true or false to disable or enable cap_setuid for OS Agent:

./oneagentctl --set-osagent-cap-setuid-enabled=true