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. Note that when using Windows Group Policy installer, the parameters that set the communication endpoint, environment ID, and token are mandatory.

For example:
Dynatrace-OneAgent-Windows.exe --set-app-log-content-access=true

You can also add the --set-param=<value> parameters right in one of the OneAgent installation screens.

For example, the following configuration... oneagent windows customize
is an equivalent of...

.\Dynatrace-OneAgent-Windows.exe --set-host-group=my_host_group --set-infra-only=true

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 `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
`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

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.

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.

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:

Infrastructure monitoring mode

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 the OneAgent command-line interface or set it using the Host settings page.

Installation path

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

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

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

OneAgent extension user

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, the default dtuser local account will be used to run OneAgent extensions.

When deploying Dynatrace on Windows Server Domain Controller, set the USER parameter 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.

The USER parameter can have the following values:

LocalSystem: 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.
dtuser is the default user account used to run Dynatrace components. Applied automatically when the USER parameter isn't used.

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.

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.