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="."
    
    mkdir -p $PACKAGE_PATH
    
    declare -A CLICKHOUSE_REPO
    CLICKHOUSE_REPO['ubuntu18.04']="https://repo.clickhouse.tech/deb/lts/main"
    CLICKHOUSE_REPO['ubuntu20.04']="https://repo.clickhouse.tech/deb/lts/main"
    CLICKHOUSE_REPO['centos7']="https://repo.clickhouse.tech/rpm/lts/x86_64"
    CLICKHOUSE_REPO['centos8']="https://repo.clickhouse.tech/rpm/lts/x86_64"
    CLICKHOUSE_REPO['rhel7']="https://repo.clickhouse.tech/rpm/lts/x86_64"
    CLICKHOUSE_REPO['rhel8']="https://repo.clickhouse.tech/rpm/lts/x86_64"
    
    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://repo.clickhouse.com/CLICKHOUSE-KEY.GPG"
    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_21.3.10.1_all.deb
    clickhouse-common-static_21.3.10.1_amd64.deb"
    
    CLICKHOUSE_PACKAGES['centos']="
    clickhouse-server-21.3.10.1-2.noarch.rpm
    clickhouse-common-static-21.3.10.1-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
    



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
    


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:

    sudo systemctl start clickhouse-server
    
  2. Start the NGINX web server:

    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
    
  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. (Optional) If a new admin password was generated for you, change this password with your own as soon as possible following the steps in the Configure Authentication guide.

Note:
After you’ve started NGINX Instance Manager, you can access the 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.


Upgrading NGINX Instance Manager

To upgrade NGINX Instance Manager:

  1. Follow the same steps above for installing NGINX Instance Manager.

  2. On the data plane host(s), upgrade and restart the NGINX Agent:

    curl -k https://<NGINX-INSTANCE-MANAGER-FQDN>/install/nginx-agent | sudo su -
    
    sudo systemctl restart nginx-agent
    
    See Also:
    See the NGINX Agent Installation Guide for other installation options, such as wget or installing from package files.
  3. Reload NGINX:

    nginx -s reload
    
  4. Reapply the SELinux policy if it’s enabled:

    sudo semodule -n -i /usr/share/selinux/packages/nms.pp
    sudo /usr/sbin/load_policy
    sudo restorecon -F -R /usr/bin/nms-core
    sudo restorecon -F -R /usr/bin/nms-dpm
    sudo restorecon -F -R /usr/bin/nms-ingestion
    sudo restorecon -F -R /usr/lib/systemd/system/nms.service
    sudo restorecon -F -R /usr/lib/systemd/system/nms-core.service
    sudo restorecon -F -R /usr/lib/systemd/system/nms-dpm.service
    sudo restorecon -F -R /usr/lib/systemd/system/nms-ingestion.service
    sudo restorecon -F -R /var/lib/nms/modules/manager.json
    sudo restorecon -F -R /var/lib/nms/modules.json
    sudo restorecon -F -R /var/lib/nms/streaming
    sudo restorecon -F -R /var/lib/nms
    sudo restorecon -F -R /var/lib/nms/dqlite
    sudo restorecon -F -R /var/run/nms
    sudo restorecon -F -R /var/lib/nms/modules
    sudo restorecon -F -R /var/log/nms
    
  5. Start the following NGINX Instance Manager services:

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


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