Installation Guide

Follow the steps in this guide to install the NGINX Management Suite Instance Manager and API Connectivity Manager modules.

Overview

The NGINX Management Suite is a comprehensive family of management plane solutions that enable you to effectively scale, secure, and monitor your applications and APIs. At its core is the NGINX Management Suite Instance Manager module, which lets you track, secure, and configure your NGINX OSS and NGINX Plus instances. Instance Manager is available as a standalone product and is automatically included when you license any other NGINX Management Suite modules.


Prepare Your Platform

Prerequisites

To install the NGINX Management Suite, you need the following:

  • A trial or paid subscription for NGINX Management Suite. Sign up for NGINX Management Suite at MyF5.

  • A Linux instance for hosting the NGINX Management Suite and modules.

  • An installed version of NGINX Plus or NGINX OSS.

  • Ensure any network firewall is open for access from external systems. NGINX Management Suite uses port 443 for both the gRPC and API/web interfaces.

Install NGINX

The NGINX Management Suite platform uses NGINX as a frontend proxy and for managing user access.

Supported NGINX versions

NGINX Management Suite supports the following NGINX versions:

Module Version NGINX OSS NGINX Plus
Instance Manager 2.7.0 and later
2.0.0–2.6.0
1.18–1.22.1
1.18–1.21.6
R21–R28
R21–R27
ACM - Management Plane 1.4.0 and later
1.0.0–1.3.1
1.18–1.22.1
1.18–1.21.6
R24–R28
R24–R27
ACM - Data Plane and Dev Portal 1.4.0 and later
1.0.0–1.3.1
Not supported
Not supported
R24–R28
R21–R27
Supported Linux distributions

The NGINX Management Suite gateway supports the following Linux distributions:

Distribution Version Architecture Instance Manager ACM Notes
Amazon Linux 2 LTS x86_64 2.0.0 and later 1.0.0 and later
CentOS 7.4 and later in the 7.x family x86_64 2.0.0 and later 1.0.0 and later
Debian 10
11
x86_64
x86_64
2.0.0 and later
2.0.0 and later
1.0.0 and later
1.0.0 and later
Oracle Linux 7.4 and later in the 7.x family
8.0 and later in the 8.0.x family
x86_64
x86_64
2.0.0 and later
2.6.0 and later
1.0.0 and later
Not supported
RHEL 7.4 and later in the 7.x family
8.x and later in the 8.x family
9.x and later in the 9.x family
x86_64
x86_64
x86_64
2.0.0 and later
2.0.0 and later
2.6.0 and later
1.0.0 and later
1.0.0 and later
Not supported
Ubuntu 18.04
20.04
22.04
x86_64
x86_64
x86_64
2.0.0 and later
2.0.0 and later
2.3.0 and later
1.0.0 and later
1.0.0 and later
1.0.0 and later
Configuration Management for App Protect WAF is not compatible with Ubuntu 22.04.

Install ClickHouse

NGINX Management Suite uses ClickHouse as a datastore for configuration settings and analytics information such as metrics, events, and alerts.

Default ClickHouse values

NGINX Management Suite uses the following default values for ClickHouse:

Important:
You can customize these settings. However, if you use custom settings, make sure to follow the Configure ClickHouse instructions to update the nms.conf file after you’ve installed NMS; otherwise NMS won’t be able to connect to ClickHouse.

Configuration Default Notes
clickhouse.address tcp://localhost:9000
clickhouse.username
clickhouse.password
clickhouse.tls_mode false
clickhouse.tls.address tcp://localhost:9440
clickhouse.tls.skip_verify false clickhouse.tls.skip_verify should be used only for self-signed certificates and is never recommended for production use. When set to true, certificates are not verified, which exposes the connection to man-in-the-middle attacks.
clickhouse.tls.key_path
clickhouse.tls.cert_path
clickhouse.tls.ca_path /etc/ssl/certs/ca-certificates.crt The default value for clickhouse.tls.ca_path works out-of-the-box for Ubuntu and Debian. You’ll need to configure a different Certificate Authority for other distributions. Refer to your distribution’s documentation for additional information.

