Настройка установки OneAgent в Windows

Установщик ЕдиногоАгента для Windows предоставляется и используется в виде самораспаковывающегося EXE-файла. Установщик также можно извлечь и использовать напрямую — в виде пакета MSI. Этот более поздний подход в основном используется при развертывании групповой политики.

Вы можете настроить установку, указав параметры командной строки для выбранных параметров, или вы можете полагаться на параметры по умолчанию. Однако обратите внимание, что параметры, отмеченные ниже как зависящие от среды, то есть параметры, которые устанавливают конечную точку связи, идентификатор среды и токен, — это:

• обязательный
• предварительно настроен только для EXE-версии установщика. Поэтому при использовании установщика в качестве MSI-пакета необходимо указывать эти параметры явно.

Передача параметров установки

Командная строка

Чтобы передать параметры, добавьте их к команде установщика и разделите пробелами.

Например, для EXE-версии установщика:

.\OneAgent-Windows.exe --set-host-group=my_host_group --set-infra-only=true INSTALL_PATH="C:\installdir"

При использовании установщика в качестве пакета MSI вы можете напрямую добавлять только параметры INSTALL_PATH, LOG_PATH, DATA_STORAGE, PCAP_DRIVER и USER. Этот тип установки обычно выполняется в автоматическом режиме как часть развертывания групповой политики. --set-param=<value> должен быть помещен внутри ADDITIONAL_CONFIGURATION (ADDITIONAL_CONFIGURATION="--set-param=<value>").

Дополнительные сведения о синтаксисе командной строки см. в разделе Silent installation.

Пользовательский интерфейс установщика

Вы также можете добавить параметры --set-param=<value> на экране установки настроек конфигурации ЕдиногоАгента.

Параметры, поддерживаемые пользовательским интерфейсом установщика

Пользовательский интерфейс установщика ЕдиногоАгента для Windows поддерживает только параметры --set-param=<value>.

Следующие параметры НЕ поддерживаются пользовательским интерфейсом установщика: USER, INSTALL_PATH, LOG_PATH, PCAP_DRIVER и DATA_STORAGE.

Удаленные параметры установки

Начиная с версии 1.213, следующие параметры принимаются только в том случае, если они заданы с использованием синтаксиса --set-param=<value>. Для этих конкретных параметров эквивалентный синтаксис PARAM=<value> больше не поддерживается:

Удаленный параметр PARAM=<value>	Новый --set-param=<value> параметр
SERVER	--set-server
TENANT	--set-tenant
TENANT_TOKEN	--set-tenant-token
PROXY	--set-proxy
HOST_GROUP	--set-host-group
APP_LOG_CONTENT_ACCESS	--set-app-log-content-access
INFRA_ONLY	--set-infra-only

Параметры установки MSI

INSTALL_PATH, LOG_PATH, DATA_STORAGE, PCAP_DRIVER и USER это особый тип параметров, соответствующих синтаксису общедоступных свойств MSI. Они не будут заменены эквивалентными параметрами --set-param=<value>. Вы можете использовать их только в командной строке установщика, а не в пользовательском интерфейсе установщика.

Путь установки

Значение по умолчанию: %PROGRAMFILES%\key-astrom\oneagent

Параметр INSTALL_PATH позволяет установить один агент в каталог по вашему выбору.

Например:

.\Key-Astrom-OneAgent-Windows.exe INSTALL_PATH="C:\test dir".

Примечание: Этот параметр не поддерживается пользовательским интерфейсом установщика.

Примечание: Параметр INSTALL_PATH не управляет каталогами журнала и файлов конфигурации ЕдиногоАгента. Чтобы настроить путь к журналу, используйте параметр LOG_PATH.

Требования к пользовательскому каталогу

Ваш пользовательский каталог установки должен соответствовать следующим требованиям:

• Каталог должен быть выделен только для целей одного агента. Никакое другое программное обеспечение не может иметь к нему доступа. Одной из причин является безопасность, а другой - автоматическая очистка, периодически выполняемая одним агентом, которая может удалять файлы, созданные другими приложениями.
• Вы не должны совместно использовать или вкладывать друг в друга каталоги установки, хранения и журнала.
• Значение должно быть абсолютным путем и не должно указывать на каталог корневого тома.
• Значение не должно быть дочерним каталогом %PROGRAMDATA%\key-astrom.

Путь к журналу

Значение по умолчанию: %PROGRAMDATA%\key-astrom\oneagent\log

Параметр LOG_PATH позволяет настроить каталог журналов одного агента.

Например:

.\Key-Astrom-OneAgent-Windows.exe LOG_PATH=C:\key-astrom\logs

Примечание: Этот параметр не поддерживается пользовательским интерфейсом установщика.

Требования к пользовательскому каталогу

