Multi-environment deployment of ActiveGate

Latest Dynatrace
4-min read

Multi-environment ActiveGate deprecation

Multi-environment ActiveGate will no longer receive new features or enhancements, and feature requests will not be accepted going forward. Existing functionality remains fully available for the time being, but the concept has reached the end of its active development.

As a consequence of this deprecation, multi-environment ActiveGate can no longer be adopted in new environments or in existing environments where none has been deployed yet.

An end-of-life date will be announced in a future release and communicated separately on this page and in the ActiveGate release notes.
Environment ActiveGate is the recommended alternative, providing equivalent connectivity capabilities scoped to a single Dynatrace environment.

If you've set up several monitoring environments, it might be cumbersome to install and maintain multiple ActiveGates. A single ActiveGate can therefore support multiple monitoring environments. Such an ActiveGate is referred to as a multi-environment ActiveGate.

A multi-environment ActiveGate handles all traffic from the environments it's associated with, so you don't need to adjust firewall settings for each additional Environment ActiveGate.

Limitations

You cannot use an Environment ActiveGate configured for multi-environment support to:

Connect to environments from different clusters
Install the zRemote module for z/OS monitoring
Monitor remote technologies with the Extensions framework
Execute monitors from private Synthetic locations
Run Database insights
Connect to environments where AWS PrivateLink is enabled—multi-environment ActiveGates have never been able to communicate with PrivateLink-enabled environments and can only connect via public cluster endpoints, not environment-specific endpoints.

All other ActiveGate features are supported.

Extensions are not supported on multi-environment ActiveGates or Cluster ActiveGates. To run Extensions, deploy a dedicated Environment ActiveGate for each environment and enable the Extension Execution Controller (EEC).

To configure an existing Environment ActiveGate for multi-environment support

Make sure that the ActiveGate modules that are incompatible with multi-environment operation are disabled. Which module is actually installed and enabled varies based on the purpose for which the ActiveGate was originally installed. Only one of the following modules can be present on the ActiveGate. However, if in doubt, disabling (and then removing) all of these particular modules at this point is acceptable:
- ActiveGate Extensions—disabled in the [extension_controller] section
- zRemote—disabled in the [zremote] section
- Synthetic 1.0—disabled in the [synthetic] section
ActiveGate version 1.333+
You can use agctl to disable incompatible modules:
agctl modules disable rpm,zremote,synthetic,extension_controller
To disable the modules manually, locate the custom.properties file in the configuration directory, and make sure that the corresponding configuration properties are set to false:
[rpm]
rpm_enabled = false

[zremote]
zremote_enabled = false

[synthetic]
synthetic_enabled = false

[extension_controller]
extension_controller_enabled = false
Make sure that the ActiveGate modules that are incompatible with multi-environment operation have been uninstalled.
- For Linux—execute one of the following commands, depending on which module needs to be uninstalled. If in doubt, execute all of the commands: If the commands are found, the respective modules will be uninstalled. If the commands are not found, it means that the modules are not present:
  sudo /opt/dynatrace/remotepluginmodule/uninstall.sh
  sudo /opt/dynatrace/zremote/uninstall.sh
  sudo /opt/dynatrace/synthetic/uninstall.sh
- For Windows: locate and uninstall the following applications, if installed:
  - Dynatrace Remote Plugin Module (Extensions 1.0 only, not present in ActiveGate 1.301+)
  - Dynatrace ZRemote
  - Dynatrace Synthetic
In the ActiveGate configuration directory, locate the authorization.properties file and familiarize yourself with the content.
The authorization.properties file defines ActiveGate authorization for each environment as identified by the environment ID. ActiveGate authorizes via tenant token and individual ActiveGate token. One and only one of the sections will contain the property mainTenant = true. This is for the environment from which the ActiveGate was downloaded and installed. Do not remove this section or this entry. Do not remove any other sections—relating to other environments—unless you do not want the ActiveGate to support those particular environments anymore.

Format of the entries in authorization.properties:
```
[<environment_ID>]
tenantToken = <tenant_token>
mainTenant = true     # identifies environment from which the ActiveGate was downloaded
authToken = <individual_ActiveGate_token>
```
For example:
```
[mySampleEnv]
tenantToken = abcdevjhij1234567890
authToken = dt0g01.HVMTLRLZ.1234567890ZYXWVUTSRQPONMLKJIHGFEDCBA01234567890ABCDEFGHIGKLMNOPQ
mainTenant = true
```
To create an individual ActiveGate token, see Generate ActiveGate token.
To reconfigure the environments that the ActiveGate serves, edit the sections in the authorization.properties file.
List each Dynatrace environment you want the Environment ActiveGate to support. Use the following format:
```
[<environment_ID>]
tenantToken = <tenant_token>
mainTenant = true
authToken = <individual_ActiveGate_token>

[<environment_ID>]
tenantToken = <tenant_token>
authToken = <individual_ActiveGate_token>
```
For example:
```
[mySampleEnv]
tenantToken = abcdevjhij1234567890
authToken = dt0g01.HVMTLRLZ.1234567890ZYXWVUTSRQPONMLKJIHGFEDCBA01234567890ABCDEFGHIGKLMNOPQ
mainTenant = true

[myAnotherEnv]
tenantToken = 0987654321jijvedcba
authToken = dt0g01.HVMTLRLZ.1234567890ZYXWVUTSRQPONMLKJZYXWVUTSRQPONMLKJIHGFE56GHMNO890ZABCD
```
Ensure consistent configuration
For correct operation, you must ensure that:
Every environment you list is already served by a multi-environment ActiveGate. Because of the deprecation described above, you cannot adopt multi-environment ActiveGate in new environments or in existing environments where none has been deployed yet: such an environment is discarded when the ActiveGate registers, and the ActiveGate continues to serve its remaining environments. The discarded environment never appears in Deployment Status (Dynatrace Classic) or in any app in Latest Dynatrace, though its SFM data remains available in the main tenant.
All environments that are to be supported by the same Environment ActiveGate run on the same Dynatrace Cluster.
The main environment, associated with the mainTenant configuration property, is correctly configured. Incorrect configuration of the main environment will result in the rejection of the ActiveGate in all configured environments: An error will be logged in the ActiveGate logs, with information stating that mainTenant configuration is invalid, and the ActiveGate won't appear in Fleet Management on any of the environments.
Save the authorization.properties file and restart the ActiveGate main service.
Verify that the environments are served as expected.
The ActiveGate log file should contain the entry listing the number of environments that the ActiveGate is working with, for example:
```
Working mode is set to MULTITENANT with 5 tenant(s).
```
This entry counts the sections in authorization.properties, so it is written before the ActiveGate contacts the cluster. If it does not list the number of environments that you have attempted to configure, scan the log file for entries indicating an error in the authorization.properties file. Error messages appear in this form:
```
Error during parsing config file `...\conf\authorization.properties` - invalid configuration: ...
```
To confirm which environments the cluster actually accepted, look for the TenantSubmitRuntimeInfo entry that the ActiveGate writes on each registration. When every listed environment is accepted, it is logged at INFO and reports counts only:
```
2026-09-14 09:12:03 UTC INFO    [<collector>] [<collector.core>, InitialCollectorSetupMessageHandler] TenantSubmitRuntimeInfo message received with accepted/discarded tenants. [#total=3, #accepted=3, #discarded=-]
```