Install in a disconnected environment (deprecated)

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.

Overview

This guide explains how to install and upgrade NGINX Instance Manager in environments without Internet access. It covers key steps, including downloading packages, managing dependencies, and configuring the system for offline use. You’ll also learn how to set up NGINX Instance Manager in disconnected mode and manually update the CVE list to keep your system secure.

Before you begin

Complete the required prerequisites
You must complete the following prerequisite steps before installing NGINX Instance Manager. Skipping these steps could cause installation issues.

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).
Make sure no other services are running on the same machine.
Ensure the machine is not accessible from the Internet.
Place the machine behind a firewall.

Download package files

To complete the steps in this guide, you need to download the NGINX Instance Manager package files from the MyF5 Customer Portal.

Install local dependencies

Local dependencies are common Linux packages like curl or openssl, which most Linux distributions include by default. When installing NGINX Instance Manager, your package manager will automatically install these dependencies. Without internet access, ensure your package manager can use a local package repository, such as a distribution DVD/ISO image or internal network mirror. Check your Linux distribution’s documentation for details.

RedHat on AWS
If you’re using AWS and can’t attach remote or local RedHat package repositories, download the necessary packages on another RedHat machine and copy them to your target machine. Use the yumdownloader utility for this task: https://access.redhat.com/solutions/10154.

Download and install external dependencies

External dependencies, such as ClickHouse and NGINX Plus, aren’t included by default in standard Linux distributions. You need to manually download and transfer these to your offline system.

To download external dependencies:

Download the fetch-external-dependencies.sh script:

Download fetch-external-dependencies.sh script
Run the script to download the external dependencies for your specific Linux distribution:
```
sudo bash fetch-external-dependencies.sh <linux distribution>
```
Supported Linux distributions:
- ubuntu20.04
- ubuntu22.04
- debian11
- debian12
- oracle7
- oracle8
- rhel8
- rhel9
- amzn2
For example, to download external dependencies for Ubuntu 20.04:
```
sudo bash fetch-external-dependencies.sh ubuntu20.04
```
This will create an archive, such as nms-dependencies-ubuntu20.04.tar.gz, containing the required dependencies.
Copy the archive to your target machine and extract the contents:

Note:
The bundled NGINX server package may conflict with existing versions of NGINX or NGINX Plus. Delete the package from the bundle if you want to keep your current version.
- For RHEL and RPM-Based systems:
```
tar -kzxvf nms-dependencies-<linux-distribution>.tar.gz
sudo rpm -ivh *.rpm
```
- For Debian, Ubuntu, Deb-based systems:
```
tar -kzxvf nms-dependencies-<linux-distribution>.tar.gz
sudo dpkg -i ./*.deb
```
Setting a custom ClickHouse password
When installing ClickHouse, you can set a password or leave it blank (default is an empty string). If you set a password, make sure to 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.

Install NGINX Instance Manager

Log in to the MyF5 Customer Portal and download the NGINX Instance Manager package files.
Install the NGINX Instance Manager package:
- For RHEL and RPM-based systems:
```
sudo rpm -ivh --nosignature /home/<user>/nms-instance-manager_<version>.x86_64.rpm
```
- For Debian, Ubuntu, Deb-based systems:
```
sudo apt-get -y install -f /home/<user>/nms-instance-manager_<version>_amd64.deb
```
Save the password!
The administrator username (default: admin) and the generated password are displayed in the terminal during installation. Be sure to record the password and store it securely.
Enable and start NGINX Instance Manager services:
```
sudo systemctl enable nms nms-core nms-dpm nms-ingestion nms-integrations --now
```
Note:
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
```

Set the operation mode to disconnected

Open the /etc/nms/nms.conf file and add the following in the integrations:license section:
```
integrations:
    license:
        mode_of_operation: disconnected
```
Restart NGINX Instance Manager:
```
sudo systemctl restart nms
```

Post-installation steps (optional)

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.

Upgrade NGINX Instance Manager

To upgrade NGINX Instance Manager to a newer version:

Upgrade the package:

For RHEL and RPM-based systems:

sudo rpm -Uvh --nosignature /home/user/nms-instance-manager_<version>.x86_64.rpm
sudo systemctl restart nms
sudo systemctl restart nginx

For Debian, Ubuntu, Deb-based systems:

sudo apt-get -y install -f /home/user/nms-instance-manager_<version>_amd64.deb
sudo systemctl restart nms
sudo systemctl restart nginx

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

(Optional) If you use SELinux, follow the Configure SELinux guide to restore SELinux contexts using restorecon for files and directories related to NGINX Instance Manager.

CVE checking

To manually update the CVE list in an air-gapped environment, follow these steps to download and overwrite the cve.xml file in the /usr/share/nms directory and restart the Data Plane Manager service:

sudo chmod 777 /usr/share/nms/cve.xml && \
sudo curl -s http://hg.nginx.org/nginx.org/raw-file/tip/xml/en/security_advisories.xml > /usr/share/nms/cve.xml && \
sudo chmod 644 /usr/share/nms/cve.xml && \
sudo systemctl restart nms-dpm

Last modified November 8, 2024