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.

Manually install on a virtual machine or bare metal (deprecated)

Overview

Follow the steps in this guide to install or upgrade NGINX Instance Manager.

Deprecated documentation notice
This document outlines manual steps that have been replaced by a simplified script-based process. For most users, we recommend using the updated process documented here.

Before You Begin

Security Considerations

To ensure that your NGINX Instance Manager deployment remains secure, follow the recommendations in this section:

Install NGINX Instance Manager and its modules on a dedicated machine (bare metal, container, cloud, or VM).
Make sure that no other services are running on the same machine.
Make sure that the machine is not accessible from the Internet.
Make sure that the machine is behind a firewall.

Requirements

To install NGINX Instance Manager, you need the following:

A trial or paid subscription for NGINX Instance Manager. Sign up for NGINX Instance Manager at MyF5.
A Linux instance to host the NGINX Instance Manager platform and modules
NGINX Plus or NGINX OSS installed on the instance hosting NGINX Instance Manager

Allow external systems access by opening network firewalls. NGINX Instance Manager uses port 443 for both gRPC and API/web interfaces.

Download Certificate and Key

Follow these steps to download the certificate and private key for NGINX Instance Manager. You’ll need these files when adding the official repository for installing NGINX Instance Manager. You can also use the certificate and key 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 NGINX Instance Manager .crt and .key files from MyF5 or follow the download link in your trial activation email.
Move and rename the .crt and .key files:
```
sudo mv <nginx-mgmt-suite-trial.crt> /etc/ssl/nginx/nginx-repo.crt
sudo mv <nginx-mgmt-suite-trial.key> /etc/ssl/nginx/nginx-repo.key
```
Note:
The downloaded filenames may vary depending on your subscription type. Modify the commands above accordingly to match the actual filenames.

Install NGINX

Install NGINX Open Source or NGINX Plus on the host where you’ll install NGINX Instance Manager. NGINX Instance Manager uses NGINX as a front-end proxy and for managing user access.

Installing NGINX and NGINX Plus

Note:
If you’re installing NGINX Plus, you can use the nginx-repo.key and nginx-repo.crt that you added in the previous section.

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

See Also:
Make sure to review the Technical Specifications guide for sizing requirements and other recommended specs.

Install ClickHouse

Note:
NGINX Instance Manager requires ClickHouse 22.3.15.33 or later.

NGINX Instance Manager uses ClickHouse to store metrics, events, and alerts, as well as configuration settings.

Select the tab for your Linux distribution, then follow the instructions to install ClickHouse.

CentOS, RHEL, RPM-Based
Debian, Ubuntu, Deb-Based

To install and enable ClickHouse CentOS, RHEL, and RPM-Based distributions, take the following steps:

Set up the repository:

sudo yum install -y yum-utils
sudo yum-config-manager --add-repo https://packages.clickhouse.com/rpm/clickhouse.repo

Install the ClickHouse server and client:
```
sudo yum install -y clickhouse-server clickhouse-client
```
IMPORTANT! When installing ClickHouse, you have the option to specify a password or leave the password blank (the default is an empty string). If you choose to specify a password for ClickHouse, you must also edit the /etc/nms/nms.conf file after installing NGINX Instance Manager and enter your ClickHouse password; otherwise, NGINX Instance Manager won’t start.

For more information on customizing ClickHouse settings, refer to the Configure ClickHouse topic.
Enable ClickHouse so that it starts automatically if the server is restarted:
```
sudo systemctl enable clickhouse-server
```
Start the ClickHouse server:
```
sudo systemctl start clickhouse-server
```

Verify ClickHouse is running:

sudo systemctl status clickhouse-server

To install and enable ClickHouse on Debian, Ubuntu, and Deb-Based distributions, take the following steps:

Set up the repository:

sudo apt-get install -y apt-transport-https ca-certificates dirmngr
GNUPGHOME=$(mktemp -d)
sudo GNUPGHOME="$GNUPGHOME" gpg --no-default-keyring --keyring /usr/share/keyrings/clickhouse-keyring.gpg --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys 8919F6BD2B48D754
sudo rm -r "$GNUPGHOME"
sudo chmod +r /usr/share/keyrings/clickhouse-keyring.gpg

