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.

Prerequisites

Important:
You must complete the following prerequisite steps before installing any of the NGINX Management Suite modules. Neglecting to do so could result in a module not installing correctly or not installing at all.

Security Considerations

To ensure that your NGINX Management Suite deployment remains secure, follow the recommendations in this section:

  • Install NGINX Management Suite and its modules on a dedicated machine (bare metal, container, cloud, or VM).
  • Make sure that no other services are running on the same machine.
  • Make sure that the machine is not accessible from the Internet.
  • Make sure that the machine is behind a firewall.

Download Package Files

To complete the steps in this guide, you need the following:

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.

Download and Install External Dependencies

External dependencies are packages that aren’t available by default in regular Linux distributions. For example, ClickHouse and NGINX Plus.

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:

  1. Select the following link to download the fetch-external-dependencies.sh script. This script downloads the necessary packages to a tar.gz archive.

    Download fetch-external-dependencies.sh script

  2. Run the fetch-external-dependencies.sh script to download the external dependencies. Specify your Linux distribution for the packages.

    sudo bash fetch-external-dependencies.sh <linux distribution>

    Supported Linux distributions:

    • ubuntu20.04
    • ubuntu22.04
    • debian11
    • debian12
    • centos7
    • oracle7
    • oracle8
    • rhel7
    • rhel8
    • rhel9
    • amzn2

    For example, to download external dependencies for Ubuntu 20.04:

    sudo bash fetch-external-dependencies.sh ubuntu20.04

    In this example, the script creates an archive called nms-dependencies-ubuntu20.04.tar.gz with the external dependencies.

  3. 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-<linux-distribution>.tar.gz
sudo rpm -ivh *.rpm


    tar -kzxvf nms-dependencies-<linux-distribution>.tar.gz
sudo dpkg -i ./*.deb

    IMPORTANT! When installing ClickHouse, you have the option to specify a password or leave the password blank (the default is an empty string). If you choose to specify a password for ClickHouse, you must also edit the /etc/nms/nms.conf file after installing NGINX Management Suite and enter your ClickHouse password; otherwise, NGINX Management Suite won’t start.

    For more information on customizing ClickHouse settings, refer to the Configure ClickHouse topic.

Install or Upgrade Instance Manager

Install Instance Manager

To install Instance Manager, take the following steps:

  1. Log in to the MyF5 Customer Portal and download the Instance Manager package files.

  2. Install the Instance Manager package:

    sudo rpm -ivh --nosignature /home/<user>/nms-instance-manager_<version>.x86_64.rpm

    IMPORTANT! The Instance Manager’s administrator username (default is admin) and generated password are displayed in the terminal during installation. You should make a note of the password and store it securely.

To install Instance Manager, take the following steps:

  1. Log in to the MyF5 Customer Portal and download the Instance Manager package files.

  2. Install the Instance Manager package:

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

    IMPORTANT! The Instance Manager’s administrator username (default is admin) and generated password are displayed in the terminal during installation. You should make a note of the password and store it securely.

  1. Enable and start the NGINX Management Suite platform services:

    sudo systemctl enable nms nms-core nms-dpm nms-ingestion nms-integrations --now

    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.

  2. Restart the NGINX web server:

    sudo systemctl restart nginx

Post-Installation Steps

The following steps may be optional, depending on your installation configuration.

  1. (Optional) If you used a custom address, username, or password or enabled TLS when installing ClickHouse, follow the steps in the Configure ClickHouse guide to update the /etc/nms/nms.conf file. If you don’t do so, NGINX Management Suite won’t be able to connect to ClickHouse.

  2. (Optional) If you use Vault, follow the steps in the Configure Vault guide to update the /etc/nms/nms.conf file. If you don’t do so, NGINX Management Suite won’t be able to connect to Vault.

  3. (Optional) If you use SELinux, follow the steps in the Configure SELinux guide to restore SELinux contexts (restorecon) for the files and directories related to NGINX Management suite.

See these topics below for instructions on how to access the web interface and add your license:

Upgrade Instance Manager

To upgrade Instance Manager to a newer version, take the following steps:

  1. Log in to the MyF5 Customer Portal and download the Instance Manager package files.

  2. Upgrade the Instance Manager package:

    sudo rpm -Uvh --nosignature /home/user/nms-instance-manager_<version>.x86_64.rpm

  3. Restart the NGINX Management Suite platform services:

    sudo systemctl restart 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.

To upgrade Instance Manager to a newer version, take the following steps:

  1. Log in to the MyF5 Customer Portal and download the Instance Manager package files.

  2. Upgrade the Instance Manager package:

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

    sudo systemctl restart nms

  1. Restart the NGINX web server:

    sudo systemctl restart nginx

  2. (Optional) If you use SELinux, follow the steps in the Configure SELinux guide to restore SELinux contexts (restorecon) for the files and directories related to NGINX Management Suite.

Accessing the Web Interface

To access the NGINX Management Suite web interface, open a web browser and go to https://<NMS_FQDN>, replacing <NMS_FQDN> with the Fully Qualified Domain Name of your NGINX Management Suite host.

The default administrator username is admin, and the generated password was displayed in the terminal during installation. If you’d like to change this password, refer to the “Set or Change User Passwords section in the Basic Authentication topic.

Add License

A valid license is required to make full use of all the features in NGINX Management Suite.

Refer to the Add a License topic for instructions on how to download and apply a trial license, subscription license, or Flexible Consumption Program license.

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. Change permissions of the CVE file:

    sudo chmod 777 /usr/share/nms/cve.xml

  2. Download the CVE file:

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

  3. Change permissions of the CVE file:

    sudo chmod 644 /usr/share/nms/cve.xml

  4. Restart the Data Plane Manager 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.