Offline Installation Guide

Complete the steps in this guide to install NGINX Management Suite modules directly from package files in environments without Internet access.

Overview

The NGINX Management Suite is a comprehensive family of management plane solutions that enable you to effectively scale, secure, and monitor your applications and APIs. At its core is the NGINX Management Suite Instance Manager module, which lets you track, secure, and configure your NGINX OSS and NGINX Plus instances. Instance Manager is available as a standalone product and is automatically included when you license any other NGINX Management Suite modules.

Before You Begin

• Download the NGINX Management Suite 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
   • ubuntu22.04
   • centos7
   • centos8
   • rhel7
   • rhel8
   • rhel9

   ./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 -o pipefail
   
   # current dir
   PACKAGE_PATH="."
   CLICKHOUSE_VERSION=21.3.20.1
   
   mkdir -p $PACKAGE_PATH
   
   fetch() {
       url=$1
       output=$2
       http_code=$(curl -fs ${url} --output ${output} --write-out '%{http_code}')
       if [ $? -ne 0 ]; then
   	echo "   -- Failed to download $url with HTTP code $http_code. Exiting."
   	exit
       fi
   }
   
   declare -A CLICKHOUSE_REPO
   CLICKHOUSE_REPO['ubuntu18.04']="https://packages.clickhouse.com/deb/pool/main/c/clickhouse/"
   CLICKHOUSE_REPO['ubuntu20.04']="https://packages.clickhouse.com/deb/pool/main/c/clickhouse/"
   CLICKHOUSE_REPO['ubuntu22.04']="https://packages.clickhouse.com/deb/pool/main/c/clickhouse/"
   CLICKHOUSE_REPO['centos7']="https://packages.clickhouse.com/rpm/stable/"
   CLICKHOUSE_REPO['centos8']="https://packages.clickhouse.com/rpm/stable/"
   CLICKHOUSE_REPO['rhel7']="https://packages.clickhouse.com/rpm/stable/"
   CLICKHOUSE_REPO['rhel8']="https://packages.clickhouse.com/rpm/stable/"
   CLICKHOUSE_REPO['rhel9']="https://packages.clickhouse.com/rpm/stable/"
   
   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['ubuntu22.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/"
   NGINX_REPO['rhel9']="https://nginx.org/packages/mainline/rhel/9/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['ubuntu22.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']}
   CLICKHOUSE_PACKAGES['rhel9']=${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['ubuntu22.04']="nginx_1.21.6-1~jammy_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"
   NGINX_PACKAGES['rhel9']="nginx-1.21.6-1.el9.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 -n "Downloading Clickhouse signing keys ... "
       fetch ${CLICKHOUSE_KEY} "${PACKAGE_PATH}/${target_distribution}/clickhouse-key.gpg"
       echo "done"
       echo -n "Downloading Nginx signing keys ... "
       fetch ${NGINX_KEY} "${PACKAGE_PATH}/${target_distribution}/nginx-key.gpg"
       echo "done"
   
       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 -n "Downloading ${package_file} ... "
           fetch $file_url $save_file
   	echo "done"
       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 -n "Downloading ${package_file} ... "
           fetch $file_url $save_file
   	echo "done"
       done
   
       bundle_file="${PACKAGE_PATH}/nms-dependencies-${target_distribution}.tar.gz"
       echo -n "Creating bundle ... "
       tar -zcf $bundle_file -C "${PACKAGE_PATH}/${target_distribution}" .
       echo "done"
       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

5. Enable the 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-integrations
   

6. Start the NGINX Management Suite services:

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

   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.

7. To verify the NGINX Management Services are running, run the following command:

   ps aufx | grep nms
   

8. Restart the NGINX web server:

   sudo systemctl restart nginx
   

• See the Access the Web Interface. After you log in, you can add a license.

Install API Connectivity Manager

Dependencies with Instance Manager

API Connectivity Manager (ACM) depends on the platform capabilities of Instance Manager. The following table lists the minimum versions of Instance Manager required for ACM:

The following table lists the minimum versions of Instance Manager required for ACM:

To ensure ACM’s new features work correctly, you may need to install or upgrade Instance Manager to the minimum version specified. If Instance Manager is not installed, ACM will install the latest version. If the installed version is below the minimum required version, ACM will upgrade Instance Manager to the latest version. Otherwise, ACM will leave Instance Manager unchanged.

Important:
If you’re installing ACM in an offline environment and the minimum required version of Instance Manager is not installed, the ACM installer will exit. You’ll need to install Instance Manager manually before installing ACM.

Install the Management Plane

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

5. Enable the 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-integrations
   sudo systemctl enable nms-acm
   

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

7. To verify the NGINX Management Suite services are running, run the following command:

   ps aufx | grep nms
   

8. Restart the NGINX web server:

   sudo systemctl restart nginx  
   

• See the section on how to access the NGINX Management Suite web interface. After you log in, you can add a license.

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

Important:

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

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

Access the Web Interface

To access the web interface, go to the FQDN for your NGINX Management Suite host and log in:

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

NGINX Management Suite Services

The following table lists the services that are installed with NGINX Management Suite. The “NMS Platform” services are installed with Instance Manager, which is the foundation for the NGINX Management Suite platform.

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

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
   

Troubleshooting

For help with common issues and suggested solutions and workarounds, refer to the NGINX Management Suite Troubleshooting Guide.