To install and enable ClickHouse, take the following steps:

  1. Follow ClickHouse’s instructions to install ClickHouse 21.3.20.1 or later for your distribution.

    Important:
    Copy and save the ClickHouse user password for future reference. You’ll need this password to access the ClickHouse client.
    Important:
    We recommend using lts releases of ClickHouse. You can replace stable with lts in any ClickHouse commands to use the lts release.
  2. Verify ClickHouse is running:

    sudo service clickhouse-server status
    
  3. Enable ClickHouse so that it starts automatically if the server is restarted:

    sudo systemctl enable clickhouse-server
    

(Optional) Install and Configure Vault

NGINX Management Suite can use Vault as a datastore for secrets.

To install and enable Vault, take the following steps:

Add NGINX Management Suite Repo

To install NGINX Management Suite, you need to add the official NGINX repo to pull the packages from. Which repo you need to add – Yum or Apt – depends on your Linux distribution.

Add .crt and .key files to etc/ssl/nginx

Tip:
If you installed NGINX Plus for the NGINX Management Suite host, you may have completed these steps already, in which case you can skip to the Add the NGINX Management Suite Repo to Yum or Apt section.

To access the NGINX Management Suite repo, you’ll need to add appropriate cert and key files to the etc/ssl/nginx folder.

  1. Create the /etc/ssl/nginx/ directory:

    sudo mkdir -p /etc/ssl/nginx
    
  2. Log in to MyF5, or follow the link in the trial activation email, and download the NMS repo .crt and .key files:

    • nginx-mgmt-suite-trial.key
    • nginx-mgmt-suite-trial.crt

    The filenames might be different, depending on your subscription type.

  3. Rename and move the NMS .crt and .key files:

    sudo mv nginx-mgmt-suite-trial.key /etc/ssl/nginx/nginx-repo.key
    sudo mv nginx-mgmt-suite-trial.crt /etc/ssl/nginx/nginx-repo.crt
    

Add NGINX Management Suite Repo to Yum or Apt

Select the tab matching your distribution type, then follow the instructions to add the NGINX Management Suite repo.


  1. Add the NGINX Management Suite Yum repository:

    sudo wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/nms.repo
    
    • RHEL 8:

      If you’re installing on RHEL 8 and using the distro’s NGINX, run the following commands to use the new version of NGINX (1.20 at the time of this update):

      sudo yum module disable nginx:1.14
      sudo yum module enable nginx:1.20
      
  2. Add the NGINX Signing Key to the Yum repository:

    curl -o /tmp/nginx_signing.key https://nginx.org/keys/nginx_signing.key
    sudo rpmkeys --import /tmp/nginx_signing.key
    
  3. (Optional) Alternatively, create a file called /etc/yum.repos.d/nms.repo and paste in the following configuration:

    [nms]
    name=NGINX Management Suite
    baseurl=https://pkgs.nginx.com/nms/centos/$releasever/$basearch/
    sslclientcert=/etc/ssl/nginx/nginx-repo.crt
    sslclientkey=/etc/ssl/nginx/nginx-repo.key
    enabled=1
    
    • Amazon Linux 2:

      If you’re installing on Amazon Linux 2, the baseurl should be: baseurl=https://pkgs.nginx.com/nms/amzn2/$releasever/$basearch/.

  1. Add the NGINX Management Suite Apt repository:

    • Debian:

      printf "deb https://pkgs.nginx.com/nms/debian `lsb_release -cs` nginx-plus\n" | sudo tee /etc/apt/sources.list.d/nms.list
      sudo wget -q -O /etc/apt/apt.conf.d/90pkgs-nginx https://cs.nginx.com/static/files/90pkgs-nginx
      
    • Ubuntu:

      printf "deb https://pkgs.nginx.com/nms/ubuntu `lsb_release -cs` nginx-plus\n" | sudo tee /etc/apt/sources.list.d/nms.list
      sudo wget -q -O /etc/apt/apt.conf.d/90pkgs-nginx https://cs.nginx.com/static/files/90pkgs-nginx
      
  2. Add the NGINX Signing Key to Apt repository:

    wget -O /tmp/nginx_signing.key https://cs.nginx.com/static/keys/nginx_signing.key
    sudo apt-key add /tmp/nginx_signing.key
    
  3. (Optional) As an alternative to downloading the 90pkgs-nginx file from our website, you can upload the file’s contents using any other means. The content of the file should match the following:

    Acquire::https::pkgs.nginx.com::Verify-Peer "true";
    Acquire::https::pkgs.nginx.com::Verify-Host "true";
    Acquire::https::pkgs.nginx.com::SslCert "/etc/ssl/nginx/nginx-repo.crt";
    Acquire::https::pkgs.nginx.com::SslKey "/etc/ssl/nginx/nginx-repo.key";
    

