Installation Guide

Learn how to install F5 NGINX Management Suite, including the Instance Manager and API Connectivity Manager modules.

Add NGINX Management Suite Repo

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

  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 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 Instance Manager

Important:
If you haven’t done so already, complete the steps to prepare to install NGINX Management Suite before continuing.

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

    sudo yum install -y nms-instance-manager
    
  2. Enable the following NGINX Management Suite services:

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

    sudo systemctl start nms
    

    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
    

  1. To install the latest version of the NGINX Instance Manager module, run the following commands:

    sudo apt-get update
    sudo apt-get install -y nms-instance-manager
    
  2. Enable the following NGINX Management Suite services:

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

    sudo systemctl start nms
    

    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
    

Install NGINX API Connectivity Manager

Install the Management Plane

Important:
If you haven’t done so already, complete the steps to prepare to install NGINX Management Suite before continuing.

  1. To install the latest version of the NGINX Management Suite API Connectivity Manager module, run the following command:

    sudo yum -y install nms-api-connectivity-manager
    
  2. Enable the following 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-acm
    
  3. Start the NGINX Management Suite services:

    sudo systemctl start nms
    

    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
    

  1. To install the latest version of the NGINX Management Suite API Connectivity Manager module, run the following commands:

    sudo apt-get update
    sudo apt-get install -y nms-api-connectivity-manager
    
  2. Enable the following 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-acm
    
  3. Start the NGINX Management Suite services:

    sudo systemctl start nms
    

    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
    

Install the Data Plane

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

To configure the data plane host(s), take the following steps:

  1. Install NGINX Plus R21 or later.

  2. Install the njs module.

Install the Developer Portal

You can run the Developer Portal on one or more hosts. The Developer Portal requires a separate, dedicated host. Do not install Developer Portal on a host that is already running the management or data planes.

To set up the Developer Portal, take the following steps:


  1. Install NGINX Plus R21 or later.

  2. Install the njs module.

  3. Add the NGINX Management Suite Repo.

  4. Install the Developer Portal:

    sudo yum -y install nginx-devportal nginx-devportal-ui
    
  5. Install PostgreSQL:

    sudo yum install -y postgresql-server
    sudo postgresql-setup initdb
    
  6. Run the following command to configure the PostgreSQL host-based authentication (HBA) file:

    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
    
  7. Restart PostgreSQL:

    sudo systemctl restart postgresql
    
  8. Run the following commands to 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;"
    
  9. Start the Dev Portal:

    sudo systemctl start nginx-devportal
    

  1. Install NGINX Plus R21 or later.

  2. Install the njs module.

  3. Add the NGINX Management Suite Repo.

  4. Install the Developer Portal:

    sudo apt-get update
    sudo apt-get -y install nginx-devportal nginx-devportal-ui
    
  5. Install PostgreSQL:

    sudo apt-get install -y postgresql
    
  6. Run the following command to configure the PostgreSQL host-based authentication (HBA) file:

    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
    
  7. Restart PostgreSQL:

    sudo systemctl restart postgresql
    
  8. Run the following commands to 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;"
    
  9. Start the Dev Portal:

    sudo systemctl start nginx-devportal
    

Enable and Start NGINX Management Suite

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.
  • nms-acm: The NGINX API Connectivity Manager service.

To enable the NGINX Management Suite services, select the tab matching your deployment and run the following commands:

  1. Enable the NGINX Management Suite services for NGINX Instance Manager:

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

    sudo systemctl start nms
    

    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
    

  1. Enable the NGINX Management Suite services for NGINX Instance Manager and API Connectivity Manager:

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

    sudo systemctl start nms
    

    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
    

Access the Web Interface

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

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

Where NGINX-MANAGEMENT-SUITE-FQDN is the address of the host where you installed NGINX Management Suite.


How To Look Up the Installed Version

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

  • Look up the installed version of NGINX Instance Manager:

    yum info nms-instance-manager
    
  • Look up the installed version of NGINX Management Suite API Connectivity Manager:

    yum info nms-api-connectivity-manager
    

  • Look up the installed version of NGINX Instance Manager:

    dpkg -s nms-instance-manager
    
  • Look up the installed version of NGINX API Connectivity Manager:

    dpkg -s nms-api-connectivity-manager