Manually install any version of NGINX Instance Manager (disconnected)

Overview

This guide explains how to install and upgrade NGINX Instance Manager in environments without Internet access. It covers key steps, including downloading packages, managing dependencies, and configuring the system for offline use. You’ll also learn how to set up NGINX Instance Manager in disconnected mode and manually update the CVE list to keep your system secure.

Before you begin

Complete the required prerequisites You must complete the following prerequisite steps before installing NGINX Instance Manager. Skipping these steps could cause installation issues.

Security considerations

To ensure that your NGINX Instance Manager deployment remains secure, follow these recommendations:

  • Install NGINX Instance Manager on a dedicated machine (bare metal, container, cloud, or VM).
  • Make sure no other services are running on the same machine.
  • Ensure the machine is not accessible from the Internet.
  • Place the machine behind a firewall.

Download package files

To complete the steps in this guide, you need to download the NGINX Instance Manager package files from the MyF5 Customer Portal.

Install local dependencies

Local dependencies are common Linux packages like curl or openssl, which most Linux distributions include by default. When installing NGINX Instance Manager, your package manager will automatically install these dependencies. Without internet access, ensure your package manager can use a local package repository, such as a distribution DVD/ISO image or internal network mirror. Check your Linux distribution’s documentation for details.

RedHat on AWS If you’re using AWS and can’t attach remote or local RedHat package repositories, download the necessary packages on another RedHat machine and copy them to your target machine. Use the yumdownloader utility for this task: https://access.redhat.com/solutions/10154.

Download and install external dependencies

External dependencies, such as ClickHouse and NGINX Plus, aren’t included by default in standard Linux distributions. You need to manually download and transfer these to your offline system.

To download external dependencies:

  1. Download the fetch-external-dependencies.sh script:

    Download fetch-external-dependencies.sh script

  2. Run the script to download the external dependencies for your specific Linux distribution:

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

    Supported Linux distributions:

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

    For example, to download external dependencies for Ubuntu 20.04:

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

    This will create an archive, such as nms-dependencies-ubuntu20.04.tar.gz, containing the required dependencies.

  3. Copy the archive to your target machine and extract the contents:

    Note: The bundled NGINX server package may conflict with existing versions of NGINX or NGINX Plus. Delete the package from the bundle if you want to keep your current version.

    • For RHEL and RPM-Based systems:

      tar -kzxvf nms-dependencies-<linux-distribution>.tar.gz
sudo rpm -ivh *.rpm

    • For Debian, Ubuntu, Deb-based systems:

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

Install NGINX Instance Manager

Save the password! The administrator username (default: admin) and the generated password are displayed in the terminal during installation. Be sure to record the password and store it securely.

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

  2. Install the NGINX Instance Manager package:

    • For RHEL and RPM-based systems:

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

    • For Debian, Ubuntu, Deb-based systems:

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

  3. Enable and start NGINX Instance Manager services:

    sudo systemctl enable nms nms-core nms-dpm nms-ingestion nms-integrations --now
    Note: 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.

  4. Restart the NGINX web server:

    sudo systemctl restart nginx

Set the operation mode to disconnected

  1. Open the /etc/nms/nms.conf file and add the following in the integrations:license section:

    integrations:
    license:
        mode_of_operation: disconnected

  2. Restart NGINX Instance Manager:

    sudo systemctl restart nms

Optional post-installation steps

Configure ClickHouse

If you installed ClickHouse and set a password (the default is an empty string), you must add it to the clickhouse.password setting in the /etc/nms/nms.conf file after installing NGINX Instance Manager. If the password is missing or incorrect, NGINX Instance Manager will not start.

You can also configure additional ClickHouse settings in the same section:

  • clickhouse.username – the username used to connect to ClickHouse
  • clickhouse.address – the address of the ClickHouse server (default is tcp://localhost:9000)
  • clickhouse.tls_mode – set to true to enable TLS
  • TLS certificate settings, such as:
    • clickhouse.tls.cert_path
    • clickhouse.tls.key_path
    • clickhouse.tls.ca_path
    • clickhouse.tls.skip_verify

For more details, see Configure ClickHouse.

Disable metrics collection

If you’re not collecting metrics — because you didn’t install ClickHouse or don’t plan to use it — you must disable metrics collection in the /etc/nms/nms.conf and /etc/nms/nms-sm-conf.yaml files. This setup requires NGINX Agent version 2.41.1 or later.

For instructions, see Disable metrics collection.

Install and configure Vault

NGINX Instance Manager can use Vault as a datastore for secrets.

To install and enable Vault, follow these steps:

Configure SELinux

SELinux helps secure your deployment by enforcing mandatory access control policies.

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 Instance Manager.

Upgrade NGINX Instance Manager

To upgrade NGINX Instance Manager to a newer version:

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

  2. Upgrade the package:

    • For RHEL and RPM-based systems:

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

    • For Debian, Ubuntu, Deb-based systems:

      sudo apt-get -y install -f /home/user/nms-instance-manager_<version>_amd64.deb
sudo systemctl restart nms
sudo systemctl restart nginx
    Note: 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.

  3. (Optional) If you use SELinux, follow the Configure SELinux guide to restore SELinux contexts using restorecon for files and directories related to NGINX Instance Manager.

CVE checking

To manually update the CVE list in an air-gapped environment, follow these steps to download and overwrite the cve.xml file in the /usr/share/nms directory and restart the Data Plane Manager service:

sudo chmod 777 /usr/share/nms/cve.xml && \
sudo curl -s http://hg.nginx.org/nginx.org/raw-file/tip/xml/en/security_advisories.xml > /usr/share/nms/cve.xml && \
sudo chmod 644 /usr/share/nms/cve.xml && \
sudo systemctl restart nms-dpm

Next steps