Configure ClickHouse

Legacy 'nms' references Some commands, file paths, and configuration references still use nms due to the ongoing transition from NGINX Management Suite (NMS) to NGINX Instance Manager (NIM). These will be updated in future releases.

Overview

NGINX Instance Manager uses ClickHouse to store metrics, events, alerts, and configuration data.
If your setup differs from the default configuration—for example, if you use a custom address, enable TLS, set a password, or turn off metrics—you need to update the /etc/nms/nms.conf file.

This guide explains how to update those settings so that NGINX Instance Manager can connect to ClickHouse correctly.

Change default settings

To change a ClickHouse setting:

  1. Open the configuration file at /etc/nms/nms.conf.

  2. In the [clickhouse] section, update the setting or settings you want to change.

  3. Restart the NGINX Instance Manager service:

    sudo systemctl restart nms

Unless otherwise specified in the /etc/nms/nms.conf file, NGINX Instance Manager uses the following default values for ClickHouse:

Configuration Default Notes
clickhouse.enable true Set to false to disable metrics collection and run NGINX Instance Manager in lightweight mode. Requires a service restart.
clickhouse.address tcp://localhost:9000 The address of the ClickHouse database.
clickhouse.username The username NGINX Instance Manager uses to connect to ClickHouse, if authentication is enabled.
clickhouse.password The password for the specified ClickHouse user.
clickhouse.tls_mode false Set to true to enable TLS for the ClickHouse connection. This setting will be deprecated in a future release. Use the clickhouse.tls section instead.
clickhouse.tls.address tcp://localhost:9440 The address NGINX Instance Manager uses to connect to ClickHouse over TLS. Format: <ip-address>:<port>.
clickhouse.tls.skip_verify false Set to true to skip TLS certificate verification. Use only for self-signed certificates in non-production environments.
clickhouse.tls.key_path Path to the client TLS key file in PEM format. Required for client authentication.
clickhouse.tls.cert_path Path to the client TLS certificate file in PEM format. Required for client authentication.
clickhouse.tls.ca_path /etc/ssl/certs/ca-certificates.crt Path to the system Certificate Authority used to verify the server certificate. The default path works for Ubuntu and Debian. Use a CA bundle appropriate to your system. See TLS configuration for details.

Disable metrics collection

As of version 2.20, NGINX Instance Manager can run without ClickHouse. This lightweight mode reduces system requirements and simplifies installation for users who do not need metrics. To use this setup, you must run NGINX Agent version 2.41.1 or later.

To disable metrics collection after installing NGINX Instance Manager:

  1. Open the configuration file at /etc/nms/nms.conf.

  2. In the [clickhouse] section, set the following value:

    enable = false

  3. Restart the NGINX Instance Manager service:

    sudo systemctl restart nms

When metrics are turned off:

  • The web interface no longer shows metrics dashboards. Instead, it displays a message explaining that metrics are turned off.
  • Metrics-related API endpoints return a 403 error.
  • All other NGINX Instance Manager features continue to work as expected.