Install NGINX Management Suite Modules

Select the tab for the NGINX Management Suite module that you want to install.


Install Instance Manager

To install the latest version of the Instance Manager module, run the following command:

  • CentOS, RHEL, RPM-Based

    sudo yum install -y nms-instance-manager
    
  • Debian, Ubuntu, Deb-Based

    sudo apt-get update
    sudo apt-get install -y nms-instance-manager
    
Important

The Instance Manager's administrator username (default is admin) and generated password are displayed in the terminal during the installation. You should make a note of the password and store it securely.

To set up Instance Manager configuration management for NGINX App Protect WAF, refer to Set Up App Protect WAF Configuration Management.

Post-Installation Steps

The following steps may be optional, depending on your installation configuration.

  1. (Optional) If you used a custom address, username, or password or enabled TLS when installing ClickHouse, follow the steps in the Configure ClickHouse guide to update the nms.conf file. If you don’t do so, NGINX Management Suite won’t be able to connect to ClickHouse.

  2. (Optional) If you use Vault, follow the steps in the Configure Vault guide to update the nms.conf file. If you don’t do so, NGINX Management Suite won’t be able to connect to Vault.

Start and Enable the NMS Services

To enable and start the NGINX Mangement Suite and Instance Manager services, take the following steps:

  1. Enable the NGINX Management Suite services:

    sudo systemctl enable nms
    sudo systemctl enable nms-core
    sudo systemctl enable nms-dpm
    sudo systemctl enable nms-ingestion
    sudo systemctl enable nms-integrations
    
  2. Start the NGINX Management Suite services:

    sudo systemctl start nms
    sudo systemctl start nms-core
    sudo systemctl start nms-dpm
    sudo systemctl start nms-ingestion
    sudo systemctl start nms-integrations
    

    NGINX Management Suite components started this way run by default as the non-root nms user inside the nms group, both of which are created during installation.

  3. To verify the NGINX Management Services are running, run the following command:

    ps aufx | grep nms
    
  4. Restart the NGINX web server:

    sudo systemctl restart nginx
    
Overview: NGINX Management Suite services

The following table lists the services that are installed with NGINX Management Suite. The “NMS Platform” services are installed with Instance Manager, which is the foundation for the NGINX Management Suite platform.

Service Module Description
nms NMS Platform A pseudo service used to start the other nms-* services.
nms-core NMS Platform The core service hosts the APIs for setting up and configuring the control plane and analyzing analytics information (metrics, events, and alerts).
nms-dpm NMS Platform The data plane manager (DPM) service hosts the APIs for managing and configuring NGINX instances on the data plane. The DPM also monitors the state of data plane resources and generates reports and event messages.
nms-ingestion NMS Platform The ingestion service collects metrics, security violations, and events from NGINX Agents that aren’t sent to the data plane manager. These metrics can be forwarded to external datastores.
nms‑integrations NMS Platform Note: This service is for future integrations; no user management or configuration is needed at this time.
nms-acm API Connectivity Manager The API Connectivity Manager service.

