Customize ActiveGate installation on Linux

You do not need to specify any parameters to the installation command, unless you need to customize settings such as directory locations, proxy configuration, SSL certificates, etc. Command-line parameters and environment variables can be used to customize such settings.

Installation command syntax

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

Spaces between the parameter name and parameter value (around the = sign) are not allowed in the command syntax.

Proxy configuration

Proxy configuration should be given in the following format:

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

Reverse proxy or load balancer configuration

A reverse proxy or a load balancer can be placed on the path from an ActiveGate to the Dynatrace Cluster. This allows your ActiveGate to connect to any available node of the Cluster, spreading the load between the nodes.
To do this, you need to:

  • Provide the address of the reverse proxy/load balancer.
  • Ensure that ActiveGate will ignore any further target address information sent from the Dynatrace Cluster, and will thus connect only to the address you have specified.

Such configuration settings can be specified during ActiveGate installation, by giving the following command-line parameters to the installer:

--ignore-cluster-runtime-info SERVER=<address of reverse proxy>

Alternatively, you can configure your ActiveGate after installation, by making changes to ActiveGate configuration.

User for ActiveGate service

To specify the user that runs the ActiveGate service, provide the following command-line option:

USER=<user>

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.

Constraints for directory location and mount points

For the full list of ActiveGate directory locations see ActiveGate files and directories.

<customizable directory>/gateway—that is, INSTALL/gateway, CONFIG/gateway, LOG/gateway, TEMP/gateway, PACKAGES_DIR/gateway—cannot be a parent of another customizable directory, that is of INSTALL, CONFIG, TEMP, LOG or PACKAGED_DIR.

For example, do not specify:

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

Similarly, do not specify:

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

However, a common parent is allowed, for example:

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

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.

Use of /temp or /tmp

Because of possible automatic purging, we recommend that you not use the /temp or /tmp directories or their subdirectories to install ActiveGate or store any data generated or used by ActiveGate.

Installation directory

INSTALL=<directory>

Stores installation files in the specified directory. The default value for this parameter (if not specified) is /opt/dynatrace. This parameter is not permitted during update.

Directory for storing downloaded packages

PACKAGES_DIR=<directory>

Stores installation files of additional capabilities in the specified directory. The default value for this parameter (if not specified) is /var/lib/dynatrace/packages. Not permitted during update.

Log directory

LOG=<directory>

Stores log files in the specified directory. The default value for this parameter (if not specified) is /var/log/dynatrace. Not permitted during update.

Configuration directory

CONFIG=<directory>

Stores configuration files in the specified directory. The default value for this parameter (if not specified) is /var/lib/dynatrace. Not permitted during update.

Temporary directory

TEMP=<directory>

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

CA certificate

You can specify the CA certificate during installation. The certificate 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:

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

Constraints for specifying SSL certificate

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.

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 certificate 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:

[root@host]# ./Dynatrace-ActiveGate-Linux-1.217.sh --certificate-file=/home/fred/myCert.jks  --certificate-password-file=/home/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 update.

Group

ActiveGate 1.209+

--set-group=<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 update.

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. In Linux deployments, this parameter must be used as an environment variable.

The connection timeout, as specified by the DYNATRACE_ACTIVEGATE_SERVER_CONNECTION_TIMEOUT=<seconds> environment variable, 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.

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>