Installation Guide

Complete the steps in this guide to install NGINX Instance Manager.

This documentation applies to NGINX Instance Manager 2.0.0 and later.

See Also:
Refer to the Offline Installation Guide if you need to install NGINX Instance Manager directly from package files.

Overview

NGINX Instance Manager allows you to effortlessly discover, configure, and scale NGINX OSS and NGINX Plus instances. Install NGINX Instance Manager in just 10 seconds and overcome NGINX sprawl in your organization.

Prerequisites

Before installing NGINX Instance Manager, see the Technical Specifications guide for system requirements and recommendations.

To complete this tutorial, you need the following:

  • A trial or paid subscription for NGINX Instance Manager. Sign up for NGINX Instance Manager at MyF5.

  • A Linux instance for hosting NGINX Instance Manager

    • See the the Technical Specifications guide for the supported distributions and sizing recommendations.
    • Ensure any network firewall is open for access from external systems. NGINX Instance Manager uses port 443 for both the gRPC and API/web interfaces.

  • NGINX Instance Manager installation packages or binaries

  • NGINX Instance Manager license files

    • Download NGINX Instance Manager license file (for production use).
    • (Optional) Download repository certificate and key (for repo access).

  • An installed version of NGINX Plus (versions R21–R25) or NGINX OSS (version 1.18 or 1.19)

See Also:
If you want to use SELinux, follow the steps in the SELinux Guide.


Install NGINX Instance Manager

Complete the following steps to install NGINX Instance Manager from a public repository.

1. Download License and Certificate Files

Your NGINX Instance Manager enrollment includes the following license and certificate files. The filenames might be different depending on your enrollment type.

Table: License and Certificate Files

File Description Notes
nginx-repo.crt Public certificate needed to install NGINX Plus from a repository. Place in /etc/ssl/nginx
nginx-repo.key Private key needed to install NGINX Plus from a repository. NGINX Plus is included as a frontend proxy for NGINX Instance Management Server. Place in /etc/ssl/nginx
nginx-manager.lic License for the NGINX Instance Manager Server

To download the license and certificate files, take the following steps:

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

    sudo mkdir -p /etc/ssl/nginx
cd /etc/ssl/nginx

  2. Log in to the MyF5 Customer Portal and download the nginx-repo.crt, nginx-repo.key, and nginx-manager.lic files. The filenames might be different depending on your enrollment type.

  3. Install the required certificate authority dependencies:

    sudo yum install ca-certificates


    sudo apt-get install apt-transport-https lsb-release ca-certificates

sudo wget https://nginx.org/keys/nginx_signing.key

sudo apt-key add nginx_signing.key

  4. Copy the nginx-repo.crt and nginx-repo.key to the /etc/ssl/nginx/ directory. These are the files you downloaded from MyF5 in step 1 of this section.

    sudo cp nginx-*.crt /etc/ssl/nginx/
sudo cp nginx-*.key /etc/ssl/nginx/


2. Install NGINX Plus or NGINX OSS

The NGINX Instance Manager server uses NGINX as a frontend proxy and supports the following versions of NGINX Plus and NGINX OSS:


Table: NGINX Instance Manager – Supported NGINX Versions

NGINX Model Supported Versions
NGINX OSS 1.18 and later
NGINX Plus R21 and later


Note:
NGINX Instance Manager uses NGINX to manage user access. Refer to the Set up Authentication guide to find out what options are available with NGINX Plus and with NGINX OSS.

3. Install ClickHouse

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

Important:
Copy and save the default ClickHouse user password for reference. You’ll need this password to access the ClickHouse client.


4. Add Repository

To install NGINX Instance Manager from a public repo, you need to add a Yum or Apt repository, which one depends on your Linux distrubtion.

To add a Yum or Apt repository, take the following steps:

  1. To add a Yum repository for Instance Manager, run the following command:

    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

    • (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

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

  1. To add an Apt repository for Instance Manager, run the following command:

    • Debian:

      printf "deb https://pkgs.nginx.com/nms/debian stable 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

sudo apt-get update

    • 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

sudo apt-get update

    • (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";

5. Install NGINX Instance Manager

  1. To install or upgrade Instance Manager from the Yum repository, run the following command:

    sudo yum install -y nms-instance-manager

    If you encounter a signing key error, try the following steps:

    curl -o /tmp/nginx_signing.key https://nginx.org/keys/nginx_signing.key

sudo rpmkeys --import /tmp/nginx_signing.key

  1. To install or upgrade Instance Manager from the Apt repository, run the following command:

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


Configure ClickHouse Connection

  • (Optional) If you specified a non-default username and password when installing ClickHouse, or if your ClickHouse installation uses TLS, follow the steps in Configure ClickHouse before proceeding. You need to update the Instance Manager configuration file with the proper ClickHouse values.


Enable and Start NGINX Instance Manager

For systemd systems, take the following steps to start or reload NGINX Instance Manager:

  1. Start the ClickHouse database server if it’s not running:

    • Check to see if the ClickHouse server is running:

      sudo systemctl status clickhouse-server

    • If necessary, start the ClickHouse server:

      sudo systemctl start clickhouse-server

  2. Start or restart the NGINX web server:

    • Check to see if the NGINX is running:

      sudo systemctl status nginx

    • Start NGINX if it’s not running:

      sudo systemctl start nginx

      —Or—

    • If NGINX is already running, reload it:

      sudo service nginx reload

  3. Enable the following NGINX Instance Manager services:

    sudo systemctl enable nms-core
sudo systemctl enable nms-dpm
sudo systemctl enable nms-ingestion
sudo systemctl enable nms

    Description of the services:

    • nms-core: The core service hosts the APIs for setting up and configuring the control plane and analyzing analytics information (metrics, events, and alerts).
    • nms-dpm: 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: 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 : A pseudo service used to start the the other nms-* services.

  4. Start the NGINX Instance Manager service:

    sudo systemctl start nms

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

  5. To verify the NGINX Instance Manager services are running, run the following command:

    ps aufx | grep nms

    The output should show processes for:

    • nms-core
    • nms-dpm
    • nms-ingestion

  6. (Optional) If a new admin password was generated for you, change this password with your own as soon as possible. To do so, follow the steps in the Set up Authentication guide.



Access the Web Interface

After you’ve installed and started NGINX Instance Manager, you can access the web interface by going to:

  • https://<NGINX-INSTANCE-MANAGER-FQDN>/ui/

Where NGINX-INSTANCE-MANAGER-FQDN is the address of the host where you installed NGINX Instance Manager.



How To Look Up the Installed Version

To see which version of Instance Manager is installed, run the following command:

yum info nms-instance-manager


dpkg -s nms-instance-manager


What’s Next