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-infra-only=true
New installation parameters
If you are installing or updating a suitable OneAgent version (see Minimum OneAgent version
), we recommend that you use the new --set-param=<value>
parameters listed below. The equivalent PARAM=<value>
parameters continue to work for the time being, but they will be removed from future releases.
Old PARAM=<value> parameter |
New --set-param=<value> parameter |
Minimum OneAgent version |
---|---|---|
SERVER |
--set-server |
1.185 |
TENANT |
--set-tenant |
1.185 |
TENANT_TOKEN |
--set-tenant-token |
1.185 |
PROXY |
--set-proxy |
1.185 |
HOST_GROUP |
--set-host-group |
1.185 |
APP_LOG_CONTENT_ACCESS |
--set-app-log-content-access |
1.185 |
DISABLE_SYSTEM_LOGS_ACCESS |
--set-system-logs-access-enabled |
1.185 |
INFRA_ONLY |
--set-infra-only |
1.187 |
If you mix equivalent PARAM=<value>
and --set-param=<value>
settings, the --set-param=<value>
setting overrides the PARAM=<value>
setting.
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
(recommended since OneAgent version 1.185)
or
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.
If you need 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=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
Default value: environment specific
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.
To set a token, pass it as a parameter value:
--set-tenant-token=abcdefghij123456
(recommended since version 1.185)
or
TENANT_TOKEN=abcdefghij123456
See Access tokens to learn how to obtain a token.
If you need 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
If you need to change the network zone assignment after installation, use --set-network-zone
in 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
(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.
Port range
OneAgent version 1.185
Default value: 50000:50100
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
If you need to change port range after installation, use --set-watchdog-portrange
in OneAgent command-line interface.
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:
- 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.
Infrastructure monitoring mode
Default value: false
Activates 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 Infrastructure monitoring.
To enable Infrastructure monitoring mode, set the parameter to:
--set-infra-only=true
(recommended since version 1.187)
or
INFRA_ONLY=1
To disable Infrastructure monitoring mode, 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 Infrastructure monitoring mode after installation, use --set-infra-only
in OneAgent command-line interface or set it using the Host settings page.
Custom host name
OneAgent version 1.189
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
For versions earlier than 1.189, use a host name configuration file.
If you need to change the host name after installation, use --set-host-name
in OneAgent command-line interface.
Custom host metadata
OneAgent version 1.189
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.
For versions earlier than 1.189, use a host metadata configuration file.
If you need to change the host metadata after installation, use --set-host-property
OneAgent command-line interface.
Custom host tags
OneAgent version 1.189
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.
For versions earlier than 1.189, use a host metadata configuration file.
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.
If you need to change the host tags after installation, use --set-host-tag
in OneAgent command-line interface.
Host ID source
OneAgent version 1.193
Default value: auto
This feature is currently 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:
auto
let Dynatrace generate the host ID automaticallyip-addresses
generate host ID based on the host IP addressip-addresses;namespace=<namespace>
if you monitor multiple environments, you can split the hosts with identical IPs using a different namespace for each environment. The namespace can contain only alphanumeric characters, hyphens, underscores, and periods; the maximum length is 256 characters.
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"
Log Monitoring
Default value: true
(OneAgent version 1.187+. For earlier versions false
)
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
If you need to enable or disable Log Monitoring after installation, use -set-app-log-content-access
in OneAgent command-line interface.
Local metric ingestion
OneAgent version 1.201
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
OneAgent version 1.201
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.
Installation path
Default value: /opt/dynatrace/oneagent
Prerequisite: Using this parameter when SELinux is enabled requires the semanage binary to be available on your system.
INSTALL_PATH
parameter allows installation to a different directory.
For example:
/bin/sh Dynatrace-OneAgent-Linux.sh INSTALL_PATH=/data/dynatrace/agent
.
When this parameter is used, 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 if you uninstall OneAgent.
For security reasons, the directory must be dedicated to OneAgent purposes only. No other software can have access to it.
Note: The INSTALL_PATH
parameter doesn't control the OneAgent log and configuration files directories that you can't modify. You can only modify the default data storage directory (/var/lib/dynatrace/oneagent/datastorage
). See Data storage.
Data storage
OneAgent version 1.199
Default value: /var/lib/dynatrace/oneagent/datastorage
Prerequisite: Using this parameter when SELinux is enabled requires the semanage binary to be available on your system.
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
The value of the parameter is an absolute path and it must not point to the filesystem root directory.
For security reasons, the directory must be dedicated to OneAgent purposes only. No other software can have access to it.
Note: After you set or change the DATA_STORAGE
parameter, you must restart deep-monitored processes, so that OneAgents monitoring them can pick up the new path to store runtime data. Otherwise, memory dumps and other runtime data won't be saved. You will be notified to restart a corresponding process on the Process overview page.
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.
--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
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:
- Linux kernel version 2.6.26+ for OneAgent installation without root privileges.
- Linux kernel 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
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.
Notes:
- The uninstall process doesn't delete the unprivileged user from the system (whether or not it's
dtuser
or specified by theUSER parameter
). - The unprivileged
username
is preserved during upgrades, unless a new username is specified during upgrade.
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
.
- 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 both 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, hyphen
-
, underscore_
, and dot.
- Minimum length is 3 characters
- Maximum length is 32 characters
- Can't be a user identifier string
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:
- Can contain only alphanumeric characters, hyphen
-
, underscore_
, and dot.
- Minimum length is 3 characters
- Maximum length is 32 characters
- Can't be a group identifier string