Customize ActiveGate installation

Linux

Command-line parameters and environment variables can be used to customize the installation. Some of these parameters pertain folder locations.

Command-line parameters

Dynatrace-ActiveGate-Linux-x86-<version>.sh [<parameter1>=<value1>] [<parameter2>=<value2>] ...

INSTALL=/dynatrace
LOG=/dynatrace/gateway/logs
CONFIG=/dynatrace/gateway/config
TEMP=/dynatrace/gateway/tmp

CONFIG=/var/lib/dynatrace
PACKAGES_DIR=/var/lib/dynatrace/gateway/packages

INSTALL=/example/apps
CONFIG=/example/configs
LOG=/example/logs
TEMP=/example/tmp

• PROXY=<proxy_configuration>
  Proxy configuration information. See Specifying proxy configuration.

• USER=<user>
  Runs the ActiveGate service as the specified user. For versions earlier than Dynatrace 1.155, the user must exist in the system. For versions 1.155+, the installer creates the user if the user doesn't already exist in the system, and the user doesn't require root privileges. If the parameter isn't specified, the installer creates user dtuserag to run the ActiveGate service. However, you can use USER=root to force the ActiveGate service to run as root. Note: the USER=root parameter is not supported when installing a synthetic-enabled ActiveGate.

• INSTALL=<folder>
  Stores installation files in the specified folder. The default value for this parameter (if not specified) is /opt/dynatrace. This parameter is not permitted during upgrade.

• PACKAGES_DIR=<folder>
  Stores installation files, of additional capabilities, in the specified folder. The default value for this parameter (if not specified) is /var/lib/dynatrace/packages. Not permitted during upgrade.

• LOG=<folder>
  Stores log files in the specified folder. The default value for this parameter (if not specified) is /var/log/dynatrace. Not permitted during upgrade.

• CONFIG=<folder>
  Stores configuration files in the specified folder. The default value for this parameter (if not specified) is /var/lib/dynatrace. Not permitted during upgrade.

• TEMP=<folder>
  Indicates the temporary directory to be used by ActiveGate. The default value for this parameter (if not specified) is /var/tmp/dynatrace. Not permitted during upgrade.

• --ca-certificate-file=<path>
  Absolute path to the location of the certificate to be used when ActiveGate connects to the Dynatrace Cluster. See Specifying CA certificate during ActiveGate installation.

• --ca-certificate-password-file=<path>
  Absolute path to the location of the file containing the certificate password. See Specifying CA certificate during ActiveGate installation.

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

• --set-group=name=<name> ActiveGate 1.209+
  

  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. Currently, an ActiveGate group can be used as a means of logical grouping. In future releases, you'll be able to use it to perform bulk actions on your ActiveGates, such as managing extensions running on ActiveGates.

  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.

Environment variables

• DYNATRACE_ACTIVEGATE_SERVER_CONNECTION_TIMEOUT=<seconds>
  Defines the maximum number of seconds (default: 120) the installer will wait for a connection to the cluster:

  • in order to download additional capabilities, or
  • to commence its normal operation, after downloading and installing any required capabilities.

  In Linux deployments, this parameter must be used as an environment variable. For example:

  [root@host]# export DYNATRACE_ACTIVEGATE_SERVER_CONNECTION_TIMEOUT=240
  [root@host]# Dynatrace-ActiveGate-Linux-x86-1.0.0.sh <... other parameters>
  

  or you can use combined commands in a single line. For example:

  [root@host]# export DYNATRACE_ACTIVEGATE_SERVER_CONNECTION_TIMEOUT=240 ; Dynatrace-ActiveGate-Linux-x86-1.0.0.sh <... other parameters>
  

  See Specifying connection timeout

Mount points

During the install process, ActiveGate creates subdirectories under its top-level directories. If you have used the INSTALL or CONFIG parameters to specify paths, ActiveGate will create its subdirectories under the specified paths. Do not create mount points to these installer-created subdirectories. You can only mount the default top-level directories or the top-level directories you have specified.

For example, if you have provided the following INSTALL parameter:

INSTALL=/opt/MyActiveGate

The ActiveGate installer will create a subdirectory gateway in the installation path you have provided:

/opt/MyActiveGate/gateway

As a result:

• The mount point /opt/MyActiveGate is VALID.
• The mount point /opt/MyActiveGate/gateway is INVALID.

Windows

Additional installation parameters and options can be specified on the command-line or they can be entered in the installer UI.

Command-line parameters

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

• CA_CERTIFICATE_FILE=<path>
  Absolute path to the location of the certificate to be used when ActiveGate connects to the Dynatrace Cluster. See Specifying CA certificate during ActiveGate installation

• CA_CERTIFICATE_PASSWORD_FILE=<path>
  Absolute path to the location of the file containing the certificate password. See Specifying CA certificate during ActiveGate installation

• DYNATRACE_ACTIVEGATE_SERVER_CONNECTION_TIMEOUT=<seconds>
  Defines the maximum number of seconds (default: 120) the installer will wait for a connection to the cluster

  • in order to download additional capabilities, or
  • to commence its normal operation, after downloading and installing any required capabilities.

  See Specifying connection timeout

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

• --set-group=<name> ActiveGate 1.209+
  ActiveGate 1.209+
  

  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. Currently, an ActiveGate group can be used as a means of logical grouping. In future releases, you'll be able to use it to perform bulk actions on your ActiveGates, such as managing extensions running on ActiveGates.

  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.

Parameters and options specified in the installer UI

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

• Proxy configuration information: Select the Use proxy check box. Then enter the configuration information into the box beneath the check box. See Specifying proxy configuration.

Specifying CA certificate during ActiveGate installation

You can 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. The certificate file is copied into the ActiveGate directory structure, in the customkeys subfolder of the ssl folder, in the ActiveGate configuration. The password is extracted from the password file and inserted into the custom.properties file in the ActiveGate configuration. It is then encrypted as soon as the ActiveGate service starts.

Linux command example:

[root@host]# Dynatrace-ActiveGate-Linux-1.75.sh --ca-certificate-file=/home/fred/myCert.jks  --ca-certificate-password-file=/home/fred/myPwd.txt

Windows 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

Specifying proxy configuration

Proxy configuration, as entered either on the command-line (Linux) or in the installer UI (Windows), 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.

Specifying connection timeout

The connection timeout, as specified by the DYNATRACE_ACTIVEGATE_SERVER_CONNECTION_TIMEOUT=<seconds> parameter (environment variable for Linux, command-line parameter for Windows), 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.