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.
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> \
-p <version> \
-v <version> \
-j <path/to/nginx-product.jwt>
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.
Note:
Starting from NGINX Plus Release 33, a JWT file is required for each NGINX Plus instance. For more information, see About Subscription Licenses.
Explanation of options:
-c
: Uses the specified SSL certificate file. Copies the file to the /etc/ssl/nginx directory.-k
: Uses the specified private key file. Copies the file to the /etc/ssl/nginx directory.-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.-v
: Installs the specified version of NGINX Instance Manager. Uselatest
for the newest version or a specific release like2.18.0
. If you skip this option, the script assumes you want to installlatest
.-j
: Uses the specified JWT token.
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