Manually install any version of NGINX Instance Manager

Overview

Overview

Follow the steps in this guide to install or upgrade a specific version of NGINX Instance Manager.

Before You Begin

Before You Begin

Security Considerations

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

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

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.

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

   Copy

   sudo mkdir -p /etc/ssl/nginx

   sudo mkdir -p /etc/ssl/nginx

2. Download the NGINX Instance Manager .crt and .key files from MyF5 or follow the download link in your trial activation email.

3. Move and rename the .crt and .key files:

   bash

   Copy

   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

   The downloaded filenames may vary depending on your subscription type. Modify the commands above accordingly to match the actual filenames.

Install NGINX

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

  
  

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

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

Configure metrics collection

Configure metrics collection

Disable metrics collection

Disable metrics collection

NGINX Instance Manager uses ClickHouse to store metrics, events, alerts, and configuration data.

Starting in version 2.20.0, you can run NGINX Instance Manager in Lightweight mode, which skips the ClickHouse installation entirely. This setup works well if you don’t need monitoring data or want to reduce system requirements. It also avoids the effort of managing a metrics database. You can add ClickHouse later if your needs change.

If you don’t need to store metrics, you can skip installing ClickHouse. But you must use NGINX Agent version 2.41.1 or later, and you must disable metrics collection in the /etc/nms/nms.conf and /etc/nms-sm.conf.yaml files.

For instructions, see Disable metrics collection.

Install ClickHouse to enable metrics

Install ClickHouse to enable metrics

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

If you install ClickHouse and choose to 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. If the password is missing or incorrect, NGINX Instance Manager will not start.

For instructions and additional configuration options, including TLS settings, see Configure ClickHouse.

NGINX Instance Manager requires ClickHouse version 24.8.12.28 or later.

Follow these steps to install and enable ClickHouse on supported Linux distributions.

1. First, set up the repository.

   • For RPM-based systems (CentOS, RHEL):

     shell

     Copy

     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

   • For Debian-based systems (Debian, Ubuntu):

     shell

     Copy

     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

2. Next, install the ClickHouse server and client:

   • For RPM-based systems (CentOS, RHEL):

     Copy

     sudo yum install -y clickhouse-server clickhouse-client

     sudo yum install -y clickhouse-server clickhouse-client

   • For Debian-based systems (Debian, Ubuntu):

     Copy

     sudo apt-get install -y clickhouse-server clickhouse-client

     sudo apt-get install -y clickhouse-server clickhouse-client

3. Then, enable the ClickHouse service so it starts automatically on reboot:

   Copy

   sudo systemctl enable clickhouse-server

   sudo systemctl enable clickhouse-server

4. Start the ClickHouse service:

   Copy

   sudo systemctl start clickhouse-server

   sudo systemctl start clickhouse-server

5. Finally, confirm the service is running:

   Copy

   sudo systemctl status clickhouse-server

   sudo systemctl status clickhouse-server

ClickHouse Default Settings

ClickHouse Default Settings

NGINX Instance Manager uses the following default values for ClickHouse. To change these values, see the Configure ClickHouse guide.

Add NGINX Instance Manager Repository

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.

wget -qO - https://cs.nginx.com/static/keys/nginx_signing.key \
    | gpg --dearmor \
    | sudo tee /usr/share/keyrings/nginx-archive-keyring.gpg >/dev/null 

wget -qO - https://cs.nginx.com/static/keys/nginx_signing.key \
    | gpg --dearmor \
    | sudo tee /usr/share/keyrings/nginx-archive-keyring.gpg >/dev/null 

Install Instance Manager

Install Instance Manager

2. Enable and start the NGINX Instance Manager platform services:

   Copy

   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.

3. Restart the NGINX web server:

   Copy

   sudo systemctl restart nginx

   sudo systemctl restart nginx

Optional post-installation steps

Optional post-installation steps

Configure ClickHouse

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.

Install and configure Vault

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.

Configure SELinux

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.

Accessing the Web Interface

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

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

Upgrade Instance Manager

2. Restart the NGINX Instance Manager platform services:

   Copy

   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.

3. Restart the NGINX web server:

   Copy

   sudo systemctl restart nginx

   sudo systemctl restart nginx

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

Next steps

Next steps

• Add NGINX Open Source and NGINX Plus instances to NGINX Instance Manager