Offline Installation Guide

Installation instructions for NGINX Management Suite – including NGINX Instance Manager and NGINX API Connectivity Manager – in environments without internet access.

Overview

Complete the steps in this guide to install NGINX Management Suite modules directly from package files. You’ll need to get the package files from the MyF5 Customer Portal, or you can use the package files provided to you from your NGINX Sales Team.

Offline Dependencies

NGINX Management Suite has both local and external dependencies. Before installing an NGINX Management Suite module, make sure to install these local and external dependencies.

Local Dependencies

Local dependencies are common Linux packages like curl or openssl, which most Linux distributions include by default. These dependencies are installed automatically by your package manager when installing an NGINX Management Suite module. Without internet access, you need to ensure that your package manager can use a local package repository, such as your distribution DVD/ISO image or internal network mirror. Refer to your Linux distribution documentation for more details.

Note:
RedHat on AWS: If you’re using Amazon Web Services and, for security reasons, you can’t attach remote or local RedHat package repositories, you can download the necessary packages on another RedHat machine and copy them to your machine. To do this, you can use the yumdownloader utility: https://access.redhat.com/solutions/10154.

External Dependencies

External dependencies are packages that aren’t available by default in regular Linux distributions.

Before installing NGINX Management Suite on an offline system, you must manually download the external dependencies and copy them to your machine.