Dependencies with Instance Manager

API Connectivity Manager (ACM) depends on the platform capabilities of Instance Manager. The following table lists the minimum versions of Instance Manager required for ACM:

The following table lists the minimum versions of Instance Manager required for ACM:

API Connectivity Manager Instance Manager Dependency
ACM 1.4.0–1.4.1 NIM 2.7.0–2.8.0
ACM 1.3.0–1.3.1 NIM 2.6.0 and later
ACM 1.1.0–1.2.0 NIM 2.4.0 and later
ACM 1.0.0 NIM 2.3.0 and later

To ensure ACM’s new features work correctly, you may need to install or upgrade Instance Manager to the minimum version specified. If Instance Manager is not installed, ACM will install the latest version. If the installed version is below the minimum required version, ACM will upgrade Instance Manager to the latest version. Otherwise, ACM will leave Instance Manager unchanged.

Important:
If you’re installing ACM in an offline environment and the minimum required version of Instance Manager is not installed, the ACM installer will exit. You’ll need to install Instance Manager manually before installing ACM.

Install ACM on Management Plane

To install the latest version of API Connectivity Manager, run the following command:

  • CentOS, RHEL, RPM-Based

    sudo yum -y install nms-api-connectivity-manager
    
  • Debian, Ubuntu, Deb-Based

    sudo apt-get update
    sudo apt-get install -y nms-api-connectivity-manager
    

Post-Installation Steps

The following steps may be optional, depending on your installation configuration.

  1. (Optional) If you used a custom address, username, or password or enabled TLS when installing ClickHouse, follow the steps in the Configure ClickHouse guide to update the nms.conf file. If you don’t do so, NGINX Management Suite won’t be able to connect to ClickHouse.

  2. (Optional) If you use Vault, follow the steps in the Configure Vault guide to update the nms.conf file. If you don’t do so, NGINX Management Suite won’t be able to connect to Vault.

Start and Enable NMS Services

To enable and start the NGINX Management Suite and API Connectivity Manager services, take the following steps:

  1. Enable the NGINX Management Suite services:

    sudo systemctl enable nms
    sudo systemctl enable nms-core
    sudo systemctl enable nms-dpm
    sudo systemctl enable nms-ingestion
    sudo systemctl enable nms-integrations
    sudo systemctl enable nms-acm
    
  2. Start the NGINX Management Suite services:

    sudo systemctl start nms
    sudo systemctl start nms-core
    sudo systemctl start nms-dpm
    sudo systemctl start nms-ingestion
    sudo systemctl start nms-integrations
    sudo systemctl start nms-acm
    

    NGINX Management Suite components started this way run by default as the non-root nms user inside the nms group, both of which are created during installation.

  3. To verify the NGINX Management Suite services are running, run the following command:

    ps aufx | grep nms
    
  4. Restart the NGINX web server:

    sudo systemctl restart nginx
    
Overview: NGINX Management Suite services

The following table lists the services that are installed with NGINX Management Suite. The “NMS Platform” services are installed with Instance Manager, which is the foundation for the NGINX Management Suite platform.

Service Module Description
nms NMS Platform A pseudo service used to start the other nms-* services.
nms-core NMS Platform The core service hosts the APIs for setting up and configuring the control plane and analyzing analytics information (metrics, events, and alerts).
nms-dpm NMS Platform The data plane manager (DPM) service hosts the APIs for managing and configuring NGINX instances on the data plane. The DPM also monitors the state of data plane resources and generates reports and event messages.
nms-ingestion NMS Platform The ingestion service collects metrics, security violations, and events from NGINX Agents that aren’t sent to the data plane manager. These metrics can be forwarded to external datastores.
nms‑integrations NMS Platform Note: This service is for future integrations; no user management or configuration is needed at this time.
nms-acm API Connectivity Manager The API Connectivity Manager service.


