Offline Installation Guide

Complete the steps in this guide to install NGINX Instance Manager in offline environments.

This documentation applies to NGINX Instance Manager 2.0.0 and later.

Overview

Complete the steps in this guide to install NGINX Instance Manager 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 Instance Manager has both local and external dependencies. Before installing NGINX Instance Manager, make sure to install these local and external dependencies first.

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 NGINX Instance Manager. 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 Instance Manager 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 versions. Delete the package from the bundle if you want to keep the existing version.

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


    tar -zxvf 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 NGINX Instance Manager

  1. Log in to the MyF5 Customer Portal and download the NGINX Instance Manager package files, or use the package provided by your NGINX Sales Team.

  1. Install the NGINX Instance Manager package:

    sudo yum -y --nogpgcheck install /home/user/nms-instance-manager_<version>.x86_64.rpm

  2. Upgrade the NGINX Instance Manager Package:

    sudo yum -y --nogpgcheck upgrade /home/user/nms-instance-manager_<version>.x86_64.rpm

  1. Install the NGINX Instance Manager package:

    sudo apt-get -y install /home/user/nms-instance-manager_<version>_amd64.deb

  2. Upgrade the NGINX Instance Manager Package:

    sudo apt-get -y upgrade /home/user/nms-instance-manager_<version>_amd64.deb

Configure ClickHouse Connection

  • (Optional) If you specified a non-default username and password when installing ClickHouse, or if your ClickHouse installation uses TLS, follow the steps in Configure ClickHouse before proceeding. You need to update the Instance Manager configuration file with the proper ClickHouse values.

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 if it’s not running:

    • Check to see if the ClickHouse server is running:

      sudo systemctl status clickhouse-server

    • If necessary, start the ClickHouse server:

      sudo systemctl start clickhouse-server

  2. Start or restart the NGINX web server:

    • Check to see if the NGINX is running:

      sudo systemctl status nginx

    • Start NGINX if it’s not running:

      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

    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.

  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. To verify the NGINX Instance Manager services are running, run the following command:

    ps aufx | grep nms

    The output should show processes for:

    • nms-core
    • nms-dpm
    • nms-ingestion

  6. (Optional) If a new admin password was generated for you, change this password with your own as soon as possible. To do so, follow the steps in the Set up Authentication guide.

Access the Web Interface

Access the NGINX Instance Manager 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.


How To Look Up the Installed Version

To see which version of Instance Manager is installed, run the following command:

yum info nms-instance-manager


dpkg -s nms-instance-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:

  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

What’s Next