Customize OneAgent installation on Linux

The Linux installer can be used with command line parameters when you can't use the default settings. Note that all parameters listed below are optional.

Passing installation parameters

To pass the parameters, append them to the installer command and separate them with spaces.

For example:

Dynatrace-OneAgent-Linux.sh --set-host-group=my_host_group --set-monitoring-mode=infra-only

Removed installation parameters

Convert to the newer --set-param=<value> parameters now. The equivalent PARAM=<value> parameters are not supported by the OneAgent installer starting with version 1.213.

If you mix equivalent PARAM=<value> and --set-param=<value> settings, the --set-param=<value> setting overrides the PARAM=<value> setting.

Installation path

Default value: /opt/dynatrace/oneagent

Prerequisite: Using this parameter when SELinux is enabled requires the semanage utility to be available on your system.

The INSTALL_PATH parameter allows installation to a different directory. For example:

/bin/sh Dynatrace-OneAgent-AIX-1.0.0.sh INSTALL_PATH=/data/dynatrace/agent

The installer creates the symbolic link /opt/dynatrace/oneagent > /data/dynatrace/agent and the OneAgent installation files are placed in the specified directory (in this example, /data/dynatrace/agent). Note that this symbolic link needs to be removed manually after OneAgent is uninstalled.

Custom directory requirements

Your custom installation directory must meet the following requirements:

Log path

Default value: /var/log/dynatrace/oneagent

Prerequisite: Using this parameter when SELinux is enabled requires the semanage utility to be available on your system.

The LOG_PATH parameter allows you to customize your OneAgent log directory. For example:

/bin/sh Dynatrace-OneAgent-Linux-1.0.0.sh LOG_PATH=/data/dynatrace/logs

Custom directory requirements

Your custom log path must meet the following requirements:

Changing location

If you use the parameter to change the location for an already installed OneAgent:

Data storage

OneAgent version 1.199

Default value: /var/lib/dynatrace/oneagent/datastorage

Prerequisite: Using this parameter when SELinux is enabled requires the semanage utility to be available on your system.

The DATA_STORAGE parameter allows you to define a directory dedicated to storing large runtime data produced by OneAgent in full-stack monitoring mode, such as crash reports or memory dumps. For example:

/bin/sh Dynatrace-OneAgent-Linux.sh DATA_STORAGE=/data/dynatrace/runtime

Communication endpoint

Default value: environment specific

The address of the OneAgent communication endpoint, which is a Dynatrace component that OneAgent sends data to. Depending on your deployment, it can be a Dynatrace Cluster or ActiveGate. If you install OneAgent using the Dynatrace Deploy page, this is already set to the correct value. To change it, use the IP address or a name. Add the port number following a colon.

To set the communication endpoint, pass it as a parameter value:

--set-server=https://100.20.10.1:443

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.

To change the endpoint after installation, use --set-server in the OneAgent command-line interface.

Environment ID

Default value: environment specific

The Dynatrace environment ID you received with your activation email. If you install OneAgent using the Dynatrace Deploy page, 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.

To set the environment ID, pass it as a parameter value:

--set-tenant=mySampleEnv

To change the tenant after installation, use --set-tenant in the OneAgent command-line interface.

Token

Default value: environment specific

The tenant token that is used for authentication when OneAgent connects to the communication endpoint to send data. If you install OneAgent using the Dynatrace Deploy page, this is already set to the correct value.

To set a token, pass it as a parameter value:

--set-tenant-token=abcdefghij123456

See Access tokens to learn how to obtain a token.

To change the tenant token after installation, use --set-tenant-token in the OneAgent command-line interface.

Network zones

Default value: unset

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

Use the --set-network-zone parameter to instruct OneAgent to communicate via the specified network zone:

--set-network-zone=your.network.zone

To change or clear the network zone assignment after installation, use Remote configuration management (select the modify network zone action).

Alternatively, you can use --set-network-zone on the OneAgent command-line interface.

Proxy

Default value: unset

The address of the proxy server. Use the IP address or a name, and add the port number following a colon. For an authenticating proxy you can specify a username and password like this username:password@172.1.1.128:8080 where both username and password need to be URL encoded.

To set a proxy, pass it as a parameter value:

--set-proxy=172.1.1.128:8080

Dynatrace also supports IPv6 addresses.

To change or clear the proxy address after installation, use --set-proxy in the OneAgent command-line interface.

Port range

Default value: 50000:50100

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. For example:

--set-watchdog-portrange=50000:50100

To change port range after installation, use --set-watchdog-portrange in the OneAgent command-line interface.

Auto-update

Use the --set-auto-update-enabled=<arg> to enable or disable OneAgent auto-update. For example:

--set-auto-update-enabled=true

After you set the parameter to false, you won't be able to control OneAgent automatic updates using the Dynatrace web UI at Settings > Updates > OneAgent updates.

Host group

Default value: unset

The name of a group you want to assign the host to. For details, see Organize your environment using host groups. Host group string requirements:

To assign a host to the host group, pass the host group name as a parameter value:

--set-host-group=My.HostGroup_123-456

To remove the host from a group, you need to uninstall OneAgent or pass an empty value --set-host-group="" when running a OneAgent update. You can't remove the host from a group using the HOST_GROUP parameter when updating OneAgent.

To change or clear the host group assignment after installation, use Remote configuration management (select the modify host group action).

Alternatively, you can use --set-host-group in the OneAgent command-line interface.

Monitoring mode

Default value: fullstack

Activates one of the OneAgent monitoring modes:

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

For example:

--set-monitoring-mode=infra-only

To change the monitoring mode after installation, use --set-monitoring-mode in the OneAgent command-line interface or set it using the Host settings page.

