Install in a disconnected environment using a script

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 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 update the CVE list manually to keep your system secure.

Access the deprecated manual steps
If you prefer to follow the original manual steps, you can access the deprecated guide. Please note that this guide is no longer actively maintained and may not reflect the latest updates or best practices.

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.

To run the script, enter the following command, replacing <path/to/certificate.crt> and <path/to/private.key> with the full paths and filenames of your SSL certificate and private key files:

sudo bash install-nim-bundle.sh \
  -c <path/to/certificate.crt> \
  -k <path/to/private.key> \
  -m offline \
  -d <distribution> \
  -p <version> \
  -v <version> \
  -j <path/to/nginx-product.jwt>

By default, this command installs the latest version of NGINX Open Source. To install NGINX Plus or specify a different version of NGINX Open Source, use the -p or -n options as needed.

Note:
Starting from NGINX Plus Release 33, a JWT file is required for each NGINX Plus instance. For more information, see About Subscription Licenses.

Explanation of options:

  • -c: Uses the specified SSL certificate file. Copies the file to the /etc/ssl/nginx directory.
  • -k: Uses the specified private key file. Copies the file to the /etc/ssl/nginx directory.
  • -m: Sets the installation mode (use offline for disconnected environments).
  • -d: Defines the target distribution (replace <distribution> with one of the supported options below).
  • -n: Installs a specific version of NGINX Open Source. Use latest to install the most recent version or specify a version like 1.27.1. If neither -n nor -p is specified, the script defaults to installing the latest version of NGINX Open Source.
  • -p: Installs the specified version of NGINX Plus. Use latest for the newest version or a specific release like R32. Overrides the -n option if both are specified.
  • -v: Installs the specified version of NGINX Instance Manager. Use latest for the newest version or a specific release like 2.18.0. If you skip this option, the script assumes you want to install latest.
  • -j: Uses the specified JWT token.

Supported distributions:

To get the latest list supported by the script, run the following command:

grep '\-d distribution' install-nim-bundle.sh

The script downloads the required packages and adds them to a tarball file. You’ll need to copy this tarball to the target machine in the disconnected environment.

Install NGINX Instance Manager

  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 \
-c <path/to/certificate.crt> 
-k <path/to/private.key> \
-m offline \
-d <distribution> \
-i <path/to/tarball.tar.gz>

  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

Post-installation steps (optional)

The following steps may be necessary depending on your installation configuration.

  • 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 Instance Manager won’t be able to connect to ClickHouse.

  • 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 Instance Manager won’t be able to connect to Vault.

  • 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
Last modified December 6, 2024