Configure NGINX Management Suite with nms.conf

Follow the steps in this guide to configure NGINX Management Suite with a configuration file.

Overview

The NGINX Management Suite includes several modules for managing your NGINX instances:

Instance Manager: This module allows you to manage multiple NGINX instances, whether they’re running on-premises, in the cloud, or in containers. With Instance Manager, you can perform tasks such as installing, configuring, and upgrading NGINX instances, as well as monitoring their health and performance.
API Connectivity Manager: This module provides a centralized interface for managing APIs that are exposed by NGINX instances. With API Connectivity Manager, you can create, publish, and secure APIs, as well as monitor their usage and performance.
App Delivery Manager: This module enables you to manage the delivery of applications that are hosted on NGINX instances. With App Delivery Manager, you can perform tasks such as deploying applications, managing SSL certificates, and configuring load balancing and caching.

To configure NGINX Management Suite, you can edit the default configuration file located at /etc/nms/nms.conf.

The nms.conf file is a configuration file, written in YAML format, used by NGINX Management Suite. This file contains settings and options that determine how the software works. The options in the file include settings for the user and group that non-privileged processes should run as; the CA cert file used for TLS server; the URL for NGINX Management Suite; the choice of whether the software should run in development mode or daemon mode; the root directory for Dqlite data; as well as various settings pertaining to logging, modules, and services.

Example nms.conf

The following example nms.conf file displays the configurable options, including their usage, placement, and default values.

# Sets non-privileged processes to run as a specified user.
user: nms

#  Sets non-privileged processes to run as a specified group.
group:

# Sets CA cert file used for TLS server.
ca_file:

# Sets the NGINX Management Suite URL.
fqdn: 127.0.0.1:443

# Run service in development mode.
dev_mode:

# Sets a daemon mode for running binary.
daemon: true

# Sets the root directory for Dqlite data.
db_root_dir: /var/lib/nms/dqlite

# For cloud Usage, the Cloud Services catalog ID for this product.
# Note: `cloud_catalog_id` will be deprecated in the future.
cloud_catalog_id: 

# Sets file mode for all unix sockets
socket_file_mode: 0660

log:
  # Sets the log level for all processes.
  level: error

  # Sets logging output encoding [console, json].
  encoding: console

# To configure NGINX Management Suite in High Availability mode, set ha.
ha:
  # With HA, use this flag to set the cluster size.
  cluster_size: 3

modules:
  # Sets full path for the modules prefix, modules and modules.json will be created.
  prefix: /var/lib/nms

  # Sets path for modules config files will be located.
  conf_dir:

# Sets disable context sub-loggers flag.
disable_context_sub_loggers: false

core:
  # Sets the log level for NGINX Management Suite Core service.
  log_level: 

  # Sets the address for NGINX Management Suite Core requests.
  address: unix:/var/run/nms/core.sock

  # Sets the address for NGINX Management Suite Core GRPC requests.
  grpc_addr: unix:/var/run/nms/coregrpc.sock

  # Sets the secrets directory path.
  # Note: `secrets_dir` will be deprecated in the future. Use `secrets` key to set up core secrets.
  secrets_dir: /var/lib/nms/secrets/

  dqlite:
    # Sets the address for Core module Dqlite database address.
    addr: 127.0.0.1:7891

    # Sets the path for Core module Dqlite database initialization schema file.
    schema: etc/nms/core/schema.sql

    # Sets the directory for Core module Dqlite database migration files.
    migrations_dir: /etc/nms/core/migrations

    # With ha, sets the join flag for Core module Dqlite database
    join:

    # Sets verbosity level to debug for Core module Dqlite database.
    verbose:

    # Sets the snap instance name for Core module Dqlite database.
    name: core

  
  server_certs:
    # Sets the path of cert file for Core TLS endpoints.
    cert: 

    # Sets the path of key file for Core TLS endpoints.
    key:

  client_certs:
    # Sets the path of client cert file for Core TLS endpoints.
    cert:

    # Sets the path of key file for Core TLS endpoints.
    key:

  analytics:
    # Sets to enable Core to run in multi-tenancy mode.
    # Note: `multi_tenancy_enabled` will be deprecated in the future.
    multi_tenancy_enabled: false

    catalogs:
      # Sets the path to metrics data directory.
      metrics_data_dir: /usr/share/nms/catalogs/metrics

      # Metrics catalog data (YAML) content - overwrites metrics data file content.
      metrics_data:

      # Sets the path to events data directory.
      events_data_dir: /usr/share/nms/catalogs/events

      # Sets the path to dimensions data directory.
      dimensions_data_dir: /usr/share/nms/catalogs/dimensions

      # Dimensions catalog data (YAML) content - overwrites dimensions data file content.
      dimensions_data:
  
  license:
    # Sets the period for license status monitoring.
    monitoring_period: 24h

    # Sets the period for license event publishing.
    event_publish_period: 10s

  secrets:
    # Sets driver key for Core secrets.
    driver: local

    # Sets config key for Core secrets.
    config: 
      key_file: /var/lib/nms/secrets/key 
      limit: 16384
      path: /var/secrets
      subpaths:
        - secret 
        - secret/secureString

  # Sets disabling for automatic RBAC cleanup.
  disable_rbac_cleanup: 

