Add ForcedEndpoints documentation for MessageBrokerConfig

dataminer/Administrator_guide/DataMiner_Systems/Generating_BrokerGateway_client_secrets.md

@@ -8,7 +8,7 @@ From DataMiner 10.5.0 [CU14]/10.6.0 [CU2]/10.6.5 onwards<!-- RN 44757 + 44778 --
 
 Using internal BrokerGateway Administrator keys for these connections is discouraged, as these keys may be refreshed during cluster maintenance or because of other actions. By contrast, user-generated client secrets persist throughout the cluster's lifecycle and are immediately distributed to all BrokerGateway instances for cluster-wide availability.
 
-Common examples of clients requiring this setup include the [Data Aggregator DxM](xref:Data_Aggregator_DxM) and [Dashboard Gateway](xref:Dashboard_Gateway_installation).
+Common examples of clients requiring this setup include the [Data Aggregator DxM](xref:Data_Aggregator_DxM), [Dashboard Gateway](xref:Dashboard_Gateway_installation), and servers hosting a [DMZ setup for dataminer.services connectivity](xref:Connect_to_cloud_with_DMZ).
 
 > [!IMPORTANT]
 > Using client secrets prevents the root certificate authority from being cycled during DataMiner Agent removals or NATSRepair calls. This is done to ensure that external clients maintain stable connectivity with the cluster, without having to change credentials or trusted root certificates.

dataminer/Administrator_guide/DataMiner_Systems/MessageBrokerConfig_ForcedEndpoints.md

@@ -0,0 +1,40 @@
+---
+uid: MessageBrokerConfig_ForcedEndpoints
+---
+
+# Configuring forced NATS endpoints
+
+The `ForcedEndpoints` setting allows all processes on a server to connect to specific custom NATS endpoints instead of the ones automatically provided by BrokerGateway.
+The `CredentialsUrl` is still used to fetch credentials from BrokerGateway, but the endpoints returned in that response are ignored.
+This setting can be configured in `MessageBrokerConfig.json`. 
+
+This is useful in scenarios where a process must reach NATS through a fixed set of endpoints — for example, when connecting through a proxy, a DMZ, or a load balancer.
+
+> [!NOTE]
+> - From DataMiner 10.6.7<!-- RN 45491 --> onwards, this is supported for DataMiner server processes.
+> - For DxMs, check the release notes of the specific DxM to find out from which version this is supported.
+
+## Configuration
+
+To override the NATS endpoints for all processes on a server, add a `ForcedEndpoints` array to the `BrokerGatewayConfig` section in `C:\ProgramData\Skyline Communications\DataMiner\MessageBrokerConfig.json`:
+
+```json
+{
+  "BrokerGatewayConfig": {
+    "CredentialsUrl": "https://<hostname>/BrokerGateway/api/natsconnection/getnatsconnectiondetails",
+    "APIKeyPath": "C:\\Program Files\\Skyline Communications\\DataMiner BrokerGateway\\appsettings.runtime.json",
+    "ForcedEndpoints": [ "custom-host-1:4222", "custom-host-2:4222", "custom-host-3" ]
+  }
+}
+```
+
+Each entry in `ForcedEndpoints` can be a string in the format `"host:port"` or `"host"`.
+
+When `ForcedEndpoints` is set, the process will:
+
+- Still call `CredentialsUrl` to retrieve the NATS credentials.
+- Use only the endpoints listed in `ForcedEndpoints` to connect to NATS, ignoring any endpoints returned by BrokerGateway. 
+  - The order of endpoints determines the connection preference and fallback order.
+  - These endpoints do not need to be a subset of the known IPs of BrokerGateway.
+
+When `ForcedEndpoints` is absent or empty, normal behavior applies and the endpoints are resolved through BrokerGateway.

dataminer/Administrator_guide/toc.yml

@@ -153,6 +153,8 @@ items:
             topicUid: Disabling_automatic_NATS_config
           - name: Generating BrokerGateway client secrets
             topicUid: Generating_BrokerGateway_client_secrets
+          - name: Configuring forced NATS endpoints
+            topicUid: MessageBrokerConfig_ForcedEndpoints
       - name: Running BPA tests
         topicUid: Running_BPA_tests
         items:

dataminer/DataMiner_Tools/BrokerGateway_Migration.md

