Install the latest NGINX Instance Manager with 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 F5 NGINX Instance Manager on a virtual machine or bare metal system using the installation script in online mode.

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
  • Optionally, NGINX Plus (requires a license and additional flags)

The script also installs all required operating system packages automatically. If you need to install earlier versions of NGINX or NGINX Instance Manager, follow the manual installation process instead.

Before you begin

Follow these steps to prepare for installing NGINX Instance Manager:

  • Download the installation script:

    Download install-nim-bundle.sh script

  • Download the certificate and private key (see the steps below): Use the certificate and private key for NGINX Instance Manager (the same files used for NGINX Plus).

    • Ensure the files have .crt and .key extensions.
    • Save them to the target system. The default locations are:
      • /etc/ssl/nginx/nginx-repo.crt
      • /etc/ssl/nginx/nginx-repo.key

  • Check for previous deployments: Ensure that NGINX Instance Manager and its components are not already installed.

    If NGINX Instance Manager or its components (such as ClickHouse or NGINX) are detected, either follow the upgrade instructions to update them or manually remove the components before proceeding with the installation.

  • (Optional) Install and configure Vault: If you plan to use Vault, set it up before proceeding.

Supported NGINX versions and Linux distributions

The installation script installs the latest version of NGINX Open Source or NGINX Plus.

To see the list of supported distributions, run:

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

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).
  • Ensure that no other services are running on the same machine.

Download certificate and key

Download the certificate and private key required for NGINX Instance Manager. These files are necessary for adding the official repository during installation and can also be used when installing NGINX Plus.

  1. On the host where you’re installing NGINX Instance Manager, create the /etc/ssl/nginx/ directory:

    sudo mkdir -p /etc/ssl/nginx

  2. Download the SSL Certificate, Private Key and JSON Web Token files from MyF5 or use the download link provided in your trial activation email.

  3. Move and rename the cert and key files to the correct directory:

    sudo mv nginx-<subscription id>.crt /etc/ssl/nginx/nginx-repo.crt
sudo mv nginx-<subscription id>.key /etc/ssl/nginx/nginx-repo.key

Prepare the system and run the installation script

If you haven’t already downloaded the script, you can download it here:

Download install-nim-bundle.sh script

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.

Verify If Metrics Are Required (Exclude ClickHouse)

In 2.20.0, we introduced Lightweight mode, which means you can skip the ClickHouse installation entirely. It’s ideal if you don’t need monitoring data or want a simpler setup. This reduces system requirements and avoids the work of managing a metrics database. You can add ClickHouse later if your needs change.

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.

Run the installation script

The install-nim-bundle.sh script automates installing NGINX Instance Manager.

By default, the script:

  • Assumes no prior installation of NGINX Instance Manager or its dependencies
  • Reads SSL files from the /etc/ssl/nginx directory
  • Installs the latest version of NGINX Open Source (OSS)
  • Installs the ClickHouse database
  • Installs the latest version of NGINX Instance Manager
  • Requires an active internet connection

Installation script options

You can customize the installation using the following options:

Category Option or Flag
Installation platform

-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 Install the latest version of NGINX Open Source. (Default if -n or -p not specified)

-p Install NGINX Plus as the API gateway. Must be used with -j to provide a JWT license.

-j <path> Path to the license.jwt file. Required when using -p.
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: install with default key and certificate paths

To use the script to install NGINX Instance Manager on Ubuntu 24.04, with repository keys in the default /etc/ssl/nginx directory, with the latest version of NGINX Open Source, run the following command:

sudo bash install-nim-bundle.sh -d ubuntu24.04

Example: install with custom repo key and certificate

To install NGINX Instance Manager on Ubuntu 24.04 with the latest version of NGINX Plus by pointing to the location of your NGINX cert and key, run the following command:

sudo bash install-nim-bundle.sh \
  -c <path/to/nginx-repo.crt> \
  -k <path/to/nginx-repo.key> \
  -p \
  -d ubuntu24.04 \
  -j <path/to/license.jwt>

After installing NGINX Instance Manager and related packages, the script generates an admin password. This may take a few minutes to appear:

Regenerated Admin password: <encrypted password>

Save this password. You’ll need it to log in to NGINX Instance Manager.

Problems and additional script parameters

There are multiple parameters to configure in the installation script. If you see fatal errors when running the script, first run the following command, which includes command options that can help you bypass problems:

bash install-nim-bundle.sh -h

Access the web interface

After installation, you can access the NGINX Instance Manager web interface to begin managing your deployment.

  1. Open a web browser.
  2. Navigate to https://<NIM_FQDN>, replacing <NIM_FQDN> with the fully qualified domain name of your NGINX Instance Manager host.
  3. Log in using the default administrator username (admin) and the autogenerated password displayed during installation.

Save the autogenerated password displayed at the end of the installation process. If you want to change the admin password, refer to the Set user passwords section in the Basic Authentication topic.

Using the script to uninstall NGINX Instance Manager and its dependencies

In some cases, the script may need to be re-run due to parameters not being set correctly, or wrong versions being specified. You can remove NGINX Instance Manager and all of its dependencies (including NGINX) so that the script can be re-run.

Potential for data loss The -r option removes all NGINX configuration files, NGINX Instance Manager, and ClickHouse. Once you run this command, the data is gone and cannot be recovered unless you have backups. Use this option only if you need to remove NGINX Instance Manager to re-run the script in a fresh environment for a new installation. See “Uninstall NGINX Instance Manager” below to perform these steps manually. If you do not want to lose your NGINX Configuration, you should take a backup of /etc/nginx/. 
bash install-nim-bundle.sh -r

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.

License NGINX Instance Manager

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

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.

Upgrade NGINX Instance Manager

  1. To upgrade to the latest version of the NGINX Instance Manager, run the following command:

    sudo yum update -y nms-instance-manager --allowerasing

  2. To upgrade to the latest version of Clickhouse, run the following command:

    sudo yum update -y clickhouse-server clickhouse-client

  1. To upgrade to the latest version of the NGINX Instance Manager, run the following commands:

    sudo apt-get update
sudo apt-get install -y --only-upgrade nms-instance-manager

  2. To upgrade to the latest version of ClickHouse, run the following commands:

    sudo apt-get update
sudo apt-get install -y --only-upgrade clickhouse-server clickhouse-client

  1. Restart the NGINX Instance Manager platform services:

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

  2. Restart the NGINX web server:

    sudo systemctl restart nginx

  3. Restart the Clickhouse server:

    sudo systemctl restart clickhouse-server

  4. (Optional) If you use SELinux, follow the steps in the Configure SELinux guide to restore the default SELinux labels (restorecon) for the 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.

Next steps