1. To download the external dependencies, run the fetch-external-dependencies.sh provided below. This script downloads the necessary packages to a tar.gz archive.

   As an argument to the script, specify the Linux distribution for the packages:

   • ubuntu18.04
   • ubuntu20.04
   • centos7
   • centos8
   • rhel7
   • rhel8

   ./fetch-external-dependencies <linux distribution>
   

   For example:

   ./fetch-external-dependencies ubuntu18.04
   

   
   
   fetch-external-dependencies.sh

   fetch-external-dependencies.sh

   #!/bin/bash
   # This script is used to fetch external packages that are not available in standard Linux distribution
   
   # Example: ./fetch-external-dependencies ubuntu18.04
   # Script will create nms-dependencies-ubuntu18.04.tar.gz in local directory which can be copied
   # into target machine and packages inside can be installed manually
   
   set -eo pipefail
   
   # current dir
   PACKAGE_PATH="."
   CLICKHOUSE_VERSION=21.3.19.1
   
   mkdir -p $PACKAGE_PATH
   
   declare -A CLICKHOUSE_REPO
   CLICKHOUSE_REPO['ubuntu18.04']="https://packages.clickhouse.com/deb/pool/lts/"
   CLICKHOUSE_REPO['ubuntu20.04']="https://packages.clickhouse.com/deb/pool/lts/"
   CLICKHOUSE_REPO['centos7']="https://packages.clickhouse.com/rpm/lts/"
   CLICKHOUSE_REPO['centos8']="https://packages.clickhouse.com/rpm/lts/"
   CLICKHOUSE_REPO['rhel7']="https://packages.clickhouse.com/rpm/lts/"
   CLICKHOUSE_REPO['rhel8']="https://packages.clickhouse.com/rpm/lts/"
   
   declare -A NGINX_REPO
   NGINX_REPO['ubuntu18.04']="https://nginx.org/packages/mainline/ubuntu/pool/nginx/n/nginx/"
   NGINX_REPO['ubuntu20.04']="https://nginx.org/packages/mainline/ubuntu/pool/nginx/n/nginx/"
   NGINX_REPO['centos7']="https://nginx.org/packages/mainline/centos/7/x86_64/RPMS/"
   NGINX_REPO['centos8']="https://nginx.org/packages/mainline/centos/8/x86_64/RPMS/"
   NGINX_REPO['rhel7']="https://nginx.org/packages/mainline/rhel/7/x86_64/RPMS/"
   NGINX_REPO['rhel8']="https://nginx.org/packages/mainline/rhel/8/x86_64/RPMS/"
   
   CLICKHOUSE_KEY="https://packages.clickhouse.com/rpm/lts/repodata/repomd.xml.key"
   NGINX_KEY="https://nginx.org/keys/nginx_signing.key"
   
   declare -A CLICKHOUSE_PACKAGES
   # for Clickhouse package names are static between distributions
   # we use ubuntu/centos entries as placeholders
   CLICKHOUSE_PACKAGES['ubuntu']="
   clickhouse-server_${CLICKHOUSE_VERSION}_all.deb
   clickhouse-common-static_${CLICKHOUSE_VERSION}_amd64.deb"
   
   CLICKHOUSE_PACKAGES['centos']="
   clickhouse-server-${CLICKHOUSE_VERSION}-2.noarch.rpm
   clickhouse-common-static-${CLICKHOUSE_VERSION}-2.x86_64.rpm"
   
   CLICKHOUSE_PACKAGES['ubuntu18.04']=${CLICKHOUSE_PACKAGES['ubuntu']}
   CLICKHOUSE_PACKAGES['ubuntu20.04']=${CLICKHOUSE_PACKAGES['ubuntu']}
   CLICKHOUSE_PACKAGES['centos7']=${CLICKHOUSE_PACKAGES['centos']}
   CLICKHOUSE_PACKAGES['centos8']=${CLICKHOUSE_PACKAGES['centos']}
   CLICKHOUSE_PACKAGES['rhel7']=${CLICKHOUSE_PACKAGES['centos']}
   CLICKHOUSE_PACKAGES['rhel8']=${CLICKHOUSE_PACKAGES['centos']}
   
   declare -A NGINX_PACKAGES
   NGINX_PACKAGES['ubuntu18.04']="nginx_1.21.3-1~bionic_amd64.deb"
   NGINX_PACKAGES['ubuntu20.04']="nginx_1.21.2-1~focal_amd64.deb"
   NGINX_PACKAGES['centos7']="nginx-1.21.4-1.el7.ngx.x86_64.rpm"
   NGINX_PACKAGES['centos8']="nginx-1.21.4-1.el8.ngx.x86_64.rpm"
   NGINX_PACKAGES['rhel7']="nginx-1.21.4-1.el7.ngx.x86_64.rpm"
   NGINX_PACKAGES['rhel8']="nginx-1.21.4-1.el8.ngx.x86_64.rpm"
   
   download_packages() {
       local target_distribution=$1
       if [ -z $target_distribution ]; then
           echo "$0 - no target distribution specified"
           exit 1
       fi
   
       mkdir -p "${PACKAGE_PATH}/${target_distribution}"
       # just in case delete all files in target dir
       rm -f "${PACKAGE_PATH}/${target_distribution}/*"
   
       readarray -t clickhouse_files <<<"${CLICKHOUSE_PACKAGES[${target_distribution}]}"
       readarray -t nginx_files <<<"${NGINX_PACKAGES[${target_distribution}]}"
   
       echo "Downloading Clickhouse signing keys"
       curl -fs ${CLICKHOUSE_KEY} --output "${PACKAGE_PATH}/${target_distribution}/clickhouse-key.gpg"
       echo "Downloading Nginx signing keys"
       curl -fs ${NGINX_KEY} --output "${PACKAGE_PATH}/${target_distribution}/nginx-key.gpg"
   
       for package_file in "${clickhouse_files[@]}"; do
           if [ -z $package_file ]; then
               continue
           fi
           file_url="${CLICKHOUSE_REPO[$target_distribution]}/$package_file"
           save_file="${PACKAGE_PATH}/${target_distribution}/$package_file"
           echo "Fetching $file_url"
           curl -fs $file_url --output $save_file
       done
   
       for package_file in "${nginx_files[@]}"; do
           if [ -z $package_file ]; then
               continue
           fi
           file_url="${NGINX_REPO[$target_distribution]}/$package_file"
           save_file="${PACKAGE_PATH}/${target_distribution}/$package_file"
           echo "Fetching $file_url"
           curl -fs $file_url --output $save_file
       done
   
       bundle_file="${PACKAGE_PATH}/nms-dependencies-${target_distribution}.tar.gz"
       tar -zcf $bundle_file -C "${PACKAGE_PATH}/${target_distribution}" .
       echo "Bundle file saved as $bundle_file"
   
   }
   
   target_distribution=$1
   
   if [ -z $target_distribution ]; then
       echo "Usage: $0 target_distribution"
       echo "Supported target distributions: ${!CLICKHOUSE_REPO[@]}"
       exit 1
   fi
   
   # check if target distribution is supported
   
   if [ -z ${CLICKHOUSE_REPO[$target_distribution]} ]; then
       echo "Target distribution is not supported."
       echo "Supported distributions: ${!CLICKHOUSE_REPO[@]}"
       exit 1
   fi
   
   download_packages "${target_distribution}"
   

   
   

