Complete the steps in this guide to install NGINX Instance Manager.
This documentation applies to NGINX Instance Manager 2.0.0 and later.
Refer to the Offline Installation Guide if you need to install NGINX Instance Manager directly from package files.
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.
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
443for 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)
If you want to use SELinux, follow the steps in the SELinux Guide.
Complete the following steps to install NGINX Instance Manager from a public repository.
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
||Public certificate needed to install NGINX Plus from a repository.||Place in
||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
||License for the NGINX Instance Manager Server|
To download the license and certificate files, take the following steps:
sudo mkdir -p /etc/ssl/nginx cd /etc/ssl/nginx
Log in to the MyF5 Customer Portal and download the
nginx-manager.licfiles. The filenames might be different depending on your enrollment type.
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
/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/
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|
- Follow the instructions to install NGINX OSS or NGINX Plus.
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.
NGINX Instance Manager uses ClickHouse as a datastore for configuration settings and analytics information such as metrics, events, and alerts.
- Follow ClickHouse’s instructions to install ClickHouse for your distribution.
Copy and save the default ClickHouse user password for reference. You’ll need this password to access the ClickHouse client.
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:
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.repoand 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
To add an Apt repository for Instance Manager, run the following command:
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
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-nginxfile 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";
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
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
- (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.
For systemd systems, take the following steps to start or reload NGINX Instance Manager:
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
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
If NGINX is already running, reload it:
sudo service nginx reload
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
Start the NGINX Instance Manager service:
sudo systemctl start nms
NGINX Instance Manager components started this way run by default as the non-root
nmsuser inside the
nmsgroup, both of which are created during installation.
To verify the NGINX Instance Manager services are running, run the following command:
ps aufx | grep nms
The output should show processes for:
(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.
After you’ve installed and started NGINX Instance Manager, you can access the web interface by going to:
NGINX-INSTANCE-MANAGER-FQDN is the address of the host where you installed NGINX Instance Manager.
To see which version of Instance Manager is installed, run the following command:
yum info nms-instance-manager
dpkg -s nms-instance-manager
- License NGINX Instance Manager
- Add Users and Set Up Authentication
- Install and Configure NGINX Agent
- Upgrade NGINX Instance Manager