Install ACM Data Plane

Platform Requirements

API Connectivity Manager requires one or more data plane hosts for the API Gateway.

The data plane platform has the following requirements:

Supported Linux distributions

The NGINX Management Suite gateway supports the following Linux distributions:

Distribution Version Architecture Instance Manager ACM Notes
Amazon Linux 2 LTS x86_64 2.0.0 and later 1.0.0 and later
CentOS 7.4 and later in the 7.x family x86_64 2.0.0 and later 1.0.0 and later
Debian 10
11
x86_64
x86_64
2.0.0 and later
2.0.0 and later
1.0.0 and later
1.0.0 and later
Oracle Linux 7.4 and later in the 7.x family
8.0 and later in the 8.0.x family
x86_64
x86_64
2.0.0 and later
2.6.0 and later
1.0.0 and later
Not supported
RHEL 7.4 and later in the 7.x family
8.x and later in the 8.x family
9.x and later in the 9.x family
x86_64
x86_64
x86_64
2.0.0 and later
2.0.0 and later
2.6.0 and later
1.0.0 and later
1.0.0 and later
Not supported
Ubuntu 18.04
20.04
22.04
x86_64
x86_64
x86_64
2.0.0 and later
2.0.0 and later
2.3.0 and later
1.0.0 and later
1.0.0 and later
1.0.0 and later
Configuration Management for App Protect WAF is not compatible with Ubuntu 22.04.

Install Developer Portal

Platform Requirements

The Developer Portal has the following platform requirements:

  • A dedicated Linux host. Do not install the Developer Portal on a host that is serving as a management or data plane.

  • NGINX Plus R24 or later

    Supported Linux distributions

    The Developer Portal supports the following Linux distributions:

    Distribution Version Platform ACM Developer Portal
    Amazon Linux 2 LTS x86_64 1.0.0 and later
    CentOS 7.4 and later in the 7.x family x86_64 1.0.0 and later
    Debian 10
    11
    x86_64
    x86_64
    1.0.0 and later
    1.0.0 and later
    Oracle Linux 7.4 and later in the 7.x family x86_64 1.0.0 and later
    RHEL 7.4 and later in the 7.x family
    8.x
    x86_64
    x86_64
    1.0.0 and later
    1.0.0 and later
    Ubuntu 18.04
    20.04
    x86_64
    x86_64
    1.0.0 and later
    1.0.0 and later
  • NGINX njs module

  • A PostgreSQL or SQLite database to store configuration settings and analytics information. (Step 3 below)

