NIM release 2.20.0

content/includes/installation/add-nms-repo.md

@@ -36,23 +36,39 @@ Add the NGINX Instance Manager repository:
 
 {{%tab name="Debian, Ubuntu, Deb-Based"%}}
 
-Add the NGINX Instance Manager repository:
-
-- **Debian**
+1. Add the NGINX signing key:
 
   ```shell
-  printf "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] https://pkgs.nginx.com/nms/debian `lsb_release -cs` nginx-plus\n" | sudo tee /etc/apt/sources.list.d/nms.list
-  sudo wget -q -O /etc/apt/apt.conf.d/90pkgs-nginx https://cs.nginx.com/static/files/90pkgs-nginx
+  wget -qO - https://cs.nginx.com/static/keys/nginx_signing.key \
+      | gpg --dearmor \
+      | sudo tee /usr/share/keyrings/nginx-archive-keyring.gpg >/dev/null 
   ```
 
-  <br>
+2. Add the NGINX Instance Manager repository:
 
-- **Ubuntu**
+   - **Debian**
 
-  ```shell
-  printf "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] https://pkgs.nginx.com/nms/ubuntu `lsb_release -cs` nginx-plus\n" | sudo tee /etc/apt/sources.list.d/nms.list
-  sudo wget -q -O /etc/apt/apt.conf.d/90pkgs-nginx https://cs.nginx.com/static/files/90pkgs-nginx
-  ```
+    ```shell
+    printf "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] \
+    https://pkgs.nginx.com/nms/debian $(lsb_release -cs) nginx-plus\n" | \
+    sudo tee /etc/apt/sources.list.d/nms.list
+
+    sudo wget -q -O /etc/apt/apt.conf.d/90pkgs-nginx \
+    https://cs.nginx.com/static/files/90pkgs-nginx
+    ```
+
+     <br>
+
+   - **Ubuntu**
+
+    ```shell
+    printf "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] \
+    https://pkgs.nginx.com/nms/ubuntu $(lsb_release -cs) nginx-plus\n" | \
+    sudo tee /etc/apt/sources.list.d/nms.list
+
+    sudo wget -q -O /etc/apt/apt.conf.d/90pkgs-nginx \
+    https://cs.nginx.com/static/files/90pkgs-nginx
+    ```
 
 {{%/tab%}}
 {{</tabs>}}

content/includes/nginx-plus/usage-tracking/overview.md

@@ -6,5 +6,5 @@ Start by installing NGINX Instance Manager on a dedicated host. Then, configure
 
 
 {{<call-out tip "Tip for Automated Reporting">}}