Ваш пользовательский каталог установки должен соответствовать следующим требованиям:

• Каталог должен быть выделен только для целей одного агента. Никакое другое программное обеспечение не может иметь к нему доступа. Одной из причин является безопасность, а другой - автоматическая очистка, периодически выполняемая одним агентом, которая может удалять файлы, созданные другими приложениями.
• Вы не должны совместно использовать или вкладывать друг в друга каталоги установки, хранения и журнала.
• Значение должно быть абсолютным путем и не должно указывать на каталог корневого тома.
• Значение не должно быть дочерним каталогом %PROGRAMDATA%\key-astrom.

Изменение расположения

Если вы используете этот параметр для изменения местоположения для уже установленного ЕдиногоАгента:

• Существующие файлы не переносятся в новое расположение
• После установки или изменения параметра LOG_PATH необходимо перезапустить процессы с глубоким мониторингом, чтобы один из агентов, отслеживающих их, мог выбрать новый путь для хранения журналов. Вы получите уведомление о необходимости перезапуска соответствующего процесса на странице Обзора процесса.

Хранение данных

ЕдиныйАгент версии 1.199

Значение по умолчанию: %PROGRAMDATA%\key-astrom\oneagent\datastorage

Параметр DATA_STORAGE позволяет определить каталог, предназначенный для хранения больших данных во время выполнения, создаваемых ЕдинымАгентом в режиме мониторинга полного стека, таких как отчеты о сбоях или дампы памяти.

Для примера:

.\Key-Astrom-OneAgent-Windows.exe DATA_STORAGE=D:\data\key-astom\runtime

Примечание: Этот параметр не поддерживается пользовательским интерфейсом установщика.

Требования к пользовательскому каталогу

• Каталог должен быть выделен только для целей одного агента. Никакое другое программное обеспечение не может иметь к нему доступа. Одной из причин является безопасность, а другой - автоматическая очистка, периодически выполняемая одним агентом, которая может удалять файлы, созданные другими приложениями.
• Вы не должны совместно использовать или вкладывать друг в друга каталоги установки, хранения и журнала.
• Значение должно быть абсолютным путем и не должно указывать на каталог корневого тома.
• Значение не должно быть дочерним каталогом %PROGRAMDATA%\key-astrom.

Изменение расположения

Если вы используете этот параметр для изменения местоположения для уже установленного ЕдиногоАгента:

• Существующие файлы не переносятся в новое расположение
• После установки или изменения параметра DATA_STORAGE необходимо перезапустить процессы с глубоким мониторингом, чтобы один из агентов, отслеживающих их, мог выбрать новый путь для хранения данных во время выполнения. В противном случае дампы памяти и другие данные во время выполнения не будут сохранены. Вы получите уведомление о необходимости перезапуска соответствующего процесса на странице Обзора процесса.

Адрес конечной точки связи

Значение по умолчанию: зависит от окружения

Адрес конечной точки связи с ЕдинымАгентом, который представляет собой компонент Ключ-Астром, на который ЕдиныйАгент отправляет данные. В зависимости от вашего развертывания это может быть кластер Ключ-Астром или АктивныйШлюз. Если вы устанавливаете один агент с помощью страницы развертывания Ключ-Астром, для этого параметра уже установлено правильное значение. Чтобы изменить его, используйте IP-адрес или имя. Добавьте номер порта после двоеточия.

Чтобы задать конечную точку связи, передайте ее в качестве значения параметра:

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

ЕдиныйАгент и кластер Ключ-Астром автоматически поддерживают рабочее соединение. Если сведения о конечной точке изменяются, кластер уведомляет ЕдиногоАгента об изменении, и ЕдиныйАгент автоматически обновляет конечную точку, заданную с помощью --set-server, до нового рабочего значения.

Если вам нужно изменить конечную точку после установки, используйте --set-server в интерфейсе командной строки ЕдиногоАгента.

Идентификатор окружения

Значение по умолчанию: зависит от окружения

Идентификатор среды Ключ-Астром, который вы получили вместе с вашим электронным письмом для активации. Если вы устанавливаете ЕдиныйАгент с помощью страницы развертывания Ключ-Астром, для этого параметра уже установлено правильное значение. Если вы продаете услуги на основе Ключ-Астром, используйте этот параметр, чтобы задать идентификаторы своих клиентов из пула идентификаторов, которые вы приобрели у Ключ-Астром.

Чтобы задать идентификатор среды, передайте его в качестве значения параметра:

--set-tenant=mySampleEnv

Если вам нужно изменить клиента после установки, используйте --set-tenant в интерфейсе командной строки ЕдиногоАгента.

Токен

Значение по умолчанию: зависит от окружения

Токен клиента, который используется для проверки подлинности, когда ЕдиныйАгент подключается к конечной точке связи для отправки данных. Если вы устанавливаете один агент с помощью страницы развертывания Ключ-Астром, для этого параметра уже установлено правильное значение.

