Important: NGINX Plus R33 requires NGINX Instance Manager 2.18 or later
To ensure uninterrupted traffic processing, upgrade to NGINX Instance Manager 2.18 or later if your NGINX data plane instances are running NGINX Plus R33. This upgrade is necessary to support usage reporting.

NGINX Plus R33 instances must send usage data to the F5 licensing endpoint or NGINX Instance Manager. If they don’t, they will stop processing traffic.

For more information about usage reporting and enforcement, see About solution licenses.

Install on a virtual machine or bare metal

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 explains how to install F5 NGINX Instance Manager on a virtual machine (VM) or bare metal. It includes key steps like:

• Installing NGINX with the GPG keys associated with F5 NGINX One
• Setting up ClickHouse
• Adding a license
• Accessing the web interface
• Securing your deployment with Vault (optional)

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.

Supported versions

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.

Prerequisites

Complete the following steps before installing NGINX Instance Manager:

• Download the certificate and private key for NGINX Instance Manager. You can use the same certificate and private key as NGINX Plus.
  • The downloaded files have .crt and .key extensions
  • Record the location of these files on the target system. The default filenames / locations are:
    • /etc/ssl/nginx/nginx-repo.crt
    • /etc/ssl/nginx/nginx-repo.key
• Record your current version of NGINX Instance Manager, along with the supported version of NGINX OSS or NGINX Plus that you want to use, if necessary. The latest version will be used by default.
• (Optional) Install and configure Vault if you plan to use it.

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
   

Download and run the installation script

Tip:
The installation script also works for upgrades of both NGINX Instance Manager and ClickHouse.

We created an installation script, install-nim-bundle.sh to automate the NGINX Instance Manager installation process. By default, it:

• Reads SSL files from the /etc/ssl/nginx directory
• Installs the latest version of NGINX OSS
• Installs Clickhouse Database
• Installs NGINX Instance Manager
• Assumes you’re connected to the internet for installations and upgrades

Warning:
As noted in About subscription licenses, custom paths won’t work until you upgrade to NGINX Plus R33.

Download the install-nim-bundle.sh script:

Download install-nim-bundle.sh script

When you run the script, it downloads and installs NGINX Instance Manager.

If you want to use the script with non-default options, use these switches:

• To point to a repository key stored in a directory other than /etc/ssl/nginx: -k /path/to/your/<nginx-repo.key> file
• To point to a repository certificate stored in a directory other than /etc/ssl/nginx: -c /path/to/your/<nginx-repo.crt> file
• To install NGINX Plus (instead of NGINX OSS): -p <nginx_plus_version> -j /path/to/license.jwt

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

You also need to specify the current operating system. To get the latest list supported by the script, run the following command:

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

For example, 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 OSS, run the following command:

sudo bash install-nim-bundle.sh -n latest -d ubuntu24.04 -j /path/to/license.jwt

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 latest -d ubuntu24.04 -j /path/to/license.jwt

In most cases, the script completes the installation of NGINX Instance Manager and associated packages. 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.

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

Configure ClickHouse

ClickHouse version requirement
NGINX Instance Manager relies on ClickHouse 24.9.2.42 or later to store essential data, including metrics, events, alerts, and configuration settings.

Setting a custom ClickHouse password
The NGINX Instance Manager installation script also installs ClickHouse with a blank password. Update the /etc/nms/nms.conf file with it after installing NGINX Instance Manager. Otherwise, NGINX Instance Manager won’t start. For more information on customizing ClickHouse settings, refer to the Configure ClickHouse topic.

ClickHouse default settings

NGINX Instance Manager uses the following default values for ClickHouse:

Customizing ClickHouse
You can customize these settings. However, if you use custom settings, make sure to follow the Configure ClickHouse instructions to update the nms.conf file after you’ve installed NGINX Instance Manager. Otherwise, NGINX Instance Manager won’t be able to connect to ClickHouse.

How to access the web interface

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

The default administrator username is admin, and the generated password is saved, in encrypted format, to the /etc/nms/nginx/.htpasswd file. The 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.

To license NGINX Instance Manager, use a JSON Web token from your NIM Subscription in MyF5.

Post-installation steps (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 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.

(Optional) Install and configure Vault

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

To install and enable Vault, follow these steps:

• Follow Vault’s instructions to install Vault 1.8.8 or later for your distribution.
• Ensure you’re running Vault in a production-hardened environment.
• After installing NGINX Instance Manager, follow the steps to configure Vault for storing secrets.

Upgrade NGINX Instance Manager

You can now use the installation script to upgrade NGINX Instance Manager and ClickHouse.

If you use SELinux, after an upgrade, follow the steps in the Configure SELinux guide to restore the default SELinux labels (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.