# Install NGINX Instance Manager using a script (disconnected)


> Use the install-nim-bundle.sh script to install or upgrade F5 NGINX Instance Manager in a disconnected (offline) environment.


**Note:** Some commands, file paths, and configuration references still use `nms` due to the ongoing transition from NGINX Management Suite (NMS) to NGINX Instance Manager (NIM). These will be updated in future releases.

## Overview

Use the `install-nim-bundle.sh` script to install and upgrade F5 NGINX Instance Manager in disconnected environments.

The script installs:

- The latest version of NGINX Open Source
- The latest version of NGINX Instance Manager
- ClickHouse, unless you choose to skip it

NGINX Plus is not supported in disconnected mode. To install earlier versions of NGINX or NGINX Instance Manager, use the [manual installation process](nim/disconnected/offline-install-guide-manual.md) instead.

---

## Before you begin

You’ll need internet access for the steps in this section.

### Prepare for installation

Before running `install-nim-bundle.sh`, address the following:

#### Handle an existing NGINX Instance Manager installation

The script supports only new installations. If NGINX Instance Manager is already installed, take one of the following actions:

- **Upgrade manually**
  The script can't perform upgrades. To update an existing installation, follow the [upgrade steps](#upgrade-nim) in this guide.

- **Uninstall first**
  To start fresh, use the [uninstall steps](#uninstall-nim) to remove the primary components, then manually check for and remove leftover files such as repository configurations or custom settings.

#### Verify SSL certificates and private keys

Make sure the required `.crt` and `.key` files are available, preferably in the default **/etc/ssl/nginx** directory. Missing certificates or keys will prevent the script from completing the installation.

#### Use manual installation if the script fails

If the script fails or you need more control, use the [manual installation steps](nim/disconnected/offline-install-guide-manual.md) instead.

### Download the SSL certificate and private key from MyF5

Download the SSL certificate and private key required for NGINX Instance Manager:

1. Log in to [MyF5](https://my.f5.com/manage/s/).
1. Go to **My Products & Plans > Subscriptions** to see your active subscriptions.
1. Find your NGINX products or services subscription, and select the **Subscription ID** for details.
1. Download the **SSL Certificate** and **Private Key** files.

### Download the installation script

[icon: download] [Download the install-nim-bundle.sh script.](/scripts/install-nim-bundle.sh)

## Package NGINX Instance Manager for offline installation

Run the script in `offline` mode to download NGINX Instance Manager, NGINX Open Source, ClickHouse (unless skipped), and all required dependencies into a tarball.

### Installation script options

| Category | Option or Flag |
|----------|----------------|
| **Installation mode and platform** | `-m offline`: Required to package the installation files into a tarball for disconnected environments.<br>`-d <distribution>`: Target Linux distribution (for example, `ubuntu22.04`, `rhel8`)

To see the list of supported distributions, run:

```shell
install-nim-bundle.sh -l
``` |
| **SSL certificate and key** | `-k <path/to/nginx-repo.key>`: Path to the downloaded private key file, the script will rename it to `nginx-repo.key` and copy to `/etc/ssl/nginx`. |
| **NGINX installation** | `-n`: Include the latest version of NGINX Open Source in the tarball.<br><br>This option is optional in `offline` mode—if not specified, the script installs the latest version of NGINX Open Source by default.<br><br>NGINX Plus is **not supported** when using the script in offline mode.<br><br>To install NGINX Plus offline, see the [manual installation guide](nginx/admin-guide/installing-nginx/installing-nginx-plus.md#offline_install). |
| **ClickHouse installation** | `-v <clickhouse-version>`: Install a specific version of ClickHouse. If not set, version `` is installed by default. |

### Example: packaging command

  ```shell
  sudo bash install-nim-bundle.sh \
  -c <PATH/TO/NGINX_REPO.CRT> \
  -k <PATH/TO/NGINX_REPO.KEY> \
  -m offline \
  -d <DISTRIBUTION> \
  -v <CLICKHOUSE_VERSION>
  ```

---

## Install NGINX Instance Manager

After you’ve packaged the installation files on a connected system, copy the tarball, script, and SSL files to your disconnected system. Then, run the script again to install NGINX Instance Manager using the tarball.

## OS dependencies for offline installation

The installation script packages NGINX Open Source, NGINX Instance Manager, and ClickHouse. In offline mode, these packages are bundled but their OS-level dependencies are not. Make sure those dependencies are installed before running the script. The following packages are required for each supported distribution type:

### Debian/Ubuntu

- NGINX: libc6, libcrypt1, libpcre2-8-0, libssl3, zlib1g, lsb-base
- NGINX Instance Manager: openssl, rsyslog, systemd, tar, lsb-release, gawk
- ClickHouse: libcap2-bin

### Red Hat-based operating systems

- NGINX: bash, glibc, libxcrypt, openssl-libs, pcre2, zlib, procps-ng, shadow-utils, systemd
- NGINX Instance Manager: glibc, openssl, rsyslog, systemd, tar, which, zlib, yum-utils
- ClickHouse: none

To find the latest dependencies for a specific package version:

- Ubuntu/Debian: `apt-cache depends <PACKAGE_NAME>=<VERSION>`
- Red Hat: `yum deplist <PACKAGE_NAME_VERSION>`

### Required flags for installing in offline mode

- `-m offline`: Required to run the script in offline mode. When used with `-i`, the script installs NGINX Instance Manager and its dependencies from the specified tarball.
- `-i <path/to/tarball.tar.gz>`: Path to the tarball created during the packaging step.
- `-c <path/to/nginx-repo.crt>`: Path to the downloaded SSL certificate file, the script will rename it to `nginx-repo.crt` and copy to `/etc/ssl/nginx`.
- `-k <path/to/nginx-repo.key>`: Path to the downloaded private key file, the script will rename it to `nginx-repo.key` and copy to `/etc/ssl/nginx`.
- `-d <DISTRIBUTION>`: Target Linux distribution (must match what was used during packaging).

### Install from the tarball

1. 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

2. Run the installation script:

    ```shell
    sudo bash install-nim-bundle.sh \
    -m offline
    -i <PATH/TO/TARBALL.TAR.GZ>
    -c <PATH/TO/NGINX_REPO.CRT>
    -k <PATH/TO/NGINX_REPO.KEY> \
    -d <DISTRIBUTION>
    ```

3. **Save the admin password**. After installation completes, the script takes a few minutes to generate a password. At the end of the process, you'll see:

    ```shell
    Regenerated Admin password: <encrypted password>
    ```

    Save that password. You'll need it when you sign in to NGINX Instance Manager.

4. After installation, open a browser, go to `https://<NIM_FQDN>`, and log in.

---

## Set the operation mode to disconnected {#set-mode-disconnected}

1. Open the `/etc/nms/nms.conf` file and add the following in the `integrations:license` section:

    ``` yaml
    integrations:
        license:
            mode_of_operation: disconnected
    ```

2.	Restart NGINX Instance Manager:

    ```shell
    sudo systemctl restart nms
    ```

---

## Optional post-installation steps

### 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](nim/system-configuration/configure-clickhouse.md).

### Disable metrics collection

If you’re not collecting metrics — because you didn’t install ClickHouse or don’t plan to use it — you must disable metrics collection in the `/etc/nms/nms.conf` and `/etc/nms/nms-sm-conf.yaml` files. This setup requires NGINX Agent version .

For instructions, see [Disable metrics collection](nim/system-configuration/configure-clickhouse.md#disable-metrics-collection).

### Install and configure Vault {#install-vault}

NGINX Instance Manager can use [Vault](https://www.vaultproject.io/) 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](https://developer.hashicorp.com/vault/install) for your operating system.
- Ensure you're running Vault in a [production-hardened environment](https://learn.hashicorp.com/tutorials/vault/production-hardening).
- After installing NGINX Instance Manager, follow the steps to [configure Vault for storing secrets](/nim/system-configuration/configure-vault.md).

### Configure SELinux

SELinux helps secure your deployment by enforcing mandatory access control policies.

If you use SELinux, follow the steps in the [Configure SELinux](/nim/system-configuration/configure-selinux.md) guide to restore SELinux contexts (`restorecon`) for the files and directories related to NGINX Instance Manager.

---

## Upgrade NGINX Instance Manager {#upgrade-nim}

To upgrade NGINX Instance Manager to a newer version:

1. Log in to the [MyF5 Customer Portal](https://account.f5.com/myf5) and download the latest package files.
2. Upgrade the package:
   - **For RHEL and RPM-based systems**:

        ```shell
        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**:

        ```shell
        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.

3.	(Optional) If you use SELinux, follow the [Configure SELinux](/nim/system-configuration/configure-selinux.md) guide to restore SELinux contexts using restorecon for files and directories related to NGINX Instance Manager.

---

## Uninstall NGINX Instance Manager {#uninstall-nim}

Follow the steps below to uninstall NGINX Instance Manager and ClickHouse.

- **For CentOS, RHEL, and RPM-based distributions:**

   ```shell
   sudo yum remove -y nms-*
   sudo systemctl stop clickhouse-server
   sudo yum remove -y clickhouse-server
   ```

- **For Debian, Ubuntu, and Deb-based distributions:**

   ```shell
   sudo apt-get remove -y nms-*
   sudo systemctl stop clickhouse-server
   sudo apt-get remove -y clickhouse-server
   ```

	If you want to remove the package and its configuration files, use `apt-get purge -y <package>` instead of `apt-get remove -y`.

---

## Update the CVE list {#cve-check}

To manually update the CVE list in an air-gapped environment, run the following command to overwrite `cve.xml` and restart the Data Plane Manager service:

```shell
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
```

---

## Next steps

- [Add NGINX Open Source and NGINX Plus instances to NGINX Instance Manager](nim/nginx-instances/add-instance.md)