-To set up automatic reporting, [add your JWT-based license to NGINX Instance Manager]({{< ref "/nim/admin-guide/license/add-license.md#apply-jwt-license" >}}). This license can be downloaded from [MyF5](https://account.f5.com/myf5) if needed.
+To set up automatic reporting, [add your JWT-based license to NGINX Instance Manager]({{< ref "/nim/admin-guide/add-license.md#apply-jwt-license" >}}). This license can be downloaded from [MyF5](https://account.f5.com/myf5) if needed.
 {{</call-out>}}

content/includes/nim/admin-guide/license/connected-install-license-note.md

@@ -4,4 +4,4 @@ docs:
 
 A valid license is required to make full use of all the features in NGINX Instance Manager.
 
-Refer to the [Add a License]({{< ref "nim/admin-guide/license/add-license.md" >}}) topic for instructions on how to download and apply a trial license, subscription license, or Flexible Consumption Program license.
+Refer to the [Add a License]({{< ref "nim/admin-guide/add-license.md" >}}) topic for instructions on how to download and apply a trial license, subscription license, or Flexible Consumption Program license.

content/includes/nim/clickhouse/cli-skip-clickhouse.md

@@ -0,0 +1,10 @@
+---
+docs:
+files:
+- content/nim/deploy/vm-bare-metal/install.md
+- content/nim/disconnected/offline-install-guide.md
+---
+
+If you skip installing ClickHouse, you need NGINX Agent {{< lightweight-nim-nginx-agent-version >}}.
+
+After installation, make sure to [disable metrics collection]({{< ref "nim/system-configuration/configure-clickhouse.md#disable-metrics-collection" >}}) in the `/etc/nms/nms.conf` file.

content/includes/nim/clickhouse/clickhouse-defaults.md

@@ -0,0 +1,23 @@
+---
+docs: DOCS-1238
+files:
+- content/nim/system-configuration/configure-clickhouse.md
+- content/nim/deploy/vm-bare-metal/install-nim-manual.md
+---
+
+{{<bootstrap-table "table table-striped table-bordered">}}
+
+| Configuration                 | Default                            | Notes |
+|------------------------------|------------------------------------|-------|
+| clickhouse.enable            | true                               | Set to `false` to disable metrics collection and run NGINX Instance Manager in lightweight mode. Requires a service restart. |
+| clickhouse.address           | tcp://localhost:9000               | The address of the ClickHouse database. |
+| clickhouse.username          |                                    | The username NGINX Instance Manager uses to connect to ClickHouse, if authentication is enabled. |
+| clickhouse.password          |                                    | The password for the specified ClickHouse user. |
+| clickhouse.tls_mode          | false                              | Set to `true` to enable TLS for the ClickHouse connection. This setting will be deprecated in a future release. Use the `clickhouse.tls` section instead. |
+| clickhouse.tls.address       | tcp://localhost:9440               | The address NGINX Instance Manager uses to connect to ClickHouse over TLS. Format: `<ip-address>:<port>`. |
+| clickhouse.tls.skip_verify   | false                              | Set to `true` to skip TLS certificate verification. Use only for self-signed certificates in non-production environments. |
+| clickhouse.tls.key_path      |                                    | Path to the client TLS key file in PEM format. Required for client authentication. |
+| clickhouse.tls.cert_path     |                                    | Path to the client TLS certificate file in PEM format. Required for client authentication. |
+| clickhouse.tls.ca_path       | /etc/ssl/certs/ca-certificates.crt | Path to the system Certificate Authority used to verify the server certificate. The default path works for Ubuntu and Debian. Use a CA bundle appropriate to your system. See [TLS configuration](#tls) for details. |
+
+{{</bootstrap-table>}}

content/includes/nim/clickhouse/clickhouse-install.md

@@ -0,0 +1,70 @@
+---
+docs:
+files:
+- content/nim/deploy/vm-bare-metal/install-nim-manual.md
+---
+
+NGINX Instance Manager uses [ClickHouse](https://clickhouse.com) to store metrics, events, alerts, and configuration settings.
+
+If you install ClickHouse and choose to 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. If the password is missing or incorrect, NGINX Instance Manager **will not start**.
+
+For instructions and additional configuration options, including TLS settings, see [Configure ClickHouse]({{< ref "nim/system-configuration/configure-clickhouse.md" >}}).
+
+NGINX Instance Manager requires ClickHouse version {{< clickhouse-version >}} or later.
+
+
+Follow these steps to install and enable ClickHouse on supported Linux distributions.
+
+1. First, set up the repository.
+
+   - For RPM-based systems (CentOS, RHEL):
+
+      ```shell
+      sudo yum install -y yum-utils
+      sudo yum-config-manager --add-repo https://packages.clickhouse.com/rpm/clickhouse.repo
+      ```
+
+   - For Debian-based systems (Debian, Ubuntu):
+
+      ```shell
+      sudo apt-get install -y apt-transport-https ca-certificates dirmngr
+      GNUPGHOME=$(mktemp -d)
+      sudo GNUPGHOME="$GNUPGHOME" gpg --no-default-keyring --keyring /usr/share/keyrings/clickhouse-keyring.gpg --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys 8919F6BD2B48D754
+      sudo rm -r "$GNUPGHOME"
+      sudo chmod +r /usr/share/keyrings/clickhouse-keyring.gpg
+
+      echo "deb [signed-by=/usr/share/keyrings/clickhouse-keyring.gpg] https://packages.clickhouse.com/deb lts main" | sudo tee /etc/apt/sources.list.d/clickhouse.list
+      sudo apt-get update
+      ```
+
+2. Next, install the ClickHouse server and client:
+
+   - For RPM-based systems (CentOS, RHEL):
+
+      ```shell
+      sudo yum install -y clickhouse-server clickhouse-client
+      ```
+
+   - For Debian-based systems (Debian, Ubuntu):
+
+      ```shell
+      sudo apt-get install -y clickhouse-server clickhouse-client
+      ```
+
+3. Then, enable the ClickHouse service so it starts automatically on reboot:
+
+   ```shell
+   sudo systemctl enable clickhouse-server
+   ```
+
+4. Start the ClickHouse service:
+
+   ```shell
+   sudo systemctl start clickhouse-server
+   ```
+
+5. Finally, confirm the service is running:
+
+   ```shell
+   sudo systemctl status clickhouse-server
+   ```

content/includes/nim/docker/docker-compose-env-vars.md

@@ -4,14 +4,15 @@ docs:
 
 {{<bootstrap-table "table table-striped table-bordered">}}
 | Variable | Category | Description |
-|----------|----------|------------|
+|----------|----------|-------------|
+| **ENABLE_METRICS** | General | Enables or disables metrics collection and storage. Set to `false` to run in lightweight mode without ClickHouse. Defaults to `true`. |
+| **NIM_MAINTENANCE** | General | Enables maintenance mode for backup, restore, and troubleshooting (`true` or `false`). |
+| **NIM_LICENSE_MODE_OF_OPERATION** | General | Sets the license mode to either `connected` (default) or `disconnected`. |
 | **NIM_LOG_LEVEL** | General | Sets the logging level for NGINX Instance Manager. |
 | **NIM_METRICS_TTL** | General | Specifies the number of days to retain metrics. |
 | **NIM_EVENTS_TTL** | General | Specifies the number of days to retain event logs. |
 | **NIM_SECURITY_TTL** | General | Specifies the number of days to retain security violation logs. |
-| **NIM_MAINTENANCE** | General | Enables maintenance mode for backup, restore, and troubleshooting (`true` or `false`). |
 | **NIM_WATCHDOG_TIMEOUT** | General | Sets the timeout (in seconds) for the Data Plane Monitoring (DPM) watchdog. |
-| **NIM_LICENSE_MODE_OF_OPERATION** | General | Sets the license mode to either `connected` (default) or `disconnected`. |
 | **PROXY_ENABLE** | Forward Proxy | Enables or disables the use of a forward proxy (`true` or `false`). |
 | **PROXY_HOST** | Forward Proxy | The IP address or hostname of the proxy server. |
 | **PROXY_PORT** | Forward Proxy | The port number of the proxy server. |
@@ -20,7 +21,6 @@ docs:
 | **PROXY_USERNAME** | Forward Proxy | (Required if `PROXY_AUTH_REQUIRED=true`) The username for proxy authentication. |
 | **PROXY_PASSWORD** | Forward Proxy | (Required if `PROXY_AUTH_REQUIRED=true`) The password for proxy authentication. |
 | **PROXY_SSL_VERIFY** | Forward Proxy | Enables or disables SSL verification when `PROXY_PROTOCOL=https`. Default is `true`, meaning the proxy must have a valid certificate issued by a trusted Certificate Authority (CA). Set to `false` to allow self-signed or untrusted certificates (not recommended). |
-
 {{</bootstrap-table>}}
 
 

content/includes/nim/installation/install-script-flags/cert.md

@@ -0,0 +1,8 @@
+---
+docs:
+files:
+- content/nim/deploy/vm-bare-metal/install.md
+- content/nim/disconnected/offline-install-guide.md
+---
+
+`-c <path/to/nginx-repo.crt>`: Path to the SSL certificate file. (default: `/etc/ssl/nginx`)

content/includes/nim/installation/install-script-flags/clickhouse-version.md

@@ -0,0 +1,8 @@
+---
+docs:
+files:
+- content/nim/deploy/vm-bare-metal/install.md
+- content/nim/disconnected/offline-install-guide.md
+---
+
+`-v <clickhouse-version>`: Install a specific version of ClickHouse. If not set, version `{{< clickhouse-version >}}` is installed by default.

content/includes/nim/installation/install-script-flags/distribution.md

@@ -0,0 +1,14 @@
+---
+docs:
+files:
+- content/nim/deploy/vm-bare-metal/install.md
+- content/nim/disconnected/offline-install-guide.md
+---
+
+`-d <distribution>`: Target Linux distribution (for example, `ubuntu22.04`, `rhel8`)
+
+To see the list of supported distributions, run:
+
+```shell
+grep '\-d distribution' install-nim-bundle.sh
+```

content/includes/nim/installation/install-script-flags/key.md

@@ -0,0 +1,8 @@
+---
+docs:
+files:
+- content/nim/deploy/vm-bare-metal/install.md
+- content/nim/disconnected/offline-install-guide.md
+---
+
+`-k <path/to/nginx-repo.key>`: Path to the private key file. (default: `/etc/ssl/nginx`)

content/includes/nim/installation/install-script-flags/skip-clickhouse.md

@@ -0,0 +1,10 @@
+---
+docs:
+files:
+- content/nim/deploy/vm-bare-metal/install.md
+- content/nim/disconnected/offline-install-guide.md
+---
+
+`-s`: Skip installing ClickHouse. This lightweight mode reduces system requirements and simplifies installation for users who do not need metrics.
+
+{{< include "nim/clickhouse/cli-skip-clickhouse.md" >}}

content/includes/nim/installation/optional-steps/configure-clickhouse.md

@@ -0,0 +1,23 @@
+---
+docs:
+files:
+- content/nim/deploy/vm-bare-metal/install.md
+- content/nim/deploy/vm-bare-metal/install-nim-manual.md
+- content/nim/disconnected/offline-install-guide.md
+- content/nim/disconnected/offline-install-guide-manual.md
+---
+
+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]({{< ref "nim/system-configuration/configure-clickhouse.md" >}}).

content/includes/nim/installation/optional-steps/configure-selinux.md

@@ -0,0 +1,12 @@
+---
+docs:
+files:
+- content/nim/deploy/vm-bare-metal/install-nim-manual.md
+- content/nim/deploy/vm-bare-metal/install.md
+- content/nim/disconnected/offline-install-guide-manual.md
+- content/nim/disconnected/offline-install-guide.md
+---
+
+SELinux helps secure your deployment by enforcing mandatory access control policies.
+
+If you use SELinux, follow the steps in the [Configure SELinux]({{< ref "/nim/system-configuration/configure-selinux.md" >}}) guide to restore SELinux contexts (`restorecon`) for the files and directories related to NGINX Instance Manager.

content/includes/nim/installation/optional-steps/disable-metrics-collection.md

@@ -0,0 +1,11 @@
+---
+docs:
+files:
+- content/nim/deploy/vm-bare-metal/install.md
+- content/nim/disconnected/offline-install-guide-manual.md
+- content/nim/disconnected/offline-install-guide.md
+---
+
+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` file. This setup requires NGINX Agent version {{< lightweight-nim-nginx-agent-version >}}.
+
+For instructions, see [Disable metrics collection]({{< ref "nim/system-configuration/configure-clickhouse.md#disable-metrics-collection" >}}).

content/includes/nim/installation/optional-steps/install-configure-vault.md

@@ -0,0 +1,16 @@
+---
+docs:
+files:
+- content/nim/deploy/vm-bare-metal/install-nim-manual.md
+- content/nim/deploy/vm-bare-metal/install.md
+- content/nim/disconnected/offline-install-guide-manual.md
+- content/nim/disconnected/offline-install-guide.md
+---
+
+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://www.vaultproject.io/docs/install) for your distribution.
+- 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]({{< ref "/nim/system-configuration/configure-vault.md" >}}).

content/includes/nim/kubernetes/nms-chart-supported-module-versions.md

@@ -6,6 +6,7 @@ docs: DOCS-1324
 
 | NGINX Instance Manager chart | Instance Manager |
 |------------------------------|------------------|
+| 2.0.0                        | 2.20.0           |
 | 1.15.0                       | 2.18.0           |
 | 1.14.4                       | 2.17.4           |
 | 1.14.0                       | 2.17.0           |

content/includes/nim/tech-specs/supported-distros.md

@@ -1,5 +1,7 @@
 ---
 docs: DOCS-1071
+files:
+- content/nim/fundamentals/tech-specs.md
 ---
 
 The following table lists the Linux distributions supported by NGINX Instance Manager and NGINX App Protect:

content/includes/nim/tech-specs/supported-nginx-versions.md

@@ -1,5 +1,7 @@
 ---
 docs: DOCS-1075
+files:
+- content/nim/fundamentals/tech-specs.md
 ---
 
 NGINX Instance Manager supports the following NGINX Open Source and NGINX Plus versions:
@@ -8,7 +10,7 @@ NGINX Instance Manager supports the following NGINX Open Source and NGINX Plus v
 
 | NGINX Instance Manager | NGINX OSS   | NGINX Plus |
 | ---------------------- | ----------- | ---------- |
-| 2.18.0 and later       | 1.18–1.25.1 | R31–R33    |
+| 2.18.0 and later       | 1.18–1.28.0 | R31–R34    |
 | 2.16.0–2.17.x          | 1.18–1.25.1 | R31–R32    |
 | 2.7.0–2.15.x           | 1.18–1.25.1 | R21–R30    |
 | 2.0.0–2.6.0            | 1.18–1.21.6 | R21–R27    |

content/nim/admin-guide/_index.md

@@ -1,5 +1,5 @@
 ---
-title: Platform administration
+title: Administer your platform
 weight: 40
 url: /nginx-instance-manager/admin-guide/
 ---