Customize ActiveGate installation on Windows

Additional installation parameters and options can be specified on the command line or they can be entered in the installer UI. They can be used to customize settings such as directory locations, proxy configuration, SSL certificates etc.

Installation command syntax

Dynatrace-ActiveGate-Windows-x86-<version>.exe [<parameter1>=<value1>]  [<parameter2>=<value2>] ...

Proxy configuration

In the installer UI, select the Use proxy check box. Then enter the configuration information into the box beneath the check box. Proxy configuration, as entered in the installer UI, should be given in the following format:

<proxy scheme><user>:<password>@<server>:<port>

Where:

  • All components are optional except for <server>.
  • If neither <user> nor <password> are provided, then the @ character should be omitted.
  • <password> can only be given if user name is specified.
  • ':' after <user> can be given even if the password part is empty.
  • <proxy scheme> is optional and can be 'http://' or 'https://'.
  • <user> is optional.
  • <server> can be an IP address or a DNS name, but not a path. For example, if '1.2.3.4/textaferslash' is provided, only the IP part ('1.2.3.4') will be extracted. The slash and the text that follow will be ignored.
  • <port> is optional.

Installation directory

Absolute path to the location of the installation directory can be specified in the installer UI. This folder will be used for installing ActiveGate executable files and libraries. Note that ActiveGate configuration files are not stored in this location.

CA certificate

Note:
Directly specifying an SSL certificate for an ActiveGate is not applicable for Cluster ActiveGates. Do not attempt to configure SSL certificates directly on a Cluster ActiveGate. If you do, the certificate will be overwritten by automatic management performed by Dynatrace. For Cluster ActiveGates, you must upload your certificates using the Cluster Management Console or the Cluster REST API v1.

You can use command-line parameters to specify the CA proxy certificate (the certificate to be used when ActiveGate connects to the Dynatrace Cluster) during installation. This enables a connection to be established to the cluster during installation, allowing the ActiveGate installer to download and install any required additional capabilities.
The password is specified as a file from which the password is read.

Absolute path to the location of custom trusted root certificate(s):

CA_CERTIFICATE_FILE=<path>

Absolute path to the location of the file containing the certificate password:

CA_CERTIFICATE_PASSWORD_FILE=<path>

Command example:

C:\Dynatrace-ActiveGate-Windows-x86-<version>.exe CA_CERTIFICATE_FILE=D:\Users\Fred\myCert.jks CA_CERTIFICATE_PASSWORD_FILE=D:\Users\Fred\myPwd.txt

Custom SSL certificate

During installation you can specify the authentication certificate that ActiveGate provides to connecting clients, such as OneAgents or connections from browser clients. If such certificates are required, then this reduces the effort of post-installation configuration.
The password is specified as a file from which the password is read.

Absolute path to the location of the authentication certificate ActiveGate provides to connecting clients, such as OneAgents or connections from browser clients (such as the RUM JavaScript):

CERTIFICATE_FILE=<path>

Absolute path to the location of the file containing the certificate password, for the authentication certificate ActiveGate provides to connecting clients:

CERTIFICATE_PASSWORD_FILE=<path>

Command example:

c:\Dynatrace-ActiveGate-Windows-x86-<version>.exe CERTIFICATE_FILE=D:\Users\Fred\myCert.jks CERTIFICATE_PASSWORD_FILE=D:\Users\Fred\myPwd.txt

Network zone

--set-network-zone=<name>

Defines the network zone to which the ActiveGate belongs. An ActiveGate can belong to only one network zone. The name of a network zone is a string of alphanumeric characters, hyphens (-), underscores (_), and dots (.). Dots are used as separators, so you must not use a dot as the first character of a network zone name. The length of the string is limited to 256 characters.

This parameter is not permitted during upgrade of an existing ActiveGate, and can be used only for fresh installations; to add an existing ActiveGate to an ActiveGate group, specify the group in the custom.properties file.

ActiveGate 1.209+

--set-group-name=<name>

Defines the ActiveGate group to which the ActiveGate belongs. An ActiveGate can belong to only one group. The name of an ActiveGate group is a string of alphanumeric characters, hyphens (-), underscores (_), and dots (.). Dots are used as separators, so you must not use a dot as the first character of a group name. The length of the string is limited to 256 characters. You can use ActiveGate groups to perform bulk actions on your ActiveGates, such as managing the Extension 2.0 framework extensions running on ActiveGates. For more information, see Extensions 2.0.

This parameter is not permitted during upgrade of an existing ActiveGate, and can be used only for fresh installations; to add an existing ActiveGate to an ActiveGate group, specify the group in the custom.properties file.

Connection timeout

DYNATRACE_ACTIVEGATE_SERVER_CONNECTION_TIMEOUT=<seconds>

Defines the maximum number of seconds (default: 120) the installer will wait for a connection to the cluster.

The connection timeout, as specified by the DYNATRACE_ACTIVEGATE_SERVER_CONNECTION_TIMEOUT=<seconds> command-line parameter, is used in two stages of the installation:

  • When downloading additional (optional) capabilities.
  • When waiting for connection to the cluster at the end of ActiveGate installation: this connection is then used by ActiveGate during its normal operation.

If the timeout occurs during the download of capabilities (if any), the additional capabilities will not be downloaded and the installation will fail. However, if the timeout occurs at the end of the installation process—that is at the start of normal operation of ActiveGate—all the ActiveGate components will have been installed and ActiveGate will continue its attempts at connecting to the cluster. ActiveGate will keep trying to connect, even after the end of the installation process. If successful, ActiveGate will then operate normally.

To check if the installation and connection was successful, sign in to Dynatrace, in Settings select Deployment Status, and then select the ActiveGates tab.