Interface Configuration

The user_config.json file holds a set of runtime integration configurations that can be modified during the application's execution.

This file may include entries relevant to all cluster applications installed on the host system. Keys prefixed with "nmx-telemetry" in the user_config.json file define the runtime configurations that can be altered during the application's lifecycle. Below is a list of parameters accepted by NMX Telemetry:

Parameter Details

The nmx-telemetry-manager-encryption parameter defines the secure communication mode over the NMX Telemetry connector gRPC interface:

• disabled: No security communication enforced.

• tls: TLS encryption enforced.

• mtls: Mutual TLS (mTLS) enforced.

tls mode requires the presence of both nmx-telemetry-manager-certificateand nmx-telemetry-manager-private-key. mtls mode additionally requires nmx-telemetry-manager-ca-certificate.

All these fields must contain valid paths to the respective certificate files for authentication to take effect:

• nmx-telemetry-manager-certificate should point to the server certificate file (or chain file if the server certificate is signed by an intermediate CA).

• nmx-telemetry-manager-private-key should point to the server key file.

• nmx-telemetry-manager-ca-certificateshould point to the trusted parent CA certificate (either root or intermediate) or a bundle of the parent CA certificates.

• nmx-telemetry-manager-peer-ca-certificate should point to a bundle of the parent CA certificates that the server should send to the client in the certificate_authorities extension of the TLS handshake message (see note below).

If any of the latter three is missing or contains an incorrect path, the configuration will be rejected, and the gRPC interface will continue using the previous configuration. This mean that, if the configuration is broken at the moment the application starts, the gRPC API will operate unsecured, as the default value "disabled" is applied to the nmx-telemetry-manager-encryption parameter.

If the trusted CA bundle is large, the size of the certificate_authorities extension (RFC 8446) may exceed 64KBytes, which is the maximum size of TLS handshake messages, causing the handshake to fail. In such cases, you can point nmx-telemetry-manager-peer-ca-certificate to a smaller CA bundle or even an empty file (e.g., /dev/null). If nmx-telemetry-manager-peer-ca-certificate is present and not an empty string, the server will use these certificates to generate the certificate_authorities extension passed to the client (or will omit the extension completely if the file is empty). Note that some clients may use the content of certificate_authorities extension to select which certificate to send to the server.

File Location

Certificate files should be placed under the /etc/nmx directory on the host system. This directory is mounted to the same path inside the NMX Telemetry containers, making the content accessible to the application.

Example of configuration fie content:

            

            
{
   "nmx-telemetry-manager-port": "enabled",
   "nmx-telemetry-manager-encryption": "mtls",
   "nmx-telemetry-manager-certificate": "/etc/nmx-telemetry/server_cert.pem",
   "nmx-telemetry-manager-private-key": "/etc/nmx-telemetry/server_key.pem",
   "nmx-telemetry-manager-ca-certificate": "/etc/nmx-telemetry/ca_cert.pem",
   "nmx-telemetry-manager-peer-ca-certificate": "/dev/null",
   "nmx-telemetry-log-level": "debug",
   "nmx-telemetry-prometheus-interface": "disabled"
}
        

Communication Mode Summary

The nmx-telemetry-manager-encryption parameter defines the secure communication mode over the NMX Telemetry gRPC interface:

• disabled: No security enforced.

• tls: TLS encryption enforced.

• mtls: Mutual TLS enforced.

For tls and mtls modes, the following fields must be present with valid paths to the certificate files:

• manager-certificate

• manager-private-key

• manager-ca-certificate

If any of these fields are missing or contain incorrect paths, the configuration will be rejected, and the gRPC interface will continue to use the previously applied configuration. If the configuration is broken when the application starts, the gRPC API will operate in an unsecured mode, with the default value "disabled" for the manager-encryption parameter.

Certificate files must be placed under the /etc/nmx directory on the host system, which is mounted to the same path inside the NMX Telemetry containers.

NMX-T reads and applies the runtime user configuration upon startup. The path to the directory containing the user_config.json file is provided as argument to the start.py script. Additionally, the configuration callback can be used to re-apply configuration from user_config.json. Each time the configuration callback is called, NMX Telemetry performs the following actions:

1. Reads the contents of user_config.json relevant to telemetry (keys with the prefix "nmx-telemetry").

2. Replaces value of the key read from the file with the value given in the callback query

3. Applies the runtime configuration.

Important Notes

1. If the configuration is malformed (wrong configuration keys, mismatching value types), it is rejected with no change to the application state

2. if the resulting configuration is invalid (certificates could not be read), application resets to the default configuration

3. resulting configuration is not persisted - sequential calls with different parameters do not result in incremental configuration update

The configuration callback URL of the NMX Telemetry application is specified by the field configCallback in the "nmx-telemetry" section of the cluster application registry installed_apps.json file. By default, NMX Telemetry uses the following configuration callback:

The key and value passed as the request payload used to overwrite values read from the user_config.json file.

            

            
{
   "Key": "configuration parameter name",
   "Value": "configuration parameter value"
}
        

To trigger NMX-Telemetry to re-read the user_config.json file, use the following HTTP request:

            

            
curl --request POST http://0.0.0.0:9350/config
        

For example, the following http request sets the logging level to "debug":

            

            
curl --header "Content-Type: application/json" --request POST --data '{"Key": "nmx-telemetry-log-level", "Value": "debug"}' http://0.0.0.0:9350/config
        

For example, the following http request disabled the gRPC interface:

            

            
curl --header "Content-Type: application/json" --request POST --data '{"Key": "nmx-telemetry-grpc-interface", "Value": "disabled"}' http://0.0.0.0:9350/config