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 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 explains how to install F5 NGINX Instance Manager on a virtual machine or bare metal system using the install-nim-bundle.sh script.

The script simplifies the installation by automating tasks such as verifying system requirements, configuring services, and managing environment-specific options. For more control or an alternative approach, you can refer to the manual installation guide, which provides detailed, step-by-step instructions.

Before you begin

Follow these steps to prepare for installing NGINX Instance Manager:

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.
Record the version details:
Note the current version of NGINX Instance Manager and confirm the supported version of NGINX OSS or NGINX Plus you intend to use.
- By default, the script installs the latest version.
(Optional) Install and configure Vault:
If you plan to use Vault, set it up before proceeding.

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.

Requirements

Supported NGINX versions and Linux distributions

Supported NGINX versions

NGINX Instance Manager supports the following NGINX Open Source and NGINX Plus versions:

NGINX Instance Manager	NGINX OSS	NGINX Plus
2.18.0 and later	1.18–1.25.1	R31–R33
2.16.0–2.17.x	1.18–1.25.1	R31–R32
2.7.0–2.15.x	1.18–1.25.1	R21–R30
2.0.0–2.6.0	1.18–1.21.6	R21–R27

Supported Linux distributions

The following table lists the Linux distributions supported by NGINX Instance Manager and NGINX App Protect:

Distribution	Version	Architecture	NGINX Instance Manager Support	NGINX App Protect Support
Amazon Linux	2 LTS	x86_64	Supported	Support discontinued as of 2.18.0
CentOS	7.4 and later in the 7.x family	x86_64	Support discontinued as of 2.17.0	Supported
Debian	11 12	x86_64 x86_64	Supported Supported on 2.13.0+	Supported Supported
Oracle Linux	7.4 and later in the 7.x family 8.0 and later in the 8.x family	x86_64 x86_64	Supported Supported on 2.6.0+	Supported Supported
RHEL	7.4 and later in the 7.x family 8.x and later in the 8.x family 9.x and later in the 9.x family	x86_64 x86_64 x86_64	Support discontinued as of 2.17.0 Supported Supported on 2.6.0+	Supported Supported Supported
Ubuntu	20.04 22.04	x86_64 x86_64	Supported Supported on 2.3.0+	Supported Supported

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.

On the host where you’re installing NGINX Instance Manager, create the /etc/ssl/nginx/ directory:
```
sudo mkdir -p /etc/ssl/nginx
```
Download the SSL Certificate, Private Key and JSON Web Token files from MyF5 or use the download link provided in your trial activation email.

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

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.

Run the installation script

The install-nim-bundle.sh script automates the installation of NGINX Instance Manager. By default, the script:

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

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

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.

Open a web browser.
Navigate to https://<NIM_FQDN>, replacing <NIM_FQDN> with the fully qualified domain name of your NGINX Instance Manager host.
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.

Post-installation steps

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.

Configuration	Default	Notes
clickhouse.address	tcp://localhost:9000
clickhouse.username
clickhouse.password
clickhouse.tls_mode	false
clickhouse.tls.address	tcp://localhost:9440
clickhouse.tls.skip_verify	false	`clickhouse.tls.skip_verify` should be used only for self-signed certificates and is never recommended for production use. When set to `true`, certificates are not verified, which exposes the connection to man-in-the-middle attacks.
clickhouse.tls.key_path
clickhouse.tls.cert_path
clickhouse.tls.ca_path	/etc/ssl/certs/ca-certificates.crt	The default value for `clickhouse.tls.ca_path` works out-of-the-box for Ubuntu and Debian. You’ll need to configure a different Certificate Authority for other distributions. Refer to your distribution’s documentation for additional information.

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

(Optional) 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.

To upgrade to the latest version of the NGINX Instance Manager, run the following command:
```
sudo yum update -y nms-instance-manager
```
To upgrade to the latest version of Clickhouse, run the following command:
```
sudo yum update -y clickhouse-server clickhouse-client
```

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
```

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

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.
Restart the NGINX web server:
```
sudo systemctl restart nginx
```

Restart the Clickhouse server:

sudo systemctl restart clickhouse-server

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