OneAgent configuration via command-line interface

OneAgent version 1.179

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

You'll find the oneagentctl tool in:

• Linux or AIX:
  /opt/dynatrace/oneagent/agent/tools
  You need root privileges.
• Windows:
  C:\Program Files (x86)\dynatrace\oneagent\agent\tools
  You need administrator privileges. If you try to run oneagentctl in a non-admin Windows console, Windows will display a User Account Control pop-up and fail.

oneagentctl command-line interface provides you with get parameters to check the state or value of a setting, and set parameters to change a setting. Note that you can use a number of set parameters in a single command. When you use the set parameters, you need to restart OneAgent service to apply changes. In some cases you'll also need to restart monitored applications.

Display help

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

• On Linux or AIX:
  ./oneagentctl --help
• On Windows:
  .\oneagentctl.exe --help

Display OneAgent version

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

• On Linux or AIX:
  ./oneagentctl --version
• On Windows:
  .\oneagentctl.exe --version

OneAgent communication

Change OneAgent communication settings

OneAgent version 1.185

• Use the --set-server parameter to set a OneAgent communication endpoint. Use the IP address or name. Depending on your deployment, it can be a Dynatrace Server, Dynatrace Managed Cluster, or ActiveGate.
• 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 token for internal authentication.
• Use the --set-tenant-token parameter to set the token, which is used to authenticate communication with the defined endpoint. Always use in combination with --set-tenant
• Use the --set-proxy parameter to set a proxy server.

Perform the following steps to adjust OneAgent connection settings:

1. Stop OneAgent.
   For OS-specific instructions, see Linux, Windows, or AIX.
2. Go to the directory with the oneagentctl tool.
3. Run the following command:

• On Linux or AIX:
  ./oneagentctl --set-server=https://my-server.com:443 --set-tenant=abc123456 --set-tenant-token=abcdefg123456790 --set-proxy=my-proxy.com
• On Windows:
  .\oneagentctl.exe --set-server=https://my-server.com:443 --set-tenant=abc123456 --set-tenant-token=abcdefg123456790 --set-proxy=my-proxy.com

4. Start OneAgent.
   For OS-specific instructions, see Linux, Windows, or AIX.
5. Restart all the applications monitored with deep code modules. 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.

Show current communication endpoints

OneAgent version 1.185

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.

• On Linux or AIX:
  ./oneagentctl --get-server
• On Windows:
  .\oneagentctl.exe --get-server

Show environment ID

OneAgent version 1.185

The Dynatrace environment ID you received with your activation email. Use the --get-tenant parameter to display the environment ID:

• On Linux or AIX:
  ./oneagentctl --get-tenant
• On Windows:
  .\oneagentctl.exe --get-tenant

Show tenant token

OneAgent version 1.185

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

• On Linux or AIX:
  ./oneagentctl --get-tenant-token
• On Windows:
  .\oneagentctl.exe --get-tenant-token

Show current proxy

OneAgent version 1.185

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

• On Linux or AIX:
  ./oneagentctl --get-proxy
• On Windows:
  .\oneagentctl.exe --get-proxy

Clear proxy configuration

OneAgent version 1.185

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

• On Linux or AIX:
  ./oneagentctl --set-proxy=
• On Windows:
  .\oneagentctl.exe --set-proxy= Restart OneAgent service to apply changes.

Check current port range

OneAgent version 1.185

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.

• On Linux or AIX:
  ./oneagentctl --get-watchdog-portrange
• On Windows:
  .\oneagentctl.exe --get-watchdog-portrange

Set a new port range

OneAgent version 1.185

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.

• On Linux or AIX:
  ./oneagentctl --set-watchdog-portrange=50000:50100
• On Windows:
  .\oneagentctl.exe --set-watchdog-portrange=50000:50100

Log monitoring

Check if Log Monitoring is enabled

OneAgent version 1.185

Log Monitoring is not supported on AIX.

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

• On Linux ./oneagentctl --get-app-log-content-access
• On Windows:
  .\oneagentctl.exe --get-app-log-content-access

Enable or disable Log Monitoring

OneAgent version 1.185

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

• On Linux: ./oneagentctl --set-app-log-content-access=true
• On Windows:
  .\oneagentctl.exe --set-app-log-content-access=true Restart OneAgent service to apply changes.

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. Most often such issues are related to deep monitoring or auto-update installations.

Check if access to system logs is enabled

OneAgent version 1.185

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

• On Linux or AIX:
  ./oneagentctl --get-system-logs-access-enabled
• On Windows:
  .\oneagentctl.exe --get-system-logs-access-enabled

Enable or disable access to system logs

OneAgent version 1.185

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

• On Linux or AIX:
  ./oneagentctl --set--system-logs-access-enabled=true
• On Windows:
  .\oneagentctl.exe --set-system-logs-access-enabled=true Restart OneAgent service to apply changes.

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

Host groups

OneAgent version 1.179

You can use the oneagentctl command-line interface to perform the following configuration actions for host groups.

Change host group assignment

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

To assign the host to MyHostGroup:

1. Stop OneAgent.
   For OS-specific instructions, see Linux, Windows, or AIX.

2. Go to the directory with the oneagentctl tool.

3. Run the following command:

   • On Linux or AIX:
     ./oneagentctl --set-host-group=MyHostGroup
   • On Windows:
     .\oneagentctl.exe --set-host-group=MyHostGroup

   Host group string requirements:

   • Can contain only alphanumeric characters, hyphens, underscores, and periods
   • Must not start with dt.
   • Maximum length is 100 characters

4. Start OneAgent.
   For OS-specific instructions, see Linux, Windows, or AIX.

5. Restart all the services monitored on the host.

Clear host group assignment

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

• On Linux or AIX:
  ./oneagentctl --set-host-group=
• On Windows:
  .\oneagentctl.exe --set-host-group=

Display host group assignment

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

• On Linux or AIX:
  ./oneagentctl --get-host-group
• On Windows:
  .\oneagentctl.exe --get-host-group

Cloud infrastructure monitoring

Use the cloud infrastructure monitoring mode, in place of full-stack monitoring mode. With this approach, you receive infrastructure-only health data, with no application or user performance data. For details, see Cloud infrastructure monitoring.

Check if cloud infrastructure monitoring mode is enabled

OneAgent version 1.187

Use the --get-infra-only parameter to check whether cloud infrastructure monitoring mode is enabled:

• On Linux or AIX:
  ./oneagentctl --get-infra-only
• On Windows:
  .\oneagentctl.exe --get-infra-only

Enable or disable cloud infrastructure monitoring mode

OneAgent version 1.187

Set the --set-infra-only parameter to true or false to enable or disable cloud infrastructure monitoring mode.

To enable cloud infrastructure monitoring mode:

1. Stop OneAgent.
   For OS-specific instructions, see Linux, Windows, or AIX.
2. Go to the directory with the oneagentctl tool.
3. Run the following command:
   • On Linux or AIX:
     ./oneagentctl --set-infra-only=true
   • On Windows:
     .\oneagentctl.exe --set-infra-only=true
4. Start OneAgent.
   For OS-specific instructions, see Linux, Windows, or AIX.
5. Restart all the services monitored on the host.

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.