Customize OneAgent installation on Windows

You can use the EXE installer and extracted MSI package with command-line parameters when you can't use the default settings. The parameters marked as environment specific, that is parameters that set the communication endpoint, environment ID, and token are preconfigured only for the EXE installer. When using the MSI Windows Group Policy installer, they are mandatory and you must set them manually.

Passing installation parameters

Command line

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

For example:

.\Dynatrace-OneAgent-Windows.exe --set-host-group=my_host_group --set-infra-only=true INSTALL_PATH="test dir"

For MSI installer, you can directly append only INSTALL_PATH and USER parameters. The --set-param=<value> has to be placed inside of ADDITIONAL_CONFIGURATION (ADDITIONAL_CONFIGURATION="--set-param=<value>"). For more information, see Silent installation.

Windows UI installer

You can also add the --set-param=<value> parameters in the Configure OneAgent settings installation screen.

Improved installation parameters

If you're installing or updating a suitable OneAgent version (see Minimum OneAgent version in the table below), we recommend that you use the newer --set-param=<value> parameters listed below. The equivalent PARAM=<value> parameters will continue to work for the time being, but they will be removed in future releases.

Old parameter	New 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
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.

MSI installation parameters

INSTALL_PATH and USER are a special kind of parameter adhering to MSI public property syntax. They won't be replaced by equivalent --set-param=<value> parameters. You can use INSTALL_PATH and USER only on the installer command line, not in the UI installer.

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 automatically
• ip-addresses generate host ID based on the host IP address
• ip-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: %PROGRAMFILES%\dynatrace\oneagent

Allows OneAgent installation to a directory of your choice. Works only with absolute Windows paths.

For example: INSTALL_PATH="C:\test dir".

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 (%PROGRAMDATA%\dynatrace\oneagent\datastorage). See Data storage.

Data storage

OneAgent version 1.199

Default value: %PROGRAMDATA%\dynatrace\oneagent\datastorage

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:
.\Dynatrace-OneAgent-Windows.exe DATA_STORAGE=D:\data\dynatrace\runtime

The value of the parameter is an absolute path and it must not point to the root volume 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.

Note: The DATA_STORAGE parameter is not supported by the UI installer.

OneAgent extension user

Default value: LocalSystem (OneAgent version 1.195+. For earlier versions dtuser)

Use the USER parameter to define the user running the process responsible for Dynatrace OneAgent extensions functionality.

If you don't add the USER parameter:

• For fresh OneAgent 1.195+ installations, the default LocalSystem account will be used to run OneAgent extensions.
• For fresh OneAgent deployments prior to version 1.195, OneAgent will use the dtuser account.
• Updating the OneAgent preserves the previously configured user account. To change it, you must reinstall OneAgent setting the USER parameter to a new value.

The USER parameter can have one of the following values:

• Recommended LocalSystem is the default user account used to run OneAgent extensions starting with OneAgent version 1.195. Applied automatically when the USER parameter isn't used. This parameter value makes OneAgent use the NT AUTHORITY\SYSTEM privileged system account to run OneAgent extensions. Effectively, no local user account is created. As a result, all OneAgent modules, including all extensions, are fully functional. This is the recommended setting to use for all OneAgent Windows installations starting with OneAgent version 1.191.

• LocalService: This parameter makes OneAgent use the NT AUTHORITY\LOCAL SERVICE system account to run OneAgent extensions. While this reduced set of privileges is enough for most of the extensions to operate, there are some that won't be able to produce data effectively (namely, extensions that collect Performance Monitor counters, such as MS SQL or .NET extensions). If you're unsure about which extensions you might use, it's best to use the LocalSystem parameter value instead.

• no_create disables user creation when installing OneAgent. You can use this to comply with strict security policies that prohibit creation of local user accounts. Note that using USER=no_create disables OneAgent extensions functionality.

• Deprecated dtuser was the default user account used to run OneAgent extensions prior to OneAgent version 1.195. It makes the installer create a local user account with the same name in the system. Note that the dtuser value will be removed in future releases. We recommend to use LocalSystem instead.

When deploying Dynatrace on Windows Server Domain Controller, make sure the USER parameter is set to LocalSystem, or alternatively LocalService, to avoid propagation of dtuser across the domain, which can cause interference with existing dtuser accounts on hosts that have Dynatrace installed.

Silent installation

With silent installation, the Dynatrace installer is pre-configured with parameter values that you define. This means that dialogs won't be generated during installation and no human interaction is required. Note that the environment specific parameters are preconfigured only for the EXE installer. When using the MSI installer, you must define the parameters yourself.

MSI installer silent installation

To set up silent command line installation for an MSI installer, add /quiet /qn as in these examples:

Command shell

msiexec /i C:\some\path\Dynatrace-OneAgent-Windows.msi ADDITIONAL_CONFIGURATION="--set-server=https://someserver.com --set-tenant=xxx --set-tenant-token=xxx --set-host-group=myGroup --set-app-log-content-access=true" /quiet /qn

PowerShell 3.0+

msiexec /i C:\some\path\Dynatrace-OneAgent-Windows.msi --% ADDITIONAL_CONFIGURATION="--set-server=https://someserver.com --set-tenant=xxx --set-tenant-token=xxx --set-host-group=myGroup --set-app-log-content-access=true" /quiet /qn

Note the --% stop-parsing symbol used in the PowerShell command.

EXE installer silent installation

To set up silent command line installation for an EXE installer, add --quiet as in this example:

.\Dynatrace-OneAgent-Windows.exe --set-host-group="myGroup" --set-app-log-content-access=true --quiet

Access to system logs

OneAgent can download system logs for the purpose of diagnosing issues that may be caused by conditions in your environment. OneAgent doesn't currently download any Windows system logs, but this can change in future releases.

--set-system-logs-access-enabled=false disables access to logs --set-system-logs-access-enabled=true 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 that is not related to Log Monitoring.