Install the latest NGINX Instance Manager with a script (disconnected)

Legacy 'nms' references Some commands, file paths, and configuration references still use nms due to the ongoing transition from NGINX Management Suite (NMS) to NGINX Instance Manager (NIM). These will be updated in future releases.

Overview

This guide shows you how to install and upgrade F5 NGINX Instance Manager in disconnected environments.

The script installs:

  • The latest version of NGINX Open Source
  • The latest version of NGINX Instance Manager
  • ClickHouse by default, unless you choose to skip it

NGINX Plus is not supported in disconnected mode.

If you need to install earlier versions of NGINX or NGINX Instance Manager, follow the manual installation process instead.

Before you begin

You’ll need internet access for the steps in this section.

Prepare your system for installation

Follow these steps to get your system ready for a successful installation with the install-nim-bundle.sh script:

Resolve existing installations of NGINX Instance Manager

The script supports only new installations. If NGINX Instance Manager is already installed, take one of the following actions:

  • Upgrade manually The script cannot perform upgrades. To update an existing installation, follow the upgrade steps in this document.

  • Uninstall first Remove the current installation and its dependencies for a fresh start. Use the uninstall steps to delete the primary components. Afterward, manually check for and remove leftover files such as repository configurations or custom settings to ensure a clean system.

Verify SSL certificates and private keys

Ensure that the required .crt and .key files are available, preferably in the default /etc/ssl/nginx directory. Missing certificates or keys will prevent the script from completing the installation.

Use the manual installation steps if needed

If the script fails or if you prefer more control over the process, consider using the manual installation steps. These steps provide a reliable alternative for troubleshooting or handling complex setups.

Download the SSL Certificate and Private Key from MyF5

Download the SSL certificate and private key required for NGINX Instance Manager:

  1. Log in to MyF5.
  2. Go to My Products & Plans > Subscriptions to see your active subscriptions.
  3. Find your NGINX products or services subscription, and select the Subscription ID for details.
  4. Download the SSL Certificate and Private Key files.

Download the installation script

Download the install-nim-bundle.sh script.

Package NGINX Instance Manager and dependencies for offline installation

Run the installation script in offline mode to download NGINX Instance Manager, NGINX Open Source, ClickHouse (unless skipped), and all required dependencies into a tarball for use in disconnected environments.

Installation script options

Category Option or Flag
Installation mode and platform -m offline: Required to package the installation files into a tarball for disconnected environments.

-d <distribution>: Target Linux distribution (for example, ubuntu22.04, rhel8)

To see the list of supported distributions, run:

grep '\-d distribution' install-nim-bundle.sh
SSL certificate and key

-c <path/to/nginx-repo.crt>: Path to the SSL certificate file. (default: /etc/ssl/nginx)


-k <path/to/nginx-repo.key>: Path to the private key file. (default: /etc/ssl/nginx)
NGINX installation -n: Include the latest version of NGINX Open Source in the tarball.

This option is optional in offline mode—if not specified, the script installs the latest version of NGINX Open Source by default.

NGINX Plus is not supported when using the script in offline mode.

To install NGINX Plus offline, see the manual installation guide.
ClickHouse installation

-s: Skip installing ClickHouse. This lightweight mode reduces system requirements and simplifies installation for users who do not need metrics.

If you skip installing ClickHouse, you need NGINX Agent 2.41.1 or later.

After installation, make sure to disable metrics collection in the /etc/nms/nms.conf file.


-v <clickhouse-version>: Install a specific version of ClickHouse. If not set, version 24.8.12.28 is installed by default.

Example: packaging command 

sudo bash install-nim-bundle.sh \
-c <path/to/nginx-repo.crt> \
-k <path/to/nginx-repo.key> \
-m offline \
-d <distribution> \
-v <clickhouse-version>

Install NGINX Instance Manager

After you’ve packaged the installation files on a connected system, copy the tarball, script, and SSL files to your disconnected system. Then, run the script again to install NGINX Instance Manager using the tarball.

Required flags for installing in offline mode

  • -m offline: Required to run the script in offline mode. When used with -i, the script installs NGINX Instance Manager and its dependencies from the specified tarball.
  • -i <path/to/tarball.tar.gz>: Path to the tarball created during the packaging step.

  • -c <path/to/nginx-repo.crt>: Path to the SSL certificate file. (default: /etc/ssl/nginx)

  • -k <path/to/nginx-repo.key>: Path to the private key file. (default: /etc/ssl/nginx)

  • -d <distribution>: Target Linux distribution (must match what was used during packaging).

Install from the tarball

  1. Copy the following files to the target system:

    • install-nim-bundle.sh script
    • SSL certificate file
    • Private key file
    • Tarball file with the required packages

  2. Run the installation script:

    sudo bash install-nim-bundle.sh \
-m offline
-i <path/to/tarball.tar.gz>
-c <path/to/nginx-repo.crt>
-k <path/to/nginx-repo.key> \
-d <distribution> \

  3. Save the admin password. In most cases, the script completes the installation of NGINX Instance Manager and associated packages. After installation is complete, the script takes a few minutes to generate a password. At the end of the process, you’ll see an autogenerated password:

    Regenerated Admin password: <encrypted password>

    Save that password. You’ll need it when you sign in to NGINX Instance Manager.

  4. After installation, open a web browser, go to https://<NIM-FQDN> (the fully qualified domain name of the NGINX Instance Manager host), and log in.

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 file. 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.

Uninstall NGINX Instance Manager

Follow the steps below to uninstall NGINX Instance Manager and ClickHouse.

  • For CentOS, RHEL, and RPM-based distributions:

    sudo yum remove -y nms-*
sudo systemctl stop clickhouse-server
sudo yum remove -y clickhouse-server

  • For Debian, Ubuntu, and Deb-based distributions:

    sudo apt-get remove -y nms-*
sudo systemctl stop clickhouse-server
sudo apt-get remove -y clickhouse-server

    If you want to remove the package and its configuration files, use apt-get purge -y <package> instead of apt-get remove -y.

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