Custom host name

Default value: unset

Use the --set-host-name to override an automatically detected host name. The host name value must not contain the <, >, &, CR (carriage return), and LF (line feed) characters and the maximum length is 256 characters.

To set the host name:

--set-host-name=myhostname

To change the host name after installation, use --set-host-name in the OneAgent command-line interface.

Custom host metadata

Default value: unset

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 the = (except key-value delimiter) and whitespace characters. The maximum length is 256 characters including the key-value delimiter.

To add or change host properties:

--set-host-property=AppName --set-host-property=Environment=Dev

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

To change the host metadata after installation, use Remote configuration management (select modify host properties action).

Alternatively, you can use --set-host-property in the OneAgent command-line interface.

Custom host tags

Default value: unset

Once configured, the tags are displayed at the top of the Properties and tags section of the host overview page. The property values must not contain the = (except key-value delimiter) and whitespace characters. The maximum length is 256 characters including the key-value delimiter.

To add or change host tags:

--set-host-tag=TestHost --set-host-tag=role=fallback --set-host-tag=Gdansk

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 change the host tags after installation, use Remote configuration management (select the modify host tags action).

Alternatively, you can use --set-host-tag in the OneAgent command-line interface.

Host ID source

Default value: auto

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 you 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 the OneAgent installer with the following parameter:

--set-host-id-source="ip-addresses;namespace=test"

To install OneAgent on a Citrix host, set the host ID source to mac-addresses:

--set-host-id-source="mac-addresses;namespace=test"

Custom directory requirements

Your custom data storage directory must meet the following requirements:

Changing location

If you use the parameter to change the location for an already installed OneAgent:

Access to system logs

Default value: true

OneAgent downloads Linux system logs for the purpose of diagnosing issues that may be caused by conditions in your environment. For details, see System logs downloaded by OneAgent.

To disable access to logs:

--set-system-logs-access-enabled=false

To enable access to logs:

--set-system-logs-access-enabled=true

If you need to change this access after installation, use the OneAgent command-line interface:

Note that this is a self-diagnostics setting and is not related to Log Monitoring.

Log Monitoring

Default value: true

When set to true, allows OneAgent to access log files for the purpose of Log Monitoring. Accepted values are (true, false) or (1, 0). This option can alternatively be enabled/disabled through the Web UI.

For example: --set-app-log-content-access=true

If you need to enable or disable Log Monitoring after installation, use -set-app-log-content-access in OneAgent command-line interface.

Automatic injection

Default value: true

You can set the --set-auto-injection-enabled=<arg> parameter to true or false to disable or enable OneAgent auto-injection.

For more information, see Automatic injection.

Local metric ingestion

Default value: 14449

You can use the --set-extensions-ingest-port=<arg> parameter to change the default communication port used for local metric ingestion. The port is used by OneAgent REST API, Scripting integration (dynatrace_ingest), and Telegraf.

For more information, see Metric ingestion.

StatsD metric ingest

Default value: 18125

You can use the --set-extensions-statsd-port=<arg> parameter to change the default DynatraceStatsD UDP listening port.

For more information, see Metric ingestion.

Non-privileged mode

NON_ROOT_MODE

Default value: 1 (OneAgent version 1.193+. For earlier versions 0)

When you install OneAgent in non-privileged mode, you only need to grant elevated privileges to OneAgent during the installation. Elevated privileges are dropped as soon as OneAgent is deployed.

Since version 1.193, OneAgent is installed in non-privileged mode by default. Existing installations aren't switched to non-privileged mode.

To switch an installed OneAgent to non-privileged mode, you need to manually append the NON_ROOT_MODE=1 parameter to the installation command. Example: sudo /bin/sh Dynatrace-Agent-Linux-1.0.0.sh NON_ROOT_MODE=1
To switch the installer back to the default mode for consecutive updates, run it with NON_ROOT_MODE=0.

Note that non-privileged mode requires Linux kernel capabilities that are available in these versions:

DISABLE_ROOT_FALLBACK

Default value: 0

Used in conjunction with the NON_ROOT_MODE parameter to block the superuser permission level for OneAgent run in the non-privileged mode. The root privileges are required for automatic updates and selected operations on kernel versions between 2.6.26 and 4.3, that is versions without the support for Linux ambient capabilities.

sudo /bin/sh Dynatrace-OneAgent-Linux-1.0.0.sh NON_ROOT_MODE=1 DISABLE_ROOT_FALLBACK=1

To switch the installer back to use the superuser permission level for subsequent updates, run it with DISABLE_ROOT_FALLBACK=0.

For more information, see the permission requirements for OneAgent installation and operation on Linux.

Specifying non-privileged user and group

USER

Default value: dtuser

Specifies the name of the non-privileged user, which is used by unprivileged OneAgent processes. Unprivileged processes are those that don't need root privileges. These processes on Linux are called Network OneAgent and Plugin OneAgent.

In either case, the Dynatrace installer checks whether a required user (dtuser or the user specified by the USER parameter) already exists in the system.

USER string requirements:

GROUP

Default value: dtuser

Can only be used in conjunction with the USER parameter and is used to specify the primary group for the user passed via the USER parameter. If you don't specify the GROUP parameter, the installer assumes it's the same as the USER, for both existing and non-existing users. If you specify the group using the GROUP parameter, and a user doesn't exist, the installer creates the user and assigns it to the specified group. You also use the GROUP parameter to specify an unprivileged user that belongs to a specific group, with a different name than the user name. To harden your system security, we strongly recommend use of a dedicated user group to run OneAgent processes.

GROUP string requirements: