NGINX Plus R33 requires NGINX Instance Manager 2.18 or later
If your NGINX data plane instances are running NGINX Plus R33 or later, you must upgrade to NGINX Instance Manager 2.18 or later to support usage reporting. NGINX Plus R33 instances must report usage data to the F5 licensing endpoint or NGINX Instance Manager. Otherwise, they will stop processing user traffic.
For more details about usage reporting and enforcement, see About solution licenses.
Install in a disconnected environment
Legacy 'nms' references
Some commands, file paths, and configuration references still usenms
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 shows you 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 update the CVE list manually to keep your system secure.
Access the deprecated manual steps
If you prefer to follow the original manual steps, you can access the deprecated guide. Please note that this guide is no longer actively maintained and may not reflect the latest updates or best practices.
Before you begin
You’ll need internet access for the steps in this section.
Download the SSL Certificate and Private Key from MyF5
Download the SSL certificate and private key required for NGINX Instance Manager:
- Log in to MyF5.
- Go to My Products & Plans > Subscriptions to see your active subscriptions.
- Find your NGINX products or services subscription, and select the Subscription ID for details.
- Download the SSL Certificate and Private Key files.
Download and run the installation script
Download the install-nim-bundle.sh script.
To run the script, enter the following command, replacing <path/to/certificate.crt>
and <path/to/private.key>
with the full paths and filenames of your SSL certificate and private key files:
sudo bash install-nim-bundle.sh \
-c <path/to/certificate.crt> \
-k <path/to/private.key> \
-m offline \
-d <distribution>
By default, this command installs the latest version of NGINX Open Source. To install NGINX Plus or specify a different version of NGINX Open Source, use the -p
or -n
options as needed.
Explanation of options:
-c
: Path to the SSL certificate file.-k
: Path to the private key file.-m
: Sets the installation mode (useoffline
for disconnected environments).-d
: Defines the target distribution (replace<distribution>
with one of the supported options below).-n
: Installs a specific version of NGINX Open Source. Uselatest
to install the most recent version or specify a version like1.27.1
. If neither-n
nor-p
is specified, the script defaults to installing the latest version of NGINX Open Source.-p
: Installs the specified version of NGINX Plus. Uselatest
for the newest version or a specific release likeR32
. Overrides the-n
option if both are specified.
Supported distributions:
To get the latest list supported by the script, run the following command:
grep '\-d distribution' install-nim-bundle.sh
The script downloads the required packages and adds them to a tarball file. You’ll need to copy this tarball to the target machine in the disconnected environment.
Install NGINX Instance Manager
-
Copy the following files to the target system:
install-nim-bundle.sh
script- SSL certificate file
- Private key file
- Tarball file with the required packages
-
Run the installation script:
sudo bash install-nim-bundle.sh \ -c <path/to/certificate.crt> -k <path/to/private.key> \ -m offline \ -d <distribution> \ -i <path/to/tarball.tar.gz>
-
Save the admin 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.
-
After installation, open a web browser, go to
https://<NIM-FQDN>
(the fully qualified domain name of the NGINX Instance Manager host), and log in.
Set the operation mode to disconnected
-
Open the
/etc/nms/nms.conf
file and add the following in theintegrations: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:
-
Log in to the MyF5 Customer Portal and download the latest package files.
-
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-rootnms
user inside thenms
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