Manually install on a virtual machine or bare metal (deprecated) (original) (raw)
- Home
- NGINX Instance Manager
- Deploy
- Virtual Machine or Bare Metal Manually install on a virtual machine or bare metal (deprecated)
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.
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.
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.
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 sudo mkdir -p /etc/ssl/nginx - Download the NGINX Instance Manager
.crtand.keyfiles from MyF5 or follow the download link in your trial activation email. - Move and rename the
.crtand.keyfiles:
bash
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 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.
The downloaded filenames may vary depending on your subscription type. Modify the commands above accordingly to match the actual filenames.
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.keyandnginx-repo.crtthat you added in the previous section.
If you’re installing NGINX Plus, you can use thenginx-repo.keyandnginx-repo.crtthat 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 |
| 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 | 1112 | x86_64x86_64 | SupportedSupported on 2.13.0+ | SupportedSupported |
| Oracle Linux | 7.4 and later in the 7.x family8.0 and later in the 8.x family | x86_64x86_64 | SupportedSupported on 2.6.0+ | SupportedSupported |
| RHEL | 7.4 and later in the 7.x family8.x and later in the 8.x family9.x and later in the 9.x family | x86_64x86_64x86_64 | Support discontinued as of 2.17.0SupportedSupported on 2.6.0+ | SupportedSupportedSupported |
| Ubuntu | 20.0422.0424.04 | x86_64x86_64x86_64 | SupportedSupported on 2.3.0+Supported on 2.18.0+ | SupportedSupportedSupported |
| 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 | 1112 | x86_64x86_64 | SupportedSupported on 2.13.0+ | SupportedSupported |
| Oracle Linux | 7.4 and later in the 7.x family8.0 and later in the 8.x family | x86_64x86_64 | SupportedSupported on 2.6.0+ | SupportedSupported |
| RHEL | 7.4 and later in the 7.x family8.x and later in the 8.x family9.x and later in the 9.x family | x86_64x86_64x86_64 | Support discontinued as of 2.17.0SupportedSupported on 2.6.0+ | SupportedSupportedSupported |
| Ubuntu | 20.0422.0424.04 | x86_64x86_64x86_64 | SupportedSupported on 2.3.0+Supported on 2.18.0+ | SupportedSupportedSupported |
See Also: Make sure to review the Technical Specifications guide for sizing requirements and other recommended specs.
Make sure to review the Technical Specifications guide for sizing requirements and other recommended specs.
Note: NGINX Instance Manager requires ClickHouse 22.3.15.33 or later.
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.
To install and enable ClickHouse CentOS, RHEL, and RPM-Based distributions, take the following steps:
- Set up the repository:
bash
sudo yum install -y yum-utils
sudo yum-config-manager --add-repo https://packages.clickhouse.com/rpm/clickhouse.repo 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 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.conffile 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. 3. Enable ClickHouse so that it starts automatically if the server is restarted:
sudo systemctl enable clickhouse-server sudo systemctl enable clickhouse-server - Start the ClickHouse server:
sudo systemctl start clickhouse-server sudo systemctl start clickhouse-server - Verify ClickHouse is running:
sudo systemctl status clickhouse-server 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:
bash
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 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 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.conffile 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. 3. Enable ClickHouse so that it starts automatically if the server is restarted:
sudo systemctl enable clickhouse-server sudo systemctl enable clickhouse-server - Start the ClickHouse server:
sudo systemctl start clickhouse-server sudo systemctl start clickhouse-server - Verify ClickHouse is running:
sudo systemctl status clickhouse-server 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.conffile after you’ve installed NGINX Instance Manager; otherwise NGINX Instance Manager won’t be able to connect to ClickHouse.
You can customize these settings. However, if you use custom settings, make sure to follow the Configure ClickHouse instructions to update the
nms.conffile 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. |
| 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.
Add the NGINX Instance Manager repository:
- CentOS/RHEL
sudo wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/nms.repo 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):
bash
sudo yum module disable nginx:1.14
sudo yum module enable nginx:1.20 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 sudo wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/nms-amazon2.repo Add the NGINX Instance Manager repository:
- Debian
shell
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 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
shell
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 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 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:
bash
sudo apt-get update
sudo apt-get install -y nms-instance-manager 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 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.
2. Restart the NGINX web server:
sudo systemctl restart nginx sudo systemctl restart nginx 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.conffile. 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.conffile. 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.
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 Instance Manager, run the following command:
sudo yum update -y nms-instance-manager sudo yum update -y nms-instance-manager - To upgrade to the latest version of the Instance Manager, run the following command:
bash
sudo apt-get update
sudo apt-get install -y --only-upgrade nms-instance-manager 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 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 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.