echo "deb [signed-by=/usr/share/keyrings/clickhouse-keyring.gpg] https://packages.clickhouse.com/deb lts main" | sudo tee /etc/apt/sources.list.d/clickhouse.list
sudo apt-get update

Install the ClickHouse server and client:
```
sudo apt-get install -y clickhouse-server clickhouse-client
```
IMPORTANT! When installing ClickHouse, you have the option to specify a password or leave the password blank (the default is an empty string). If you choose to specify a password for ClickHouse, you must also edit the /etc/nms/nms.conf file after installing NGINX Instance Manager and enter your ClickHouse password; otherwise, NGINX Instance Manager won’t start.

For more information on customizing ClickHouse settings, refer to the Configure ClickHouse topic.
Enable ClickHouse so that it starts automatically if the server is restarted:
```
sudo systemctl enable clickhouse-server
```
Start the ClickHouse server:
```
sudo systemctl start clickhouse-server
```

Verify ClickHouse is running:

sudo systemctl status clickhouse-server

ClickHouse Default Settings

NGINX Instance Manager uses the following default values for ClickHouse:

Important:
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, take the following steps:

Follow Vault’s instructions to install Vault 1.8.8 or later for your distribution.
Ensure you are running Vault in a Production Hardened Environment.
After installing NGINX Instance Manager, follow the steps to Configure Vault for Storing Secrets.

Add NGINX Instance Manager Repository

To install NGINX Instance Manager, you need to add the official repository to pull the pre-compiled deb and rpm packages from.

Select the tab matching your Linux distribution, then follow the instructions to add the NGINX Instance Manager repository.

CentOS, RHEL, RPM-Based
Debian, Ubuntu, Deb-Based

Add the NGINX Instance Manager repository:

CentOS/RHEL
```
sudo wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/nms.repo
```
- RHEL 8: If you’re installing on RHEL 8 and using the distro’s NGINX, run the following commands to use the new version of NGINX (1.20 at the time of this update):
```
sudo yum module disable nginx:1.14
sudo yum module enable nginx:1.20
```

Amazon Linux 2

sudo wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/nms-amazon2.repo

Add the NGINX Instance Manager repository:

Debian

printf "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] https://pkgs.nginx.com/nms/debian `lsb_release -cs` nginx-plus\n" | sudo tee /etc/apt/sources.list.d/nms.list
sudo wget -q -O /etc/apt/apt.conf.d/90pkgs-nginx https://cs.nginx.com/static/files/90pkgs-nginx

Ubuntu

printf "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] https://pkgs.nginx.com/nms/ubuntu `lsb_release -cs` nginx-plus\n" | sudo tee /etc/apt/sources.list.d/nms.list
sudo wget -q -O /etc/apt/apt.conf.d/90pkgs-nginx https://cs.nginx.com/static/files/90pkgs-nginx

To install the latest version of Instance Manager, run the following command:
```
sudo yum install -y nms-instance-manager
```
IMPORTANT! The Instance Manager’s administrator username (default is admin) and generated password are displayed in the terminal during installation. You should make a note of the password and store it securely.

To install the latest version of Instance Manager, run the following commands:
```
sudo apt-get update
sudo apt-get install -y nms-instance-manager
```
IMPORTANT! The Instance Manager’s administrator username (default is admin) and generated password are displayed in the terminal during installation. You should make a note of the password and store it securely.

Enable and start the NGINX Instance Manager platform services:
```
sudo systemctl enable nms nms-core nms-dpm nms-ingestion nms-integrations --now
```
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
```

Post-Installation Steps

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.

Accessing the Web Interface

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

The default administrator username is admin, and the generated 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.

Add License

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 Instance Manager

CentOS, RHEL, RPM-Based
Debian, Ubuntu, Deb-Based

To upgrade to the latest version of the Instance Manger, run the following command:
```
sudo yum update -y nms-instance-manager
```

To upgrade to the latest version of the Instance Manager, run the following command:
```
sudo apt-get update
sudo apt-get install -y --only-upgrade nms-instance-manager
```

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
```
(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 Management suite.