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.

For example:
Dynatrace-OneAgent-Linux.sh --set-app-log-content-access=true

Communication endpoint

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 Server, Dynatrace Managed 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 (recommended since OneAgent version 1.185)
or
SERVER=https://100.20.10.1:443

If you need to change the server address after installation, use --set-server in the OneAgent command-line interface.

Environment ID

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=abcdefghij (recommended since OneAgent version 1.185)
or
TENANT=abcdefghij

If you need to change the tenant after installation, use --set-tenant in the OneAgent command-line interface.

Token

The internal 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.

You can retrieve the tenant token from the following REST endpoint. In return, you will get a JSON object that includes the token.

https://<ENVIRONMENTID>.live.dynatrace.com/api/v1/deployment/installer/agent/connectioninfo?Api-Token=<API_TOKEN>

Be sure to replace <ENVIRONMENTID> and <API_TOKEN> with the proper values.

To set a token, pass is as a parameter value:
--set-tenant-token=abcdefghij123456 (recommended since version 1.185)
or
TENANT_TOKEN=abcdefghij123456

If you need to change the tenant token after installation, use --set-tenant-token in the OneAgent command-line interface.

Proxy

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 (recommended since version 1.185)
or
PROXY=172.1.1.128:8080

Dynatrace also supports IPv6 addresses.

If you need to change the proxy address after installation, use --set-proxy in the OneAgent command-line interface.

Host group

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:

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

To assign a host to the host group, pass the host group name as a parameter value:
–-set-host-group=My.HostGroup_123-456 (recommended since OneAgent version 1.185)
or
HOST_GROUP=My.HostGroup_123-456

To remove the host from a group, you must 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. The –-set-host-group parameter is available since OneAgent version 1.177. For more information, see OneAgent configuration via command-line interface.

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

Cloud infrastructure monitoring mode

Activates 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.

To enable cloud infrastructure monitoring set the parameter to:
--set-infra-only=true (recommended since version 1.187)
or
INFRA_ONLY=1

To disable cloud infrastructure monitoring set the parameter to:
--set-infra-only=false (recommended since version 1.187)
or
INFRA_ONLY=0

If you need to change, enable, or disable cloud infrastructure monitoring mode after installation, use --set-infra-only in the OneAgent command-line interface or set it using the Host settings page.

Installation path

INSTALL_PATH parameter allows installation to a different directory. For example on Linux: /bin/sh Dynatrace-OneAgent-Linux.sh INSTALL_PATH=/data/dynatrace/. When this parameter is used, the installer creates the symbolic link opt/dynatrace/oneagent -> /data/dynatrace and all OneAgent files are placed in the specified directory (in this example, /data/dynatrace). Note that this symbolic link needs to be removed manually, once OneAgent has been uninstalled. Using this parameter on Linux when SELinux is enabled requires the semanage binary to be available on your system.

Log Monitoring

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 (recommended since version 1.185)
or
APP_LOG_CONTENT_ACCESS=true

Access to system logs

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.

--set-system-logs-access-enabled=false disables access to logs (recommended since version 1.185)
--set-system-logs-access-enabled=true enables access to logs (recommended since version 1.185) or
DISABLE_SYSTEM_LOGS_ACCESS=1 disables access to logs DISABLE_SYSTEM_LOGS_ACCESS=0 enables access to logs

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.

Non-privileged mode

• NON_ROOT_MODE OneAgent version 1.141+ can be installed in non-privileged mode. This is the only time you need to grant elevated privileges to OneAgent. Elevated privileges are dropped as soon as OneAgent is deployed.

  To install OneAgent in 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 available in the versions:

  • Linux kernal version 2.6.26+ for OneAgent installation without root privileges.
  • Linuz kernal version 4.3+ (recommended systemd version 221+) for OneAgent automatic updates and full operation without root privileges.
    For more information, see Linux non-privileged mode

• DISABLE_ROOT_FALLBACK
  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-Agent-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 consecutive updates, run it with DISABLE_ROOT_FALLBACK=0.

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

  Notes:

  • The uninstall process doesn't delete the unprivileged user from the system (whether or not it's dtuser or specified by the USER parameter).
  • The unprivileged username is preserved during upgrades, unless a new username is specified during upgrade.

Specifying non-priviliged user and group

• USER
  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.

  • The default behavior is that the Dynatrace installer uses dtuser for the name of the unprivileged user.
  • If the USER=<username> parameter is specified, the installer uses <username> as the name of the unprivileged user.

  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.

  • If a user and a group with the same name exist and this user has that group set as its primary one, the user is used to start the OneAgent network and plugin modules.
  • If a user doesn't exist, the Dynatrace installer creates this user and group and later starts these unprivileged processes with this new user.
  • If a user exists in the system but doesn't have a group with the same name set as its primary one, the installation is aborted—to use a group with a different name, you must use the GROUP parameter.

  USER string requirements:

  • Can contain only alphanumeric characters

  • Minimum length is 3 characters

  • Maximum length is 32 characters

  • Can't be a user identifier string

  • GROUP
    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:

  • Can contain only alphanumeric characters
  • Minimum length is 3 characters
  • Maximum length is 32 characters
  • Can't be a group identifier string