2. After you copy and extract the bundle onto your target machine, take the following steps to install the packages:

   Note:
   The bundled NGINX server package may conflict with installed versions of NGINX or NGINX Plus. Delete the package from the bundle if you want to keep the existing version.

   • CentOS, RHEL, and RPM-Based
   • Debian, Ubuntu, and Deb-Based

   tar -kzxvf nms-dependencies-rhel7.tar.gz
   sudo yum localinstall *.rpm
   

   tar -kzxvf nms-dependencies-ubuntu18.04.tar.gz
   sudo dpkg -i ./*.deb
   

Note:
Even though the ClickHouse server may not be exposed to the network, you should use a non-default username and strong password for improved security.

Install Instance Manager

• CentOS, RHEL, and RPM-Based
• Debian, Ubuntu, and Deb-Based

Install API Connectivity Manager

Install the Management Plane

• CentOS, RHEL, and RPM-Based
• Debian, Ubuntu, and Deb-Based

Install the Data Plane

The API Connectivity Manager data plane and Developer Portal hosts require PostgreSQL, NGINX Plus, and njs.

1. You can install the PostgreSQL package from your distribution’s repo at the same time you install the operating system. Refer to the the PostgreSQL download guide for instructions.

2. To install the NGINX Plus and njs dependencies, run the fetch-external-devportal-dependencies.sh script below. This script downloads the necessary packages to a tar.gz archive.

   As an argument to the script, specify the Linux distribution for the packages:

   • amzn2
   • centos7
   • centos8
   • debian10
   • debian11
   • rhel7
   • rhel8
   • ubuntu18.04
   • ubuntu20.04

   ./fetch-external-devportal-dependencies <linux distribution>
   

   For example:

   ./fetch-external-devportal-dependencies ubuntu18.04
   

   
   
   fetch-external-devportal-dependencies.sh

   fetch-external-devportal-dependencies.sh

   #!/usr/bin/env bash
   # This script is used to fetch external packages that are not available in standard Linux distribution
   
   # Example: ./fetch-external-dependencies ubuntu18.04 nginx-repo.crt nginx-repo.key
   # Script will create devportal-dependencies-ubuntu18.04.tar.gz in local directory which can be copied
   # into target machine and packages inside can be installed manually
   
   set -eo pipefail
   
   PACKAGE_PATH="."
   
   mkdir -p $PACKAGE_PATH
   
   declare -A NGINXPLUS_REPO
   NGINXPLUS_REPO['ubuntu18.04']="https://pkgs.nginx.com/plus/ubuntu/pool/nginx-plus/n/nginx-plus"
   NGINXPLUS_REPO['ubuntu20.04']="https://pkgs.nginx.com/plus/ubuntu/pool/nginx-plus/n/nginx-plus"
   NGINXPLUS_REPO['debian10']="https://pkgs.nginx.com/plus/debian/pool/nginx-plus/n/nginx-plus"
   NGINXPLUS_REPO['debian11']="https://pkgs.nginx.com/plus/debian/pool/nginx-plus/n/nginx-plus"
   NGINXPLUS_REPO['centos7']="https://pkgs.nginx.com/plus/centos/7/x86_64/RPMS"
   NGINXPLUS_REPO['centos8']="https://pkgs.nginx.com/plus/centos/8/x86_64/RPMS"
   NGINXPLUS_REPO['rhel7']="https://pkgs.nginx.com/plus/rhel/7/x86_64/RPMS"
   NGINXPLUS_REPO['rhel8']="https://pkgs.nginx.com/plus/rhel/8/x86_64/RPMS"
   NGINXPLUS_REPO['amzn2']="https://pkgs.nginx.com/plus/amzn2/2/x86_64/RPMS"
   
   declare -A NJS_REPO
   NJS_REPO['ubuntu18.04']="https://pkgs.nginx.com/plus/ubuntu/pool/nginx-plus/n/nginx-plus-module-njs"
   NJS_REPO['ubuntu20.04']="https://pkgs.nginx.com/plus/ubuntu/pool/nginx-plus/n/nginx-plus-module-njs"
   NJS_REPO['debian10']="https://pkgs.nginx.com/plus/debian/pool/nginx-plus/n/nginx-plus-module-njs"
   NJS_REPO['debian11']="https://pkgs.nginx.com/plus/debian/pool/nginx-plus/n/nginx-plus-module-njs"
   NJS_REPO['centos7']="https://pkgs.nginx.com/plus/centos/7/x86_64/RPMS"
   NJS_REPO['centos8']="https://pkgs.nginx.com/plus/centos/8/x86_64/RPMS"
   NJS_REPO['rhel7']="https://pkgs.nginx.com/plus/rhel/7/x86_64/RPMS"
   NJS_REPO['rhel8']="https://pkgs.nginx.com/plus/rhel/8/x86_64/RPMS"
   NJS_REPO['amzn2']="https://pkgs.nginx.com/plus/amzn2/2/x86_64/RPMS"
   
   declare -A NGINXPLUS_PACKAGES
   NGINXPLUS_PACKAGES['ubuntu18.04']="nginx-plus_26-1~bionic_amd64.deb"
   NGINXPLUS_PACKAGES['ubuntu20.04']="nginx-plus_26-1~focal_amd64.deb"
   NGINXPLUS_PACKAGES['debian10']="nginx-plus_26-1~buster_amd64.deb"
   NGINXPLUS_PACKAGES['debian11']="nginx-plus_26-1~bullseye_amd64.deb"
   NGINXPLUS_PACKAGES['centos7']="nginx-plus-26-1.el7.ngx.x86_64.rpm"
   NGINXPLUS_PACKAGES['centos8']="nginx-plus-26-1.el8.ngx.x86_64.rpm"
   NGINXPLUS_PACKAGES['rhel7']="nginx-plus-26-1.el7.ngx.x86_64.rpm"
   NGINXPLUS_PACKAGES['rhel8']="nginx-plus-26-1.el8.ngx.x86_64.rpm"
   NGINXPLUS_PACKAGES['amzn2']="nginx-plus-26-1.amzn2.ngx.x86_64.rpm"
   
   declare -A NJS_PACKAGES
   NJS_PACKAGES['ubuntu18.04']="nginx-plus-module-njs_26+0.7.3-1~bionic_amd64.deb"
   NJS_PACKAGES['ubuntu20.04']="nginx-plus-module-njs_26+0.7.3-1~focal_amd64.deb"
   NJS_PACKAGES['debian10']="nginx-plus-module-njs_26+0.7.3-1~buster_amd64.deb"
   NJS_PACKAGES['debian11']="nginx-plus-module-njs_26+0.7.3-1~bullseye_amd64.deb"
   NJS_PACKAGES['centos7']="nginx-plus-module-njs-26+0.7.3-1.el7.ngx.x86_64.rpm"
   NJS_PACKAGES['centos8']="nginx-plus-module-njs-26+0.7.3-1.el8.ngx.x86_64.rpm"
   NJS_PACKAGES['rhel7']="nginx-plus-module-njs-26+0.7.3-1.el7.ngx.x86_64.rpm"
   NJS_PACKAGES['rhel8']="nginx-plus-module-njs-26+0.7.3-1.el8.ngx.x86_64.rpm"
   NJS_PACKAGES['amzn2']="nginx-plus-module-njs-26+0.7.3-1.amzn2.ngx.x86_64.rpm"
   
   download_packages() {
       local target_distribution=$1
       local nginx_repo_cert=$2
       local nginx_repo_key=$3
       if [ -z $target_distribution ] ||  [ -z $nginx_repo_cert ] ||  [ -z $nginx_repo_key ]; then
           echo "$0 - missing parameter"
           exit 1
       fi
   
       mkdir -p "${PACKAGE_PATH}/${target_distribution}"
       # just in case delete all files in target dir
       rm -f "${PACKAGE_PATH}/${target_distribution}/*"
   
       readarray -t nginxplus_files <<<"${NGINXPLUS_PACKAGES[${target_distribution}]}"
       readarray -t njs_files <<<"${NJS_PACKAGES[${target_distribution}]}"
   
       for package_file in "${nginxplus_files[@]}"; do
           if [ -z $package_file ]; then
               continue
           fi
           file_url="${NGINXPLUS_REPO[$target_distribution]}/$package_file"
           save_file="${PACKAGE_PATH}/${target_distribution}/$package_file"
           echo "Fetching $file_url"
           curl --cert ${nginx_repo_cert} --key ${nginx_repo_key} -fs $file_url --output $save_file
       done
   
       for package_file in "${njs_files[@]}"; do
           if [ -z $package_file ]; then
               continue
           fi
           file_url="${NJS_REPO[$target_distribution]}/$package_file"
           save_file="${PACKAGE_PATH}/${target_distribution}/$package_file"
           echo "Fetching $file_url"
           curl --cert ${nginx_repo_cert} --key ${nginx_repo_key} -fs $file_url --output $save_file
       done
   
       bundle_file="${PACKAGE_PATH}/devportal-dependencies-${target_distribution}.tar.gz"
       tar -zcf $bundle_file -C "${PACKAGE_PATH}/${target_distribution}" .
       echo "Bundle file saved as $bundle_file"
   
   }
   
   target_distribution=$1
   nginx_repo_cert=$2
   nginx_repo_key=$3
   
   if [ -z $target_distribution ]; then
       echo "Usage: $0 target_distribution nginxrepo_cert nginxrepo_key"
       echo "Supported target distributions: ${!NGINXPLUS_REPO[@]}"
       exit 1
   fi
   
   if [ -z $nginx_repo_cert ] || [ -z $nginx_repo_key ]; then
       echo "Usage: $0 target_distribution nginxrepo_cert nginxrepo_key"
       echo "Missing nginxrepo_cert or nginxrepo_key parameters"
       exit 1
   fi
   
   # check if target distribution is supported
   if [ -z ${NGINXPLUS_REPO[$target_distribution]} ]; then
       echo "Target distribution $target_distribution is not supported."
       echo "Supported distributions: ${!NGINXPLUS_REPO[@]}"
       exit 1
   fi
   
   download_packages "${target_distribution}" "${nginx_repo_cert}" "${nginx_repo_key}"
   

   
   

3. After you copy and extract the bundle onto your target machine, take the following steps to install the packages:

   Note:
   The bundled NGINX Plus package may conflict with installed versions of NGINX Plus. Delete the package from the bundle if you want to keep the existing version.

   • CentOS, RHEL, and RPM-Based
   • Debian, Ubuntu, and Deb-Based

   tar -kzxvf devportal-dependencies-rhel7.tar.gz
   sudo yum localinstall *.rpm
   

   tar -kzxvf devportal-dependencies-ubuntu18.04.tar.gz
   sudo dpkg -i ./*.deb
   

Install the Developer Portal

• CentOS, RHEL, and RPM-Based
• Debian, Ubuntu, and Deb-Based

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:

• NIM
• NIM + ACM

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:

• CentOS, RHEL, RPM-Based
• Debian, Ubuntu, Deb-Based

CVE Checking

NGINX Instance Manager connects to the internet to get a list of the current CVEs (Common Vulnerabilities and Exposures) to use with the scan function. To manually update the CVE list, download and overwrite the cve.xml file in the /usr/share/nms directory.

To download the CVE file, take the following steps:

1. Download the CVE file:

   curl -s http://hg.nginx.org/nginx.org/raw-file/tip/xml/en/security_advisories.xml > /usr/share/nms/cve.xml
   

2. Restart the dpm service to pick up the new CVE file:

   systemctl restart nms-dpm