Install NGINX Instance Manager

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:
If you need to install NGINX Instance Manager directly from package files — for instance, in an offline environment — refer to the Offline Installation Guide for instructions.

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 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.


Download License Files

Log in to the MyF5 Customer Portal and download the NGINX Instance Manager license files:

  • NGINX-Instance-Manager.lic: The NGINX Instance Manager license. This file might have a different name.


Install NGINX Instance Manager

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

  1. Log in to the MyF5 Customer Portal and download the NGINX repo key bundle files:

    • nginx-repo.crt: This file is used to access the installation repository. The apt and yum repository files reference this file and the private key file to pull packages. You can place these files in /etc/ssl/nginx following the instructions for setting up the repository below.

    • nginx-repo.key: This key file is used with the crt file to access the installation repository.

  2. Install NGINX Plus or NGINX OSS. See the Technical Specifications guide for the supported versions. Also, see the Configure Authentication guide to see which auth options are available for NGINX Plus and NGINX OSS.

  3. Install ClickHouse from the official repositories. Follow the instructions for your distribution.

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

    sudo mkdir /etc/ssl/nginx
    cd /etc/ssl/nginx
    
  5. Copy the files to the /etc/ssl/nginx/ directory:

    sudo cp nginx-*.crt /etc/ssl/nginx/nginx-repo.crt
    sudo cp nginx-*.key /etc/ssl/nginx/nginx-repo.key
    
  6. 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
    
  7. Install the repository file:

    sudo wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/nms.repo
    
    • (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
      

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

    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";
      
  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):

    Note:

    If you’re not using the distro’s NGINX, or if you’ve installed NGINX Plus, you can skip this step.

    Make sure to review the Technical Specifications guide for the supported versions of NGINX and NGINX Plus.

    sudo yum module disable nginx:1.14
    sudo yum module enable nginx:1.20
    
  9. Install NGINX Instance Manager:

    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
    

    sudo apt-get install -y nms-instance-manager
    
  10. Continue to the Start and Enable NGINX Instance Manager section.



Start and Enable NGINX Instance Manager

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

  1. Start the ClickHouse database server:

    sudo systemctl start clickhouse-server
    
  2. Start the NGINX web server:

    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
    
  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. (Optional) If a new admin password was generated for you, change this password with your own as soon as possible following the steps in the Configure Authentication guide.

Note:
After you’ve 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.


Upgrading NGINX Instance Manager

To upgrade NGINX Instance Manager, take the following steps:

  1. Install NGINX Instance Manager:

    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
    

    sudo apt-get install -y nms-instance-manager
    
  2. On the data plane host(s), upgrade and restart the NGINX Agent:

    curl -k https://<NGINX-INSTANCE-MANAGER-FQDN>/install/nginx-agent | sudo su -
    
    sudo systemctl restart nginx-agent
    
    See Also:
    See the NGINX Agent Installation Guide for other installation options, such as wget or installing from package files.
  3. Reload NGINX:

    nginx -s reload
    
  4. Reapply the SELinux policy if it’s enabled:

    sudo semodule -n -i /usr/share/selinux/packages/nms.pp
    sudo /usr/sbin/load_policy
    sudo restorecon -F -R /usr/bin/nms-core
    sudo restorecon -F -R /usr/bin/nms-dpm
    sudo restorecon -F -R /usr/bin/nms-ingestion
    sudo restorecon -F -R /usr/lib/systemd/system/nms.service
    sudo restorecon -F -R /usr/lib/systemd/system/nms-core.service
    sudo restorecon -F -R /usr/lib/systemd/system/nms-dpm.service
    sudo restorecon -F -R /usr/lib/systemd/system/nms-ingestion.service
    sudo restorecon -F -R /var/lib/nms/modules/manager.json
    sudo restorecon -F -R /var/lib/nms/modules.json
    sudo restorecon -F -R /var/lib/nms/streaming
    sudo restorecon -F -R /var/lib/nms
    sudo restorecon -F -R /var/lib/nms/dqlite
    sudo restorecon -F -R /var/run/nms
    sudo restorecon -F -R /var/lib/nms/modules
    sudo restorecon -F -R /var/log/nms
    
  5. Start the following NGINX Instance Manager services:

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


What’s Next