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 theyumdownloader
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.
-
To download the external dependencies, run the
fetch-external-dependencies.sh
provided below. This script downloads the necessary packages to atar.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}"
-
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.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
-
Log in to the MyF5 Customer Portal and download the Instance Manager package files, or use the package provided by your NGINX Sales Team.
-
Install the Instance Manager package:
sudo yum -y --nogpgcheck install /home/user/nms-instance-manager_<version>.x86_64.rpm
-
Upgrade the Instance Manager package:
sudo yum -y --nogpgcheck upgrade /home/user/nms-instance-manager_<version>.x86_64.rpm
-
Log in to the MyF5 Customer Portal and download the Instance Manager package files, or use the package provided by your NGINX Sales Team.
-
Install the Instance Manager package:
sudo apt-get -y install /home/user/nms-instance-manager_<version>_amd64.deb
-
Upgrade the Instance Manager package:
sudo apt-get -y upgrade /home/user/nms-instance-manager_<version>_amd64.deb
Install API Connectivity Manager
Install the Management Plane
-
Log in to the MyF5 Customer Portal and download the API Connectivity Manager package files, or use the package provided by your NGINX Sales Team.
-
Install the API Connectivity Manager package:
sudo yum -y --nogpgcheck install /home/user/nms-api-connectivity-manager_<version>.x86_64.rpm
-
Upgrade the API Connectivity Manager package:
sudo yum -y --nogpgcheck upgrade /home/user/nms-api-connectivity-manager_<version>.x86_64.rpm
-
Log in to the MyF5 Customer Portal and download the API Connectivity Manager package files, or use the package provided by your NGINX Sales Team.
-
Install the API Connectivity Manager package:
sudo apt-get -y install /home/user/nms-api-connectivity-manager_<version>_amd64.deb
-
Upgrade the API Connectivity Manager package:
sudo apt-get -y upgrade /home/user/nms-api-connectivity-manager_<version>_amd64.deb
Install the Data Plane
The API Connectivity Manager data plane and Developer Portal hosts require PostgreSQL, NGINX Plus, and njs.
-
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.
-
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}"
-
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.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
-
On the Developer Host, complete the same steps from the Install the Data Plane section to install PostgreSQL, NGINX Plus, and njs.
-
Log in to the MyF5 Customer Portal and download the NGINX Developer Portal package files, or use the package provided by your NGINX Sales Team.
-
Install the NGINX Developer Portal packages:
sudo yum -y --nogpgcheck install /home/user/nginx-devportal-<version>.x86_64.rpm /home/user/nginx-devportal-ui-<version>.x86_64.rpm
-
Upgrade the NGINX Developer Portal packages:
sudo yum -y --nogpgcheck upgrade /home/user/nginx-devportal-<version>.x86_64.rpm /home/user/nginx-devportal-ui-<version>.x86_64.rpm
-
On the Developer Host, complete the same steps from the Install the Data Plane section to install PostgreSQL, NGINX Plus, and njs.
-
Log in to the MyF5 Customer Portal and download the NGINX Developer Portal package files, or use the package provided by your NGINX Sales Team.
-
Install the NGINX Developer Portal package:
sudo apt-get -y install -f /home/user/nginx-devportal_<version>_amd64.deb /home/user/nginx-devportal-ui_<version>_amd64.deb
-
Upgrade the NGINX Developer Portal packages:
sudo apt-get -y install -f /home/user/nginx-devportal_<version>_amd64.deb /home/user/nginx-devportal-ui_<version>_amd64.deb
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 othernms-*
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:
-
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
-
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 thenms
group, both of which are created during installation. -
To verify the NGINX Management Suite services are running, run the following command:
ps aufx | grep nms
-
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
-
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 thenms
group, both of which are created during installation. -
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
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:
-
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
-
Restart the dpm service to pick up the new CVE file:
systemctl restart nms-dpm