@@ -164,7 +164,7 @@ The following actions will be executed automatically during the migration, in th
 
    This file is used when initializing default sessions for DataMiner processes using the NATS communication channel. During system migration, the file is automatically overwritten to include the correct BrokerGateway URL and the path to the associated API key.
 
-A typical example of this file’s contents is shown below:
+   A typical example of this file’s contents is shown below:
 
    ```json
    {
@@ -175,6 +175,8 @@ A typical example of this file’s contents is shown below:
    }
    ```
 
+   Optionally, a `ForcedEndpoints` array can be added to override the NATS endpoints provided by BrokerGateway. This setting should only be used in combination with a server that does not run a DataMiner Agent, for example, servers hosting a [DMZ setup for dataminer.services connectivity](xref:Connect_to_cloud_with_DMZ) or [Dashboard Gateway](xref:Dashboard_Gateway_installation). The [Data Aggregator DxM](xref:Data_Aggregator_DxM) does not work in combination with `ForcedEndpoints`. For more information, see [Configuring forced NATS endpoints](xref:MessageBrokerConfig_ForcedEndpoints).
+
 > [!NOTE]
 > The NATSMigration tool has a hard‑coded 10‑minute timeout for completing the *ResetCluster* operation. If for some reason the migration cannot be completed within 10 minutes, or if something goes wrong during the migration, all Agents will revert back to using the SLNet-managed NATS solution.<!-- RN 41115 -->
 

dataminer/Troubleshooting/Procedures/Investigating_NATS_Issues.md

@@ -164,6 +164,7 @@ This file configures how DataMiner processes connect to BrokerGateway to obtain
 - `CredentialsUrl` typically points to the local Agent (using loopback or FQDN). This is the default setting unless it has been manually changed.
 - If the HTTPS certificate CN/SAN does not match the hostname used in the URL, clients may fail with TLS validation errors.
 - *appsettings.runtime.json* must be present at the path specified in `APIKeyPath`.
+- If you want to override the NATS endpoints returned by BrokerGateway, you can add a `ForcedEndpoints` array. See [Configuring forced NATS endpoints](xref:MessageBrokerConfig_ForcedEndpoints).
 
 **Example:**
 

dataminer/dataminer_services/Connecting_to_cloud/Connect_to_cloud_with_DMZ.md

@@ -72,7 +72,11 @@ From version 2.7.0 of the CloudGateway DxM onwards, you can connect a DMS to dat
 
    1. If you are using the **BrokerGateway-managed** NATS solution:
 
-      1. Copy a `C:\Program Files\Skyline Communications\DataMiner BrokerGateway\appsettings.runtime.json` file from a DataMiner node to the same location on the DMZ.
+      1. Obtain an API key for the DMZ server:
+
+         - From DataMiner 10.5.0 [CU14]/10.6.0 [CU2]/10.6.5 onwards, [generate a BrokerGateway client secret](xref:Generating_BrokerGateway_client_secrets) and place the client secret file on the DMZ server. Then set `APIKeyPath` to the path of that file.
+
+         - In earlier DataMiner versions, copy `C:\Program Files\Skyline Communications\DataMiner BrokerGateway\appsettings.runtime.json` from a DataMiner node to the same location on the DMZ. Then set `APIKeyPath` to the path of the copied file.
 
       1. On the DMZ, open `C:\ProgramData\Skyline Communications\DataMiner\MessagebrokerConfig.json`.
 
@@ -82,15 +86,13 @@ From version 2.7.0 of the CloudGateway DxM onwards, you can connect a DMS to dat
          {
            "BrokerGatewayConfig": {
              "CredentialsUrl": "https://SERVER/BrokerGateway/api/natsconnection/getnatsconnectiondetails",
-             "APIKeyPath": "C:\\Program Files\\Skyline Communications\\DataMiner BrokerGateway\\appsettings.runtime.json"
+             "APIKeyPath": "<path to client secret file or copied appsettings.runtime.json>"
            }
          }
          ```
 
       1. Set the `CredentialsUrl` to point to one of the servers in the **internal network**.
 
-      1. Ensure the `APIKeyPath` points to the destination location of the copied `appsettings.runtime.json` file.
-
    1. If you are using the **SLNet-managed** NATS solution:
 
       1. From a DataMiner node in the internal network, copy `C:\Skyline DataMiner\SLCloud.xml` to the same folder on the DMZ.