dpm:

   # Sets the log level for the NGINX Management Suite Data Plane Manager (DPM) service.
  log_level: 

  # Sets the address for NGINX Management Suite DPM requests.
  address: unix:/var/run/nms/dpm.sock

  # Sets the address for NGINX Management Suite DPM GRPC requests.
  grpc_addr: unix:/var/run/nms/am.sock

  # If enabled, keeps DPM deployments in list indefinitely.
  deployment_debug: false

  # Sets the timeout (in seconds) of the system entry, after which system will be reported as offline. 
  system_timeout: 60

  # Sets the timeout (in seconds) of the nginx entry, after which nginx will be reported as offline.
  nginx_timeout: 60

  # If enabled, validates dpm configuration before config is published.
  validate_before_publish: false

  # If enabled, uses the local copy of the NGINX CVE XML file located at /usr/share/nms/cve.xml. 
  offline_nginx_cve: false

  dqlite:
    # Sets the address for DPM module Dqlite database address.
    addr: 127.0.0.1:7890

    # Sets the path for DPM module Dqlite database initialization schema file.
    schema: etc/nms/dpm/schema.sql

    # Sets the directory for DPM module Dqlite database migration files.
    migrations_dir: /etc/nms/dpm/migrations

    # With ha, sets the join flag for DPM module Dqlite database
    join:

    # Sets verbosity level to debug for DPM module Dqlite database.
    verbose:

    # Sets the snap instance name for DPM module Dqlite database.
    name: dpm

  server_certs:
    # Sets the path of cert file for DPM TLS endpoints.
    cert:

    # Sets the path of key file for DPM TLS endpoints.
    key:

  client_certs:
    # Sets the path of client cert file for DPM TLS endpoints.
    cert:

    # Sets the path of key file for DPM TLS endpoints.
    key:

  nats:
    # Sets the NATS service address.
    address: nats://127.0.0.1:9100

    # With ha, sets the NATS service proxy address
    proxy_address:

    # Sets the NATS streaming store root directory.
    store_root_dir: /var/lib/nms/streaming

    # Sets the NATS streaming maximum store in bytes.
    max_store_bytes: 10737418240

    # Sets the NATS streaming maximum memory in bytes.
    max_memory_bytes: 1073741824

    # Sets the NATS streaming maximum message in bytes.
    max_message_bytes: 1048576

integrations:
  # Sets the log level for Integrations.
  log_level: 

  # Sets the http server listen address for Integrations.
  address: unix:/var/run/nms/integrations.sock"


  dqlite:
    # Sets the address for Integrations module Dqlite database address.
    addr: 127.0.0.1:7892

    # Sets the path for Integrations module Dqlite database initialization schema file.
    schema: etc/nms/integrations/schema.sql

    # Sets the directory for Integrations module Dqlite database migration files.
    migrations_dir: /etc/nms/integrations/migrations

    # With ha, sets the join flag for Integrations module Dqlite database.
    join:

    # Sets verbosity level to debug for Integrations module Dqlite database.
    verbose:

    # Sets the snap instance name for Integrations module Dqlite database.
    name: integrations

  server_certs:
    # Sets the path of cert file for Integrations TLS endpoints.
    cert:

    # Sets the path of key file for Integrations TLS endpoints.
    key:

  client_certs:
    # Sets the path of client cert file for Integrations TLS endpoints.
    cert:

    # Sets the path of key file for Integrations TLS endpoints.
    key:


ingestion:

  # Sets the log level for Ingestion.
  log_level:

  # Sets the GRPC server listen address for agent Ingestion.
  grpc_addr: unix:/var/run/nms/ingestion_test.sock

  server_certs:
    # Sets the path of cert file for Ingestion TLS endpoints.
    cert: 

    # Sets the path of key file for Ingestion TLS endpoints.
    key:

clickhouse:

  # Sets the log level for ClickHouse.
  log_level:

  # Sets the address that will be used to connect to ClickHouse.
  address: tcp://127.0.0.1:9000


  # Note: Username and password should only be set, if you have custom defined username and password for ClickHouse.
  # Sets the username that will be used to connect to ClickHouse. 
  username:

  # Sets the password that will be used to connect to ClickHouse.
  password:

  # Activates or deactivates TLS for connecting to ClickHouse. 
  # Note: `tls_mode` will be deprecated in the future, use `tls` key to enable TLS connection for ClickHouse.
  tls_mode: true

  tls:
    # Sets the address (form <ip-address:port>)used to connect to ClickHouse with a TLS connection.
    address: tcp://127.0.0.1:9440

    # Activates or deactivates TLS verification of ClickHouse connection.
    skip_verify: false

    # Sets the path of the certificate used for TLS connections in PEM encoded format.
    cert_path:

    # Sets the path of the client key used for TLS connections in PEM encoded format.
    key_path:

    # Sets the path of the Certificate Authority installed on the system for verifying certificates.
    cert_ca: /etc/ssl/certs/ca-certificates.crt
  
  # Sets directory containing ClickHouse migration files.
  migrations_path: /usr/share/nms/clickhouse/migrations