Runtime Configuration

The user_config.json file contains a set of the run-time integration configuration that could be changed during the application run.

The file may contain records relevant to all cluster applications installed on the host system. Keys prefixed with "nmx-telemetry" within the file user_config.json define the runtime configuration that could be changed during the application lifecycle. Here is the list of parameters accepted by the NMX Telemetry:

Parameter "manager-encryption" defines the secure communication mode over the NMX Telemetry connector gRPC interface:

• disabled - no security communication enforced

• tls - TLS encryption enforced

• mtls - mutual TLS enforced

Communication mode "tls" requires presence of the fields nmx-telemetry-manager-certificate and nmx-telemetry-manager-private-key. "mtls" mode additionally requires nmx-telemetry-manager-ca-certificate. All these fields should contain correct paths files in order for authentication to take effect.

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

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

• nmx-telemetry-manager-ca-certificate (in "mtls" mode) should point the trusted parent CA certificate, either root or intermediate, or a bundle of the parent CA certificates.

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

If any of the latter three is missing or containing wrong path to the certificate file, configuration will be rejected and the gRPC interface continue using the configuration it used before the change. Which means in particular, if the configuration is broken at the moment of the application start, the gRPC API will operate unsecured, as default value "disabled" considered for the parameter "nmx-telemetry-manager-encryption".

If trusted CA bundle is large, the size of the certificate_authorities extension (RFC 8446) may exceed 64KBytes, the maximum size of TLS handshake messages, and cause TLS handshake to fail. In this case you can point nmx-telemetry-manager-peer-ca-certificate to a lesser CA bundle or even to an empty file ("/dev/null" will also work). If nmx-telemetry-manager-peer-ca-certificate is present and not an empty string, server will use these certificates to generate 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.

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

Example of the 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"
}
        

The "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 enforced

Communication modes "tls" and "mtls" require presence of the fields manager-certificate, manager-private-key and manager-ca-certificate with the correct paths to the certificate files, for the authentication to take effect. If any of the latter three is missing or containing wrong path to the certificate file, configuration will be rejected and the gRPC interface will continue to use the configuration used before the change. Therefore, if the configuration is broken at the moment of the application starts, the gRPC API will operate unsecured, as default value "disabled" is considered for the parameter "manager-encryption".

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

NMX-T reads and applies the runtime user configuration configuration on its start. Path to the directory containing the user_config.json file is given as argument to the start.py script. T

Configuration callback can be used to re-apply configuration given in the user_config.json. Each time the configuration callback is called, NMX Telemetry does the following:

1. Reads content of user_config.json relevant to the telemetry - keys with prefixes "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

Please note that:

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

Configuration callback URL of the NMX-T application is declared by the field "configCallback" of the "nmx-telemetry" section in the cluster application registry "installed_apps.json" file. The default values for the NMX-T are:

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

            

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

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

For example, setting the 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