# Install NGINX Instance Manager using a script


> Install or upgrade F5 NGINX Instance Manager on a virtual machine or bare metal system using the automated installation script.


**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

This guide shows you how to install and upgrade F5 NGINX Instance Manager on a virtual machine or bare metal system using the installation script in online mode.

The script installs:

- The latest version of NGINX Open Source, required for running NGINX Instance Manager
- Optionally, NGINX Plus instead of NGINX Open Source (requires a license and additional flags)
- The latest version of NGINX Instance Manager
- ClickHouse by default, unless you choose to skip it

The script also installs all required operating system packages automatically. If you need to install earlier versions of NGINX or NGINX Instance Manager, follow the [manual installation process](nim/deploy/vm-bare-metal/install-nim-manual.md) instead.

---

## Before you begin

Follow these steps to prepare for installing NGINX Instance Manager:

- **Download the installation script**:

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

- **Download the certificate and private key** (see [these steps](#download-cert-key)):
  Use the certificate and private key for NGINX Instance Manager (the same files used for NGINX Plus).
  - Ensure the files have `.crt` and `.key` extensions.
  - Save them to the target system. The default locations are:
    - `/etc/ssl/nginx/nginx-repo.crt`
    - `/etc/ssl/nginx/nginx-repo.key`

- **Check for previous deployments**:
  Ensure that NGINX Instance Manager and its components are not already installed.

  If NGINX Instance Manager or its components (such as ClickHouse or NGINX) are detected, either follow the [upgrade instructions](#upgrade-nim) to update them or [manually remove the components](#uninstall-nim) before proceeding with the installation.

- **(Optional) Install and configure Vault**:
  If you plan to use Vault, set it up before proceeding.

### Supported NGINX versions and Linux distributions

The installation script installs the latest version of [NGINX Open Source](https://nginx.org/news.html) or [NGINX Plus](https://docs.nginx.com/nginx/releases/).

To see the list of supported distributions, run:

```shell
install-nim-bundle.sh -l
```

### 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).
- Ensure that no other services are running on the same machine.

---

## Download certificate and key {#download-cert-key}

Download the SSL certificate and private key needed for NGINX Instance Manager to add the official repository during installation. These can also be used when [installing NGINX Plus](nginx/admin-guide/installing-nginx/installing-nginx-plus.md).

1. On the host where you're installing NGINX Instance Manager, create the **/etc/ssl/nginx/** and **/etc/nginx/** directories:

    ```shell
    sudo mkdir -p /etc/ssl/nginx /etc/nginx
    ```

2. Download the **SSL Certificate**, **Private Key** and ***JSON Web Token*** files from [MyF5](https://account.f5.com/myf5) or use the download link provided in your trial activation email.

3. Rename the cert and key to `nginx-repo.crt` and `nginx-repo.key`, move them to the `/etc/ssl/nginx/` directory. Rename the JWT file to `license.jwt` and move it to the `/etc/nginx/` directory:

    ```shell
    sudo mv nginx-<subscription-id>.crt /etc/ssl/nginx/nginx-repo.crt
    sudo mv nginx-<subscription-id>.key /etc/ssl/nginx/nginx-repo.key
    sudo mv <nginx-license-id>.jwt /etc/nginx/license.jwt
    ```

---

## Prepare the system and run the installation script {#download-install}

If you haven’t already downloaded the script, you can download it here:

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

### Prepare your system for installation

Follow these steps to get your system ready for a successful installation with the `install-nim-bundle.sh` script:

#### Resolve existing installations of NGINX Instance Manager

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

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

- **Uninstall first**
  Remove the current installation and its dependencies for a fresh start. Use the [uninstall steps](#uninstall-nim) to delete the primary components. Afterward, manually check for and remove leftover files such as repository configurations or custom settings to ensure a clean system.

#### Verify SSL certificates and private keys

Ensure that 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.

#### Verify If Metrics Are Required (Exclude ClickHouse)

In 2.20.0, we introduced Lightweight mode, which means you can skip the ClickHouse installation entirely. It’s ideal if you don’t need monitoring data or want a simpler setup. This reduces system requirements and avoids the work of managing a metrics database. You can add ClickHouse later if your needs change.

#### Use the manual installation steps if needed

If the script fails or if you prefer more control over the process, consider using the [manual installation steps](nim/deploy/vm-bare-metal/install-nim-manual.md). These steps provide a reliable alternative for troubleshooting or handling complex setups.

### Run the installation script

The `install-nim-bundle.sh` script automates installing NGINX Instance Manager.

By default, the script:

- Assumes no prior installation of NGINX Instance Manager or its dependencies
- Reads SSL files from the `/etc/ssl/nginx` directory
- Installs the latest version of NGINX Open Source (OSS)
- Installs the ClickHouse database
- Installs the latest version of NGINX Instance Manager
- Requires an active internet connection

#### Installation script options

You can customize the installation using the following options:

| Category | Option or Flag |
|----------|----------------|
| **Installation platform** | `-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` Install the latest version of NGINX Open Source. *(Default if `-n` or `-p` not specified)*<br><br>`-p` Install NGINX Plus as the API gateway. Must be used with `-j` to provide a JWT license.<br><br>`-j <path>` Path to the `license.jwt` file. Required when using `-p`. |
| **ClickHouse installation** | `-v <clickhouse-version>`: Install a specific version of ClickHouse. If not set, version `` is installed by default. |

**Example: install with default key and certificate paths**

To use the script to install NGINX Instance Manager on Ubuntu 24.04, with repository keys in the default `/etc/ssl/nginx` directory, with the latest version of NGINX Open Source, run the following command:

```bash
sudo bash install-nim-bundle.sh -d ubuntu24.04
```

<br>

**Example: install with custom repo key and certificate**

To install NGINX Instance Manager on Ubuntu 24.04 with the latest version of NGINX Plus by pointing to the location of your NGINX cert and key, run the following command:

```bash
sudo bash install-nim-bundle.sh \
  -c <path/to/nginx-repo.crt> \  # in case of non-default name or location
  -k <path/to/nginx-repo.key> \  # in case of non-default name or location
  -p \
  -d ubuntu24.04 \
  -j <path/to/license.jwt> # in case of non-default name or location
```

<br>

After installing NGINX Instance Manager and related packages, the script generates an admin password. This may take a few minutes to appear:

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

Save this password. You'll need it to log in to NGINX Instance Manager.

### Problems and additional script parameters

There are multiple parameters to configure in the installation script. If you see fatal errors when running the script, first run the following command, which includes command options that can help you bypass problems:

```bash
bash install-nim-bundle.sh -h
```

### Access the web interface {#access-web-interface}

After installation, you can access the NGINX Instance Manager web interface to begin managing your deployment.

1. Open a web browser.
2. Navigate to `https://<NIM_FQDN>`, replacing `<NIM_FQDN>` with the fully qualified domain name of your NGINX Instance Manager host.
3. Log in using the default administrator username (`admin`) and the autogenerated password displayed during installation.

Save the autogenerated password displayed at the end of the installation process. If you want to change the admin password, refer to the [Set user passwords](/nim/admin-guide/authentication/basic-auth/set-up-basic-authentication.md#set-basic-passwords) section in the Basic Authentication topic.

### Using the script to uninstall NGINX Instance Manager and its dependencies

In some cases, the script may need to be re-run due to parameters not being set correctly, or wrong versions being specified. You can remove NGINX Instance Manager and all of its dependencies (including NGINX) so that the script can be re-run.

**Note:** The `-r` option removes all NGINX configuration files, NGINX Instance Manager, and ClickHouse. Once you run this command, the data is gone and cannot be recovered unless you have backups. Use this option only if you need to remove NGINX Instance Manager to re-run the script in a fresh environment for a new installation. See "[Uninstall NGINX Instance Manager](#uninstall-nim)" below to perform these steps manually. If you do not want to lose your NGINX Configuration, you should take a backup of `/etc/nginx/`. 

```bash
bash install-nim-bundle.sh -r
```

---

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

## License NGINX Instance Manager

A valid license is required to make full use of all the features in NGINX Instance Manager.

Refer to the [Add a License](nim/licensing-and-reporting/add-license-connected-deployment.md) topic for instructions on how to download and apply a trial license, subscription license, or Flexible Consumption Program license.

---

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

#### CentOS, RHEL, RPM-Based

1. To upgrade to the latest version of the NGINX Instance Manager, run the following command:

   ```shell
   sudo yum update -y nms-instance-manager --allowerasing
   ```

1. To upgrade to the latest version of Clickhouse, run the following command:

   ```shell
   sudo yum update -y clickhouse-server clickhouse-client
   ```

#### Debian, Ubuntu, Deb-Based

1. To upgrade to the latest version of the NGINX Instance Manager, run the following commands:

   ```shell
   sudo apt-get update
   sudo apt-get install -y --only-upgrade nms-instance-manager
   ```

1. To upgrade to the latest version of ClickHouse, run the following commands:

   ```shell
   sudo apt-get update
   sudo apt-get install -y --only-upgrade clickhouse-server clickhouse-client
   ```

2. Restart the NGINX Instance Manager platform services:

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

   ```shell
   sudo systemctl restart nginx
   ```

4. Restart the Clickhouse server:

   ```shell
   sudo systemctl restart clickhouse-server
   ```

5. (Optional) If you use SELinux, follow the steps in the [Configure SELinux](nim/system-configuration/configure-selinux.md) guide to restore the default SELinux labels (`restorecon`) for the 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`.

---

## Next steps

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