Merge remote-tracking branch 'internal/internal/nim-release-2.20.0' into nim-release-2.20.0

Author: travisamartin

cleanup_log.txt

@@ -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/installation/add-nms-repo.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/installation/clickhouse-defaults.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/nginx-plus/usage-tracking/overview.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/admin-guide/license/connected-install-license-note.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/cli-skip-clickhouse.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/clickhouse/clickhouse-defaults.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/clickhouse/clickhouse-install.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`)