Installation Steps

  1. Follow the steps to add the NGINX Management Suite Repo to Yum or Apt.

  2. Run the following command(s) for your Linux distribution to install the Developer Portal:

    • CentOS, RHEL, RPM-based

      sudo yum -y install nginx-devportal nginx-devportal-ui
      
    • Debian, Ubuntu, Deb-based

      sudo apt-get update
      sudo apt-get -y install nginx-devportal nginx-devportal-ui
      
  3. Select one of the following database options for your installation:

    Install PostgreSQL

    To use PostgreSQL for the Dev Portal database, take the following steps:

    1. Run the following command(s) to install PostgreSQL:

      • CentOS, RHEL, RPM-based

        sudo yum install -y postgresql-server
        sudo postgresql-setup initdb
        
      • Debian, Ubuntu, Deb-based

        sudo apt-get install -y postgresql
        
    2. Configure the PostgreSQL host-based authentication (HBA) file:

      • CentOS, RHEL, RPM-based

        cat << EOF | sudo tee /var/lib/pgsql/data/pg_hba.conf
        
        # TYPE DATABASE USER ADDRESS METHOD
        
        local all postgres peer
        local all all md5
        # IPv4 local connections:
        host all all 127.0.0.1/32 md5
        # IPv6 local connections:
        host all all ::1/128 md5
        EOF
        
      • Debian, Ubuntu, Deb-based

        cat << EOF | sudo tee /etc/postgresql/<pg_version>/main/pg_hba.conf
        
        # TYPE DATABASE USER ADDRESS METHOD
        
        local all postgres peer
        local all all md5
        # IPv4 local connections:
        host all all 127.0.0.1/32 md5
        # IPv6 local connections:
        host all all ::1/128 md5
        EOF
        
    3. Restart PostgreSQL:

      sudo systemctl restart postgresql
      
    4. Create the devportal database, add the nginxdm user, and assign privileges:

      sudo -u postgres createdb devportal
      sudo -u postgres psql -c "CREATE USER nginxdm WITH LOGIN PASSWORD 'nginxdm';"
      sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON DATABASE devportal TO nginxdm;"
      
    Install SQLite

    To use SQLite for the Dev Portal database, take the following steps:

    1. Set up the SQLite database:

      echo 'DB_TYPE="sqlite"' | sudo tee -a /etc/nginx-devportal/devportal.conf
      echo 'DB_PATH="/var/lib/nginx-devportal"' | sudo tee -a /etc/nginx-devportal/devportal.conf
      
  4. Start the Dev Portal:

    sudo systemctl start nginx-devportal
    

Install Security Monitoring Module

Dependencies with Instance Manager

The Security Monitoring module requires the following versions of Instance Manager to be installed on the management plane:

Security Monitoring Instance Manager
1.2.0 and later 2.8.0 and later
1.1.0 and later 2.7.0 and later
1.0.0 and later 2.6.0 and later
Important:
The Security Monitoring module installation does not automatically install or upgrade Instance Manager. You’ll need to manually install Instance Manager, or upgrade it to a version supported for use with Security Monitoring.

Installation Steps

Take the following steps to install the Security Monitoring module on your NGINX Management Suite host.

  1. To install the latest version of the Security Monitoring module, run the following command:

    • CentOS, RHEL, RPM-Based

      sudo yum -y install nms-sm
      
    • Debian, Ubuntu, Deb-Based

      sudo apt-get update
      sudo apt-get install -y nms-sm
      
  2. Restart the NGINX Management Suite services:

    sudo systemctl restart nms
    sudo systemctl restart nms-core
    sudo systemctl restart nms-dpm
    sudo systemctl restart nms-ingestion
    sudo systemctl restart nms-integrations
    

    NGINX Management Suite components started this way run by default as the non-root nms user inside the nms group, both of which are created during installation.

  3. To verify the NGINX Management Services are running, run the following command:

    ps aufx | grep nms
    
  4. Restart the NGINX web server:

    sudo systemctl restart nginx
    

Set Up Data Plane Instances for Security Monitoring

Follow the steps in the Setup Guide to set up your NGINX App Protect WAF data plane instances for use with Security Monitoring.


Access the Web Interface

To access the web interface, go to the FQDN for your NGINX Management Suite host and log in:

  • https://<NGINX-MANAGEMENT-SUITE-FQDN>/ui/

How To Look Up the Installed Version

To see which version of an NGINX Management Suite module is installed, run the following commands:

  • Instance Manager:

    yum info nms-instance-manager
    
  • API Connectivity Manager:

    yum info nms-api-connectivity-manager
    
  • Security Monitoring module:

    yum info nms-sm
    

  • Instance Manager:

    dpkg -s nms-instance-manager
    
  • API Connectivity Manager:

    dpkg -s nms-api-connectivity-manager
    
  • Security Monitoring module:

    dpkg -s nms-sm
    

Troubleshooting

For help with common issues and suggested solutions and workarounds, refer to the NGINX Management Suite Troubleshooting Guide.


What’s Next