Чтобы установить токен, передайте его в качестве значения параметра:

--set-tenant-token=abcdefghij123456

См. раздел Токены доступа, чтобы узнать, как получить токен.

Если вам нужно изменить токен клиента после установки, используйте --set-tenant-token в интерфейсе командной строки ЕдиногоАгента.

Сетевые зоны

Значение по умолчанию: не задано

Чтобы узнать о правилах именования сетевых зон и другой справочной информации, см. раздел Сетевые зоны.

Используйте параметр --set-network-zone, чтобы указать одному Агенту осуществлять связь через указанную сетевую зону:

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

Если вам нужно изменить назначение сетевой зоны после установки, используйте --set-network-zone в интерфейсе командной строки ЕдиногоАгента.

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.

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

Port range

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.

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 use this command to disable auto-updates, you won't be able to control OneAgent automatic updates using the Dynatrace web UI at Settings > Preferences > 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:

• 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

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

To enable Infrastructure monitoring mode, set the parameter to:

--set-infra-only=true

To disable Infrastructure monitoring mode, set the parameter to:

--set-infra-only=false

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

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.

Important: This command adds a custom host name to display in the UI, but the detected host name is not changed. For details, see Set custom host names.

To set the host name:

--set-host-name=myhostname

If you need to change the host name after installation, use --set-host-name in 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.

If you need to change the host metadata after installation, use --set-host-property 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.

If you need to change the host tags after installation, use --set-host-tag in 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:

• auto — Let Dynatrace generate the host ID automatically
• ip-addresses — Generate host ID based on the host IP address
• mac-address — Generate host ID based on the host's NIC MAC address
• fqdn — Generate host ID based on the host fully qualified domain name (FQDN) in the host.domain format. If the FQDN doesn't contain a dot character, the NIC MAC address is used instead.
• If you monitor multiple environments, you can split the hosts with identical IPs, MAC addresses, or FQDNs using a different namespace for each environment. The namespace can contain only alphanumeric characters, hyphens, underscores, and periods; the maximum length is 256 characters:

• ip-addresses;namespace=<namespace>
• mac-addresses;namespace=<namespace>
• fqdn;namespace=<namespace>

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"

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.

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

OneAgent version 1.213

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

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.

OneAgent extension user

The Default value: LocalSystem (OneAgent version 1.195+. For earlier versions, it's dtuser)

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

.\Dynatrace-OneAgent-Windows.exe USER=LocalService

Note: This parameter is not supported by the installer UI.

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.
• Deprecated no_create disabled user creation when installing OneAgent prior to OneAgent version 1.209. Starting with the version 1.209, when you use the no_create parameter, the OneAgent installer applies the LocalSystem parameter without any warning. The no_create setting is not converted to LocalSystem for existing installations when running an update. To convert, you must reinstall OneAgent setting the USER parameter to a new value.
• Deprecated dtuser was the default user account used to run OneAgent extensions prior to OneAgent version 1.195. It made the installer create a local user account with the same name in the system. Starting with the version 1.209, when you use the dtuser parameter, the OneAgent installer applies the LocalSystem parameter without any warning. Starting with OneAgent version 1.239, the dtuser setting is converted to LocalSystem for existing installations when running an update.

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

When using the silent installation mode, the OneAgent installer should be pre-configured with appropriate parameter values, since interactive dialogs and prompts will not be displayed during installation. Note: The environment specific parameters are preconfigured only for the EXE version of the installer. When using the installer in the form of an MSI package, you must specify all of these parameters yourself.

MSI package—silent installation

To set up silent command-line installation when using an MSI package, 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" /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" /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 version of the installer, add --quiet as in this example:

.\Dynatrace-OneAgent-Windows.exe --set-host-group="myGroup" --quiet

Packet capture driver (pcap)

OneAgent version 1.229+

The PCAP_DRIVER parameter allows you to specify which packet capture driver will be installed and used for network metrics collection.

Possible values:

npcap—install the Npcap driver. This option will uninstall any existing installation of Npcap or WinPcap

winpcap—install the WinPcap driver. This option will NOT uninstall or overlay any existing installation of Npcapor WinPcap.

auto—automatically determine which driver to install. This option will NOT uninstall or overlay any existing installation of Npcapor WinPcap. By default, Npcap is installed, except for Windows Server 2019 build 1809 without hotfix KB4571748, where, for compatibility reasons, WinPcap is installed.

Default value: auto

Example:

.\Dynatrace-OneAgent-Windows.exe PCAP_DRIVER=npcap

Note:

• This parameter is not supported by the installer UI.
• The value of this parameter persists through updates.

For more information, see

• OneAgent security on Windows
• Install OneAgent on Windows