diff --git a/content/includes/nim/docker/docker-compose-env-vars.md b/content/includes/nim/docker/docker-compose-env-vars.md new file mode 100644 index 000000000..c34e6e767 --- /dev/null +++ b/content/includes/nim/docker/docker-compose-env-vars.md @@ -0,0 +1,26 @@ +--- +docs: +--- + +{{}} +| Variable | Category | Description | +|----------|----------|------------| +| **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. | +| **PROXY_PROTOCOL** | Forward Proxy | The proxy protocol (`http` or `https`). | +| **PROXY_AUTH_REQUIRED** | Forward Proxy | Specifies whether authentication is required for the proxy (`true` or `false`). | +| **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). | + +{{}} + + diff --git a/content/includes/nim/system-configuration/trust-proxy-ca-certificates.md b/content/includes/nim/system-configuration/trust-proxy-ca-certificates.md new file mode 100644 index 000000000..7211c5246 --- /dev/null +++ b/content/includes/nim/system-configuration/trust-proxy-ca-certificates.md @@ -0,0 +1,18 @@ +--- +docs: +--- + +1. Copy the proxy CA certificate into the system’s trusted certificate directory, for example **/usr/local/share/ca-certificates/** or **/etc/ssl/certs/** (path varies by distribution). +1. Run the appropriate command to update the system’s trusted certificates: + + - **Debian/Ubuntu**: + + ```bash + sudo update-ca-certificates + ``` + + - **RHEL/CentOS**: + + ```shell + sudo update-ca-trust + ``` diff --git a/content/nap-waf/v4/admin-guide/install-nms.md b/content/nap-waf/v4/admin-guide/install-nms.md index a91b0a06a..9020cba28 100644 --- a/content/nap-waf/v4/admin-guide/install-nms.md +++ b/content/nap-waf/v4/admin-guide/install-nms.md @@ -21,7 +21,7 @@ weight: 100 [NGINX Management Suite Security Monitoring]({{< relref "/nms/about.md#security-monitoring" >}}) provides a centralized visualization tool that lets you analyze threats, view protection insights, and identify areas for policy tuning. -- For more information on how to configure Security Monitoring, see [Set Up App Protect Instances for Security Monitoring]({{< relref "/nim/monitoring/security-monitoring/configure/set-up-app-protect-instances.md" >}}). +- For more information on how to configure Security Monitoring, see [Set Up App Protect Instances for Security Monitoring]({{< relref "/nim/nginx-app-protect/security-monitoring/set-up-app-protect-instances.md" >}}). --- diff --git a/content/nim/admin-guide/authentication/oidc/getting-started.md b/content/nim/admin-guide/authentication/oidc/getting-started.md index e5ebb1fd8..dff2ec06e 100644 --- a/content/nim/admin-guide/authentication/oidc/getting-started.md +++ b/content/nim/admin-guide/authentication/oidc/getting-started.md @@ -18,6 +18,8 @@ NGINX Instance Manager’s implementation of OIDC is designed to work with any I {{}}To learn how to configure OIDC with a specific identity provider, refer to the linked topics in the [Set up specific IdPs for OIDC](#oidc-specific-idps) section at the bottom of this page.{{}} +{{}}OpenID Connect (OIDC) authentication is not supported when NGINX Instance Manager is running in [forward-proxy mode]({{< relref "nim/system-configuration/configure-forward-proxy.md" >}}). OIDC is configured on the NGINX Plus layer and cannot pass authentication requests through a forward proxy.{{}} + ## Create roles and user groups in NGINX Instance Manager {#configure-nim} When using OIDC for authentication, administrators don't need to create and manage users in NGINX Instance Manager. Instead, they create user groups in NGINX Instance Manager that match groups in their IdP. The roles assigned to the user group set the access level and permissions for users based on their group membership. Users who aren't in a group with an assigned role won't have access to NGINX Instance Manager. diff --git a/content/nim/deploy/docker/deploy-nginx-instance-manager-docker-compose.md b/content/nim/deploy/docker/deploy-nginx-instance-manager-docker-compose.md index 1ca98e9ab..0c22a8307 100644 --- a/content/nim/deploy/docker/deploy-nginx-instance-manager-docker-compose.md +++ b/content/nim/deploy/docker/deploy-nginx-instance-manager-docker-compose.md @@ -52,12 +52,23 @@ To set up Docker to communicate with the NGINX container registry located at `pr ### Compose deployment -Navigate to the directory where you downloaded `docker-compose.yaml`. With the following commands, use docker to log in to private-registry.nginx.com and then run `docker compose up -d`. +{{}} + +If you are configuring a **forward proxy**, follow the steps in the [Forward Proxy Configuration Guide]({{< relref "nim/system-configuration/configure-forward-proxy.md" >}}) to modify `docker-compose.yaml` with the correct proxy settings **before** deploying NGINX Instance Manager. + +{{}} + +Go to the directory where you downloaded `docker-compose.yaml`. Use the following commands to log in to `private-registry.nginx.com` and deploy NGINX Instance Manager. ```shell -~$ docker login private-registry.nginx.com --username= --password=none -~$ echo "admin" > admin_password.txt -~$ docker compose up -d +docker login private-registry.nginx.com --username= --password=none +echo "admin" > admin_password.txt +docker compose up -d +``` + +If the deployment succeeds, you’ll see output similar to this: + +```text [+] Running 6/6 ✔ Network nim_clickhouse Created 0.1s ✔ Network nim_external_network Created 0.2s @@ -65,19 +76,17 @@ Navigate to the directory where you downloaded `docker-compose.yaml`. With the f ✔ Container nim-precheck-1 Started 0.8s ✔ Container nim-clickhouse-1 Healthy 6.7s ✔ Container nim-nim-1 Started 7.4s -``` + ``` ### Supported environment variables -You may modify the following variables in the `docker-compose.yaml` file: +{{< include "nim/docker/docker-compose-env-vars.md" >}} + +
-- `NIM_LOG_LEVEL` - set the NGINX Instance Manager logging level. -- `NIM_METRICS_TTL` - set a custom time-to-live in days value for metrics retention. -- `NIM_EVENTS_TTL` - set a custom time-to-live in days value for events retention. -- `NIM_SECURITY_TTL` - set a custom time-to-live in days value for security violation retention. -- `NIM_MAINTENANCE` - enable maintenance mode to preform backup, restore and troubleshooting. -- `NIM_WATCHDOG_TIMEOUT` - set a custom dpm watchdog timeout in seconds. -- `NIM_LICENSE_MODE_OF_OPERATION` - set the NGINX Instance Manager license mode of operation to either connected or disconnected. Default is connected. +{{}} +For details on configuring a forward proxy, see the [Forward Proxy Configuration Guide]({{< relref "nim/system-configuration/configure-forward-proxy.md" >}}). +{{}} ### Compose stop or tear down diff --git a/content/nim/deploy/kubernetes/deploy-using-helm.md b/content/nim/deploy/kubernetes/deploy-using-helm.md index 4cdf531c5..0bc12fdcd 100644 --- a/content/nim/deploy/kubernetes/deploy-using-helm.md +++ b/content/nim/deploy/kubernetes/deploy-using-helm.md @@ -13,7 +13,7 @@ tags: {{< include "/nim/decoupling/note-legacy-nms-references.md" >}} -This guide provides a step-by-step tutorial on how to set up F5 NGINX Instance Manager on a Kubernetes cluster using Helm. You'll learn how to download and use Docker images and customize your deployment. +This guide explains how to deploy F5 NGINX Instance Manager on a Kubernetes or OpenShift cluster using Helm. You’ll learn how to download and use Docker images and customize your deployment. ### About Helm @@ -21,8 +21,6 @@ Helm charts are pre-configured packages of Kubernetes resources deployed with a Helm charts consist of files that describe a group of related Kubernetes resources, like deployments, services, and ingress. They also allow you to manage dependencies between applications, making it easier to deploy multi-tier or complex applications. -{{< call-out "important" "Supportability considerations" >}} NGINX Instance Manager **does not** support [OpenShift](https://www.redhat.com/en/technologies/cloud-computing/openshift). For better compatibility, use [NGINX Ingress Controller](https://docs.nginx.com/nginx-ingress-controller/). {{< /call-out >}} - --- ## Before you begin @@ -41,8 +39,6 @@ To deploy NGINX Instance Manager using a Helm chart, you need: {{< /bootstrap-table >}} - - --- ## Get the NGINX Instance Manager images @@ -57,12 +53,23 @@ Create a Docker registry secret on the cluster, using the JWT token as the usern {{< note >}} Make sure there are no extra characters or spaces when copying the JWT token. They can invalidate the token and cause 401 errors during authentication. {{< /note >}} -```shell -kubectl create secret docker-registry regcred \ ---docker-server=private-registry.nginx.com \ ---docker-username= \ ---docker-password=none -``` +- **Kubernetes**: + + ```shell + kubectl create secret docker-registry regcred \ + --docker-server=private-registry.nginx.com \ + --docker-username= \ + --docker-password=none + ``` + +- **OpenShift**: + + ```shell + oc create secret docker-registry regcred \ + --docker-server=private-registry.nginx.com \ + --docker-username= \ + --docker-password=none + ``` {{< warning >}} @@ -74,9 +81,18 @@ This can be ignored (since no password is used), but if others have access to th To confirm the secret is created: -```shell -kubectl get secret regcred --output=yaml -``` +- **Kubernetes**: + + ```shell + kubectl get secret regcred --output=yaml + ``` + +- **OpenShift**: + + ```shell + oc get secret regcred --output=yaml + ``` + You can now use this secret for Helm deployments and point the charts to the public registry. @@ -99,14 +115,16 @@ The first command adds the `nginx-stable` repository to your local Helm repo lis ## Create a Helm deployment values.yaml file -The `values.yaml` file customizes the Helm chart installation without editing the chart itself. You can specify image repositories, environment variables, resource requests, and more. +The `values.yaml` file customizes the Helm chart installation without modifying the chart itself. You can use it to specify image repositories, environment variables, resource requests, and other settings. 1. Create a `values.yaml` file similar to this example: - In the `imagePullSecrets` section, add the credentials for your private Docker registry. - Change the version tag to the version of NGINX Instance Manager you would like to install. See "Install the chart" below for versions. + - Replace `` with your private Docker registry and port (if applicable). + - If deploying on OpenShift, add the `openshift.enabled: true` setting. - {{< see-also >}} For more on creating a secret, see Kubernetes [Pull an Image from a Private Registry](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/). {{}} + {{< see-also >}} For details on creating a secret, see Kubernetes [Pull an Image from a Private Registry](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/). {{}} ```yaml nms-hybrid: @@ -138,13 +156,74 @@ The `values.yaml` file customizes the Helm chart installation without editing th tag: ``` - This file specifies the Docker images for `apigw`, `core`, `dpm`, `ingestion`, `integrations`, and `utility`. It also indicates that a secret called `regcred` should be used for pulling images. +2. Save and close the `values.yaml` file. + +--- + +## Enabling OpenShift + +If deploying on OpenShift, include this setting in the `values.yaml` file: + +```yaml +nms-hybrid: + openshift: + enabled: true +``` + +### How OpenShift handles security constraints + +When `openshift.enabled: true` is set in the `values.yaml` file, the NGINX Instance Manager deployment automatically creates a **custom Security Context Constraint (SCC)** and links it to the Service Account used by all pods. + +By default, OpenShift enforces strict security policies that require containers to run as **non-root** users. The NGINX Instance Manager deployment needs specific user IDs (UIDs) for certain services, such as **1000** for `nms` and **101** for `nginx` and `clickhouse`. Since the default SCCs do not allow these UIDs, a **custom SCC** is created. This ensures that the deployment can run with the necessary permissions while maintaining OpenShift’s security standards. + +The custom SCC allows these UIDs by setting the `runAsUser` field, which controls which users can run containers. To verify that the SCC has been created, run: + +```shell +oc get scc nms-restricted-v2-scc --output=yaml +``` -1. Save and close the `values.yaml` file. --- +To apply network policies for NGINX Instance Manager, ensure Kubernetes has a [network plugin](https://kubernetes.io/docs/concepts/extend-kubernetes/compute-storage-net/network-plugins/) installed before the Helm chart installation. + +By default, the following network policies will be created in the release namespace: + +- **Kubernetes**: + + ```shell + kubectl get netpol -n nms + ``` + +- **OpenShift**: + + ```shell + oc get netpol -n nms + ``` + + **Output** + + ```text + NAME POD-SELECTOR AGE + apigw app.kubernetes.io/name=apigw 4m47s + clickhouse app.kubernetes.io/name=clickhouse 4m47s + core app.kubernetes.io/name=core 4m47s + dpm app.kubernetes.io/name=dpm 4m47s + ingestion app.kubernetes.io/name=ingestion 4m47s + integrations app.kubernetes.io/name=integrations 4m47s + utility app.kubernetes.io/name=integrations 4m47s + ``` + +To disable network policies, update the `values.yaml` file: + +```yaml +networkPolicies: + # Set this to true to enable network policies for NGINX Instance Manager. + enabled: false +``` + +--- ## Install the chart diff --git a/content/nim/monitoring/security-monitoring/configure/_index.md b/content/nim/monitoring/security-monitoring/configure/_index.md deleted file mode 100644 index f2c40cdbe..000000000 --- a/content/nim/monitoring/security-monitoring/configure/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: Configure -description: -weight: 200 ---- \ No newline at end of file diff --git a/content/nim/monitoring/security-monitoring/configure/create-role-security-monitoring.md b/content/nim/monitoring/security-monitoring/configure/create-role-security-monitoring.md deleted file mode 100644 index a3e26dc77..000000000 --- a/content/nim/monitoring/security-monitoring/configure/create-role-security-monitoring.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -title: Add user access to Security Monitoring dashboards -description: Learn how to grant users access to the F5 NGINX Security Monitoring dashboards. -toc: true -weight: 200 -doctype: how-to -product: NIM -docs: DOCS-1026 - ---- - -## Overview - -You can use F5 NGINX Security Monitoring to monitor NGINX App Protect WAF instances. The Security Monitoring analytics dashboards and security logs provide protection insights and help you analyze possible threats or identify opportunities to tune your security policies. - -By completing the steps in this topic, you will create a role that gives users access to the Security Monitoring module and logs, and assign it to user accounts or groups. - -{{< note >}} The recommendations in this guide follow the principle of least privilege and do not grant users access to NGINX Instance Manager. You can create additional roles with custom modules, features, and permissions to suit your use case. {{}} - ---- - -## Before you begin - -Complete the following prerequisites before proceeding with this guide: - -- NGINX Security Monitoring is [installed]({{< relref "/nim/monitoring/security-monitoring/install-security-monitoring.md" >}}) and running. -- Your user account needs to be able to access the User Management settings in NGINX Instance Manager. - The minimum required role permissions are: - - - **Module**: Settings - - **Feature**: User Management - - **Access**: `READ`, `CREATE`, `UPDATE` - -- Review the table below to determine the minimum permissions needed for your use case. - - {{}} - - | Module(s) | Feature(s) | Access | Description | - |-------|--------|----|--------| - | Instance Manager
Security Monitoring | Analytics
Security Monitoring | READ
READ | Read-only access that allows users to view the Security Monitoring dashboards. Users cannot access NGINX Instance Manager or Settings.| - | Instance Manager
Security Monitoring
Settings | Analytics
Security Monitoring
User Management | READ
READ
CREATE, READ, UPDATE| Allows users to view the Security Monitoring dashboards and manage user accounts and roles.

{{< fa "lightbulb" >}} Recommended for a "super-user" who is responsible for managing other users' access to the security dashboards. This permission set does not allow the user to delete user accounts.| - - - {{}} - ---- - -## Create a role - -{{< include "nim/rbac/create-roles.md" >}} - ---- - -## Assign the role - -After you've created a role for Security Monitoring, assign the role to one or more users or to a user group. - ---- - -### Assign the role to users - -{{< include "nim/rbac/assign-roles-to-users.md" >}} - ---- - -### Assign the role to user groups - -{{< include "nim/rbac/assign-roles-to-user-groups.md" >}} diff --git a/content/nim/monitoring/security-monitoring/configure/set-up-app-protect-instances.md b/content/nim/monitoring/security-monitoring/configure/set-up-app-protect-instances.md deleted file mode 100644 index 4b252c247..000000000 --- a/content/nim/monitoring/security-monitoring/configure/set-up-app-protect-instances.md +++ /dev/null @@ -1,247 +0,0 @@ ---- -title: Create App Protect WAF instances for Security Monitoring -description: Learn how to set up F5 NGINX App Protect data plane instances for use with - the NGINX Security Monitoring and NGINX Instance Manager. -toc: true -weight: 100 -type: how-to -product: NIM -docs: DOCS-1107 ---- - -## Overview - -F5 NGINX Security Monitoring supports the following use cases: - -- **Security Monitoring only**: Use only the Security Monitoring module to monitor data from NGINX App Protect WAF instances. You will be able to review the security dashboards to assess potential threats and identify opportunities to fine-tune your policies. Your NGINX App Protect WAF configurations are managed outside of the NGINX Instance Manager context. -- **Security Monitoring and Instance Manager**: Use the Security Monitoring module with the NGINX Instance Manager. In addition to monitoring your application security, you will be able to manage your NGINX App Protect WAF configurations and security policies in a single location and push pre-compiled updates to an instance or instance group. - ---- - -## Before you begin - -Complete the following prerequisites before proceeding with the steps in this guide. - -1. If you are new to NGINX App Protect WAF, follow the instructions in the installation and configuration guides to get up and running: - - - [Install NGINX App Protect WAF](https://docs.nginx.com/nginx-app-protect/admin-guide/install/) on one or more data plane instances. Each data plane instance must have connectivity to the NGINX Instance Manager host. - - [Configure NGINX App Protect WAF](https://docs.nginx.com/nginx-app-protect/configuration-guide/configuration/#policy-configuration-overview) according to your needs on each of the data plane instance. - -1. Review the dependencies with NGINX App Protect WAF and NGINX Plus. - - {{< include "nim/tech-specs/security-data-plane-dependencies.md" >}} - -1. Determine your use case: **Security Monitoring only** or **Security Monitoring and Configuration Management**. -1. [Install the NGINX Security Monitoring module]({{< relref "/nim/monitoring/security-monitoring/install-security-monitoring.md" >}}) and [upload your license]({{< relref "/nim/admin-guide/license/add-license.md" >}}). - ---- - -## Install NGINX Agent - -NGINX Agent is a companion daemon for NGINX Open Source or NGINX Plus instance that provides: - -- Remote management of NGINX configurations -- Collection and reporting of real-time NGINX performance and operating system metrics -- Notifications of NGINX events - -Repeat the steps in this section on each NGINX App Protect WAF data plane host to install and configure NGINX Agent for use with Security Monitoring. **These settings apply to both of the Security Monitoring use cases.** - -1. Use SSH to connect to the data plane host. -1. Install the NGINX Agent package from the NGINX Instance Manager host. - - {{< include "agent/installation/install-agent-api.md" >}} - -1. Edit the `/etc/nginx-agent/nginx-agent.conf` file to add the `nap_monitoring` configuration. - - Add the lines below to the end of the file. This enables NGINX Agent to send NGINX App Protect messages to the NGINX Instance Manager management plane. - - ```yaml - dataplane: - status: - # poll interval for data plane status - the frequency the NGINX Agent will query the data plane for changes - poll_interval: 30s - # report interval for data plane status - the maximum duration to wait before syncing data plane information if no updates have been observed - report_interval: 24h - events: - # report data plane events back to the management plane - enable: true - metrics: - # specify the size of a buffer to build before sending metrics - bulk_size: 20 - # specify metrics poll interval - report_interval: 1m - collection_interval: 15s - mode: aggregated - - # OSS NGINX default config path - # path to aux file dirs can also be added - config_dirs: "/etc/nginx:/usr/local/etc/nginx:/usr/share/nginx/modules:/etc/nms:/etc/app_protect" - - # Enable reporting NGINX App Protect details to the management plane. - extensions: - - nginx-app-protect - - nap-monitoring - - # Enable reporting NGINX App Protect details to the control plane. - nginx_app_protect: - # Report interval for NGINX App Protect details - the frequency the NGINX Agent checks NGINX App Protect for changes. - report_interval: 15s - # Enable precompiled publication from the NGINX Instance Manager (true) or perform compilation on the data plane host (false). - precompiled_publication: true - - # NGINX App Protect Monitoring config - nap_monitoring: - # Buffer size for collector. Will contain log lines and parsed log lines - collector_buffer_size: 50000 - # Buffer size for processor. Will contain log lines and parsed log lines - processor_buffer_size: 50000 - # Syslog server IP address the collector will be listening to - syslog_ip: "127.0.0.1" - # Syslog server port the collector will be listening to - syslog_port: 514 - ``` - -1. If the `location /api` directive has not been set up in the `nginx.conf` file, follow the example below to add it: - - ```nginx - server{ - location /api { - api write=on; - allow 127.0.0.1; - deny all; - } - } - ``` - - After adding the directive, restart NGINX to apply the changes: - - ```bash - sudo systemctl restart nginx - ``` - - {{}}You can change the values of `syslog_ip` and `syslog_port` to meet your needs. - You must use the same values when configuring logging for the Security Monitoring module. If the `syslog:` configuration does not match these settings, the monitoring dashboards will not display any data. Also, the networking changes for NGINX App Protect Version 5 preclude the use of `127.0.0.1` as a syslog server address. For Version 5, the address of the `docker0` interface (typically `192.0.10.1`) or the IP address of the data plane host can be used for the syslog server address.{{}} - - {{}}You can use the NGINX Agent installation script to add the fields for `nginx_app_protect` and `nap_monitoring`: - -```bash -# Download install script via API -curl https:///install/nginx-agent > install.sh - -# Use the flag --nap-monitoring to set the child fields for the field 'nap_monitoring', the -# child field values will be set to the values in the example configuration from above. Specify -# the -m | --nginx-app-protect-mode flag to set up management of NGINX App Protect on the instance. -# In the example below we specify 'precompiled-publication' for the flag value which will make the -# config field 'precompiled_publication' set to 'true', if you would like to set the config field -# 'precompiled_publication' to 'false' you can specify 'none' as the flag value. -sudo sh ./install.sh --nap-monitoring true --nginx-app-protect-mode precompiled-publication -``` - - {{}} - -1. Restart NGINX Agent: - - ``` bash - sudo systemctl restart nginx-agent - ``` - ---- - -## Create instances for Security Monitoring only - -Complete the steps in this section if you are only using the Security Monitoring module to monitor your application security. In this use case, you are **not using Instance Manager** to manage your WAF security policies. - -Repeat the steps below on each NGINX App Protect WAF data plane instance. - -1. Use SSH to connect to the data plane host. - -1. Create a new log format definition file with the name `/etc/app_protect/conf/log_sm.json` and the contents shown below. - This defines the log format for the Security Monitoring module. - - This configuration sets the maximum accepted request payload to 2048 bytes and the maximum message size to 5k. The latter setting truncates messages larger than 5k. -2. Add character escaping for the used separator `,` to be escaped with its standard URL encoding `%2C`. - - ``` json - { - "filter": { - "request_type": "illegal" - }, - "content": { - "format": "user-defined", - "format_string": "%blocking_exception_reason%,%dest_port%,%ip_client%,%is_truncated_bool%,%method%,%policy_name%,%protocol%,%request_status%,%response_code%,%severity%,%sig_cves%,%sig_set_names%,%src_port%,%sub_violations%,%support_id%,%threat_campaign_names%,%violation_rating%,%vs_name%,%x_forwarded_for_header_value%,%outcome%,%outcome_reason%,%violations%,%violation_details%,%bot_signature_name%,%bot_category%,%bot_anomalies%,%enforced_bot_anomalies%,%client_class%,%client_application%,%client_application_version%,%transport_protocol%,%uri%,%request%", - "escaping_characters": [ - { - "from": ",", - "to": "%2C" - } - ], - "max_request_size": "2048", - "max_message_size": "5k", - "list_delimiter": "::" - } - } - ``` - -1. Find the context in your NGINX configuration where NGINX App Protect WAF logging is enabled. - In the same context, add the `app_protect_security_log` directive shown in the example below to configure attack data logging for use with the Security Monitoring dashboards. - - ```nginx - app_protect_security_log_enable on; - app_protect_security_log "/etc/app_protect/conf/log_sm.json" syslog:server=127.0.0.1:514; - ``` - - {{}}The `syslog:server=:` must match the `syslog_ip` and `syslog_port` values specified in the [NGINX Agent configuration file](#agent-config). The dashboards won't display any data if these settings don't match. Also, the networking changes for NGINX App Protect Version 5 preclude the use of `127.0.0.1` as a syslog server address. For Version 5, the address of the `docker0` interface (typically `192.0.10.1`) or the IP address of the data plane host can be used for the syslog server address.{{}} - -1. Restart NGINX Agent and the NGINX web server. - - ```bash - sudo systemctl restart nginx-agent - sudo systemctl restart nginx - ``` - -You should now be able to view data from your NGINX App Protect instances in the NGINX Security Monitoring dashboards. - ---- - -## Create instances for Security Monitoring with Instance Manager - -Complete the steps in this section if you want to use the Security Monitoring module **and** Instance Manager. In this use case, you will use NGINX Instance Manager to monitor threats and to manage your NGINX App Protect WAF configurations and security policies. - -Take the steps below to update your NGINX App Protect WAF configurations by using Instance Manager. - -1. Log in to the NGINX Instance Manager user interface and go to **Modules** > **Instance Manager**. -1. Select **Instances** or **Instance Groups**, as appropriate. -1. Select **Edit Config** from the **Actions** menu for the desired instance or instance group. -1. Next, edit the desired configuration file. You will add directives that reference the security policies bundle and enable the NGINX App Protect WAF logs required by the Security Monitoring dashboards. An example configuration is provided below. - - ```nginx - app_protect_enable on; - app_protect_enable on; - app_protect_policy_file "/etc/nms/NginxDefaultPolicy.tgz"; - app_protect_security_log_enable on; - app_protect_security_log "/etc/nms/secops_dashboard.tgz" syslog:server=127.0.0.1:514; - ``` - - - Add the `app_protect_policy_file` directive with a reference to a security policy. - - The policy reference must use the `.tgz` file extension when using Instance Manager to perform precompiled publication of NGINX App Protect WAF policies and log profiles. The file path referenced must exist on the NGINX Instance Manager host, but it's ok if the policy file doesn't exist yet. If your Instance is not configured for precompiled publication, then use the `.json` file extension for polcies and log profiles. In this case, the file path referenced in the NGINX configuration must reside on the Instance. - - If you are using custom security policies, at this stage, it's fine to use the default security policy shown in the example above. After completing the steps in this guide, refer to the instructions in [Set Up App Protect WAF Configuration Management]({{< relref "/nim/nginx-app-protect/setup-waf-config-management#add-waf-config" >}}) to add your custom security policy files to NGINX Instance Manager and update your NGINX configuration. - - - Add the `app_protect_security_log_enable on` and the `app_protect_security_log` directive to any NGINX context where NGINX App Protect WAF is enabled and you want to be able to review attack data. - - The logging configuration must reference `"/etc/nms/secops_dashboard.tgz"`, as shown in the example. - - If the `app_protect_security_log_enable` setting is already present, just add the `app_protect_security_log` beneath it in the same context. - - {{}}The `syslog:server=:` must match the `syslog_ip` and `syslog_port` values specified in the [NGINX Agent configuration file](#agent-config). The Security Monitoring dashboards won't display any data if these settings don't match. Also, the networking changes for NGINX App Protect Version 5 preclude the use of `127.0.0.1` as a syslog server address. For Version 5, the address of the `docker0` interface (typically `192.0.10.1`) or the IP address of the data plane host can be used for the syslog server address.{{}} - -1. Select **Publish** to immediately push the configuration file updates out to your NGINX instance or instance group. - -You should now be able to view data from your NGINX App Protect WAF instances in the Security Monitoring dashboard. - -## See also - -- [Grant Users Access to the Security Monitoring Dashboards]({{< relref "create-role-security-monitoring" >}}): Follow the steps in this guide to allow other users in your organization to access the Security Monitoring Dashboards. - -- If you are using Security Monitoring with Instance Manager, proceed to the [Set Up App Protect WAF Configuration Management]({{< relref "/nim/nginx-app-protect/setup-waf-config-management" >}}) guide. diff --git a/content/nim/monitoring/security-monitoring/configure/update-geo-db.md b/content/nim/monitoring/security-monitoring/configure/update-geo-db.md deleted file mode 100644 index 7eadcef1d..000000000 --- a/content/nim/monitoring/security-monitoring/configure/update-geo-db.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: Update the geolocation database used in dashboards -description: Learn how to update the Geolocation Database used in F5 NGINX Management - Suite Security Monitoring dashboards. -toc: true -weight: 400 -type: how-to -product: NIM -docs: DOCS-1108 ---- - -## Overview - -You can use F5 NGINX Security Monitoring to monitor NGINX App Protect WAF instances. The Security Monitoring analytics dashboard uses MaxMind's GeoLite2 Free Database to provide extra Geolocation data for Security Violations. - -By completing the steps in this topic, you will be able to update the Security Monitoring module to get the latest Geolocation database such that the dashboards can provide accurate data. - ---- - -## Before you begin - -Complete the following prerequisites before proceeding with this guide: - -- NGINX Security Monitoring is [installed]({{< relref "/nim/monitoring/security-monitoring/install-security-monitoring.md" >}}) and running. -- NGINX App Protect is configured, and the Security Monitoring dashboard is gathering security violations - - ---- - -## Update the geolocation database - -1. Create a [MaxMind](https://dev.maxmind.com/geoip/geolite2-free-geolocation-data/) account and subscribe to get the latest updates to the Geolocation database. -1. Download the GeoLite2 Country (Edition ID: GeoLite2-Country) database in a GeoIP2 Binary `.mmdb` format from the [MaxMind](https://www.maxmind.com/en/accounts/current/geoip/downloads) website. The database will be present in a `gzip` downloaded file. -1. Unzip the downloaded `gzip` file, which contains the binary data of the GeoLite2 Country database with a filename `GeoLite2-Country.mmdb` -1. Replace the `GeoLite2-Country.mmdb` present on your NGINX Instance Manager's Control Plane at `/usr/share/nms/geolite2/GeoLite2-Country.mmdb` with the newly downloaded GeoLite2 Country database. - - ```bash - sudo scp /path/to/GeoLite2-Country.mmdb {user}@{host}:/usr/share/nms/geolite2/GeoLite2-Country.mmdb - ``` - -1. Restart the NGINX Instance Manager services - - ```bash - sudo systemctl restart nms-ingestion - sudo systemctl restart nms-core - ``` diff --git a/content/nim/monitoring/security-monitoring/configure/update-signatures.md b/content/nim/monitoring/security-monitoring/configure/update-signatures.md deleted file mode 100644 index 6301708d9..000000000 --- a/content/nim/monitoring/security-monitoring/configure/update-signatures.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: Update the Attack Signature Database -description: Learn how to update the Attack Signature Database used in F5 NGINX Management - Suite Security Monitoring dashboards. -toc: true -weight: 300 -type: how-to -product: NIM -docs: DOCS-1109 ---- - -## Overview - -You can use the F5 NGINX Security Monitoring module to monitor NGINX App Protect WAF instances for security. The Security Monitoring module analytics dashboards utilize a Signature Database to give more detail about the Attack Signatures that have caused a Security Violation, like the Signature's name, accuracy, and risk. - -If the Signature Database is not updated to match the Attack Signature version used for App Protect WAF protection, new signatures may be triggered without a name or other attributes like risk and accuracy. - -The steps in this topic ensure that dashboards show the correct information by updating the Security Monitoring module with the newest Attack Signature data. - ---- - -## Before you begin - -Complete the following prerequisites before proceeding with this guide: - -- NGINX Security Monitoring is [installed]({{< relref "/nim/monitoring/security-monitoring/install-security-monitoring.md" >}}) and running -- NGINX App Protect is configured, and the Security Monitoring dashboard is gathering security violations - ---- - -## Update the Signature Database - -1. Open an SSH connection to the data plane host and log in. -1. Use the [Attack Signature Report Tool]({{< relref "/nap-waf/v4/configuration-guide/configuration.md#attack-signature-report-tool" >}}) to generate a Signature Report file. The filename must be `signature-report.json`. - - ```bash - sudo /opt/app_protect/bin/get-signatures -o ./signature-report.json - ``` - -1. Open an SSH connection to the management plane host and log in. -1. Replace the `signature-report.json` on your NGINX Instance Manager's control plane at `/usr/share/nms/sigdb/signature-report.json` with the newly generated Signature Report. - - ```bash - sudo scp /path/to/signature-report.json {user}@{host}:/usr/share/nms/sigdb/signature-report.json - ``` - -1. Restart the NGINX Instance Manager services: - - ```bash - sudo systemctl restart nms-ingestion - sudo systemctl restart nms-core - ``` \ No newline at end of file diff --git a/content/nim/monitoring/security-monitoring/install-security-monitoring.md b/content/nim/monitoring/security-monitoring/install-security-monitoring.md deleted file mode 100644 index db0164269..000000000 --- a/content/nim/monitoring/security-monitoring/install-security-monitoring.md +++ /dev/null @@ -1,157 +0,0 @@ ---- -title: "Install or upgrade Security Monitoring" -toc: true -weight: 100 -doctype: how-to -product: NIM -docs: DOCS-1208 ---- - -## Overview - -Follow the steps in this guide to install or upgrade or upgrade the NGINX Security Monitoring module. - ---- - -## Before you begin - -### Security considerations - -{{< include "installation/secure-installation.md" >}} - ---- - -### Installation prerequisites - -{{< include "installation/nms-prerequisites.md" >}} - ---- - -### Dependencies with Instance Manager - -{{< include "nim/tech-specs/security-management-plane-dependencies.md" >}} - ---- - -## Install Security Monitoring - -{{}} - -{{%tab name="CentOS, RHEL, RPM-Based"%}} - -1. To install the latest version of the Security Monitoring module, run the following command: - - ```bash - sudo yum -y install nms-sm - ``` - -{{%/tab%}} -{{%tab name="Debian, Ubuntu, Deb-Based"%}} - -1. To install the latest version of the Security Monitoring module, run the following commands: - - ```bash - sudo apt-get update - sudo apt-get install -y nms-sm - ``` - -{{%/tab%}} - -{{}} - -2. Restart the F5 NGINX Instance Manager services: - - ```bash - 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: - - ```bash - sudo systemctl restart nginx - ``` - -4. If running Security Monitoring v1.7.0 or higher, start the module: - - ```bash - sudo systemctl start nms-sm - ``` - - ---- - -### Access the web interface - -{{< include "installation/access-web-ui.md" >}} - - ---- - -### Add license - -A valid license is required to make full use of all the features in Security Monitoring module. - -Refer to the [Add a License]({{< relref "/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. - ---- - -## Upgrade Security Monitoring - -{{}}The upgrade process for Security Monitoring **does not** automatically upgrade Instance Manager, which is a package dependency. To ensure compatibility with Security Monitoring, you will need to manually [upgrade Instance Manager]({{< relref "/nim/deploy/vm-bare-metal/install.md#upgrade-nim" >}}) to a version supported by Security Monitoring. For specific version dependencies between Security Monitoring and Instance Manager, refer to the [Security Monitoring release notes]({{< relref "/nim/monitoring/security-monitoring/releases/release-notes.md" >}}).{{}} - -
- -{{}} -{{%tab name="CentOS, RHEL, RPM-Based"%}} - -1. To upgrade to the latest version of Security Monitoring, run the following command: - - ```bash - sudo yum update -y nms-sm - ``` - -{{%/tab%}} - -{{%tab name="Debian, Ubuntu, Deb-Based"%}} - -1. To upgrade to the latest version of the Security Monitoring, run the following command: - - ```bash - sudo apt-get update - sudo apt-get install -y --only-upgrade nms-sm - ``` - -{{%/tab%}} -{{}} - -2. Restart the NGINX Instance Manager platform services: - - ```bash - 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: - - ```bash - sudo systemctl restart nginx - ``` - -4. If running Security Monitoring v1.7.0 or higher, start the module: - - ```bash - sudo systemctl start nms-sm - ``` - -5. (Optional) If you use SELinux, follow the steps in the [Configure SELinux]({{< relref "/nim/system-configuration/configure-selinux.md" >}}) guide to restore the default SELinux labels (`restorecon`) for the files and directories related to NGINX Instance Manager. - ---- - -## See also - -To set up your NGINX App Protect WAF data plane instances for use with Security Monitoring, refer to the following instructions: - -- [Create App Protect WAF instances for Security Monitoring]({{< relref "/nim/monitoring/security-monitoring/configure/set-up-app-protect-instances" >}}) diff --git a/content/nim/monitoring/security-monitoring/releases/_index.md b/content/nim/monitoring/security-monitoring/releases/_index.md deleted file mode 100644 index 65ec4e6d0..000000000 --- a/content/nim/monitoring/security-monitoring/releases/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: Releases -description: "Stay up-to-date with the latest F5 NGINX Security Monitoring releases." -weight: 300 ---- diff --git a/content/nim/monitoring/security-monitoring/releases/known-issues.md b/content/nim/monitoring/security-monitoring/releases/known-issues.md deleted file mode 100644 index 898f1a037..000000000 --- a/content/nim/monitoring/security-monitoring/releases/known-issues.md +++ /dev/null @@ -1,120 +0,0 @@ ---- -title: Known issues -description: This document lists and describes the known issues and possible workarounds - in the F5 NGINX Security Monitoring module. Fixed issues are removed - after **45 days**. -toc: true -weight: 200 -doctype: reference -product: NIM -docs: DOCS-1077 ---- - -{{< tip >}}We recommend you upgrade to the latest version of the Security Monitoring module to take advantage of new features, improvements, and bug fixes.{{< /tip >}} - ---- - -## 1.7.0 -October 18, 2023 - -### {{% icon-bug %}} Web interface fails to load after restarting NGINX Instance Manager {#44587} - -{{}} - -| Issue ID | Status | -|----------------|--------| -| 44587 | Open | - -{{}} -#### Description -The NGINX Instance Manager web interface can fail to load with a "Page not found" error after restarting its service. The security monitoring module will fail to appear on the launchpad until the page is manually reloaded. - -#### Workaround - -Reload the page in the browser to resolve this issue. - ---- - -## 1.5.0 -June 12, 2023 - -### {{% icon-resolved %}} Using empty values as filters returns inaccurate results {#42941} - -{{}} - -| Issue ID | Status | -|----------------|--------| -| 42941 | Fixed in Security Monitoring -1.6.0 | - -{{}} -#### Description -Using an empty string as a key or value results in an empty dataset. - ---- - -## 1.0.0 -November 17, 2022 - -### {{% icon-resolved %}} The API Connectivity Manager module won't load if the Security Monitoring module is enabled {#44433} - -{{}} - -| Issue ID | Status | -|----------------|--------| -| 44433 | Fixed in Instance Manager 2.8.0 | - -{{}} -#### Description -If you have Instance Manager 2.7 or earlier installed and attempt to enable both the API Connectivity Manager and Security Monitoring modules on the same NGINX Instance Manager management plane, the API Connectivity Manager module will not load because of incompatibility issues with the Security Monitoring module. - -#### Workaround - -Before enabling the API Connectivity Manager and Security Monitoring modules, ensure that your Instance Manager is upgraded to version 2.8 or later. Be sure to read the release notes for each module carefully, as they may contain important information about version dependencies. - -To see which version of Instance Manager you have installed, run the following command: - -- CentOS, RHEL, RPM-based: - - ```bash - yum info nms-instance-manager - ``` - -- Debian, Ubuntu, Deb-based: - - ```bash - dpkg -s nms-instance-manager - ``` - ---- - -### {{% icon-bug %}} Filtering data by Instance Group in the Security Monitoring module does not show any results. {#38790} - -{{}} - -| Issue ID | Status | -|----------------|--------| -| 38790 | Open | - -{{}} -#### Description -The Security Monitoring plugin on NGINX Agent does not automatically pick up changes made to agent-dynamic.conf, causing the Instance Group association to be missing in the Security Violations generated. - -#### Workaround - -Restart the NGINX Agent, and the subsequent Violations should be associated with the Instance Group: - -`systemctl restart nginx-agent` - ---- - -### {{% icon-resolved %}} The field retrieving URIs is incorrectly listed as URL {#38377} - -{{}} - -| Issue ID | Status | -|----------------|--------| -| 38377 | Fixed in Security Monitoring -1.2.0 | - -{{}} -#### Description -The field with URI data was mapped to the heading URL. The name of the field has been corrected. diff --git a/content/nim/monitoring/security-monitoring/releases/release-notes.md b/content/nim/monitoring/security-monitoring/releases/release-notes.md deleted file mode 100644 index 1d73b2fbc..000000000 --- a/content/nim/monitoring/security-monitoring/releases/release-notes.md +++ /dev/null @@ -1,317 +0,0 @@ ---- -title: Release notes -description: These release notes list and describe the new features, enhancements, - and resolved issues in the F5 NGINX Security Monitoring module. -toc: true -weight: 100 -doctype: reference -product: NIM -docs: DOCS-1078 ---- - ---- - -## 1.7.1 - -October 23, 2023 - -### Upgrade Paths {#1-7-1-upgrade-paths} - -Security Monitoring supports upgrades from these previous versions: - -- 1.4.0 - 1.7.0 - -If your Security Monitoring version is older, you may need to upgrade to an intermediate version before upgrading to the target version. - - - -### What's New{#1-7-1-whats-new} -This release includes the following updates: - -- {{% icon-feature %}} **Stability and performance improvements** - - This release includes stability and performance improvements. - - -### Known Issues{#1-7-1-known-issues} - -You can find information about known issues in the [Known Issues]({{< relref "/nim/monitoring/security-monitoring/releases/known-issues.md" >}}) topic. - ---- - -## 1.7.0 - -October 18, 2023 - -### Upgrade Paths {#1-7-0-upgrade-paths} - -Security Monitoring supports upgrades from these previous versions: - -- 1.4.0 - 1.6.0 - -If your Security Monitoring version is older, you may need to upgrade to an intermediate version before upgrading to the target version. - - - -### Changes in Default Behavior{#1-7-0-changes-in-behavior} -This release has the following changes in default behavior: - -- {{% icon-feature %}} **Security Monitoring backend service** - - The backend for Security Monitoring is now served by the `nms-sm` process instead of `nms-core`. The `nms-sm` process must be started after installation of the `nms-sm` package. - - -### Known Issues{#1-7-0-known-issues} - -You can find information about known issues in the [Known Issues]({{< relref "/nim/monitoring/security-monitoring/releases/known-issues.md" >}}) topic. - ---- - -## 1.6.0 - -July 20, 2023 - -### Upgrade Paths {#1-6-0-upgrade-paths} - -Security Monitoring supports upgrades from these previous versions: - -- 1.3.0 - 1.5.0 - -If your Security Monitoring version is older, you may need to upgrade to an intermediate version before upgrading to the target version. - - - -### Resolved Issues{#1-6-0-resolved-issues} -This release fixes the following issues. Select an issue's ID link to view its details. - -- {{% icon-resolved %}} Using empty values as filters returns inaccurate results [(42941)]({{< relref "/nim/monitoring/security-monitoring/releases/known-issues.md#42941" >}}) - -### Known Issues{#1-6-0-known-issues} - -You can find information about known issues in the [Known Issues]({{< relref "/nim/monitoring/security-monitoring/releases/known-issues.md" >}}) topic. - ---- - -## 1.5.0 - -June 12, 2023 - -### Upgrade Paths {#1-5-0-upgrade-paths} - -Security Monitoring supports upgrades from these previous versions: - -- 1.2.0 - 1.4.0 - -If your Security Monitoring version is older, you may need to upgrade to an intermediate version before upgrading to the target version. - - - -### What's New{#1-5-0-whats-new} -This release includes the following updates: - -- {{% icon-feature %}} **Improved security monitoring with violation and signature details** - - This release adds violation and signature details to Security Monitoring. This information helps you identify false positives and gain a more comprehensive understanding of violations, allowing you to fine-tune your security policies and optimize your threat detection. - - -### Known Issues{#1-5-0-known-issues} - -You can find information about known issues in the [Known Issues]({{< relref "/nim/monitoring/security-monitoring/releases/known-issues.md" >}}) topic. - ---- - -## 1.4.0 - -April 26, 2023 - -### Upgrade Paths {#1-4-0-upgrade-paths} - -Security Monitoring supports upgrades from these previous versions: - -- 1.1.0 - 1.3.0 - -If your Security Monitoring version is older, you may need to upgrade to an intermediate version before upgrading to the target version. - - - -### What's New{#1-4-0-whats-new} -This release includes the following updates: - -- {{% icon-feature %}} **View violation context for requests in Event logs** - - You can now view the request entity and its associated details that triggered a WAF violation from the event logs. - - -### Changes in Default Behavior{#1-4-0-changes-in-behavior} -This release has the following changes in default behavior: - -- {{% icon-feature %}} **Update to the Signature context pie chart** - - The Signature context pie chart now shows information related to signature-based violations in requests and URIs, in addition to the already available header, parameter, and cookie information. - - -### Known Issues{#1-4-0-known-issues} - -You can find information about known issues in the [Known Issues]({{< relref "/nim/monitoring/security-monitoring/releases/known-issues.md" >}}) topic. - ---- - -## 1.3.0 - -March 21, 2023 - -### Upgrade Paths {#1-3-0-upgrade-paths} - -Security Monitoring supports upgrades from these previous versions: - -- 1.0.0 - 1.2.0 - -If your Security Monitoring version is older, you may need to upgrade to an intermediate version before upgrading to the target version. - - - -### What's New{#1-3-0-whats-new} -This release includes the following updates: - -- {{% icon-feature %}} **Top Signatures section added to the Main tab** - - The "Top Signatures" section is now available in the "Main" tab of the Security Monitoring module dashboard. - - -### Security Updates{#1-3-0-security-updates} - -{{< important >}} -For the protection of our customers, NGINX doesn’t disclose security issues until an investigation has occurred and a fix is available. -{{< /important >}} - -This release includes the following security updates: - -- {{% icon-resolved %}} **Instance Manager vulnerability CVE-2023-1550** - - NGINX Agent inserts sensitive information into a log file ([CVE-2023-1550](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2023-1550)). An authenticated attacker with local access to read NGINX Agent log files may gain access to private keys. This issue is exposed only when the non-default trace-level logging is enabled. - - NGINX Agent is included with NGINX Instance Manager, and used in conjunction with API Connectivity Manager and the Security Monitoring module. - - This issue has been classified as [CWE-532: Insertion of Sensitive Information into Log File](https://cwe.mitre.org/data/definitions/532.html). - -#### Mitigation - -- Avoid configuring trace-level logging in the NGINX Agent configuration file. For more information, refer to the [Configuring the NGINX Agent]({{< relref "/nms/nginx-agent/install-nginx-agent.md#configuring-the-nginx-agent ">}}) section of NGINX Instance Manager documentation. If trace-level logging is required, ensure only trusted users have access to the log files. - -#### Fixed in - -- NGINX Agent 2.23.3 -- Instance Manager 2.9.0 - -For more information, refer to the MyF5 article [K000133135](https://my.f5.com/manage/s/article/K000133135). - - -### Changes in Default Behavior{#1-3-0-changes-in-behavior} -This release has the following changes in default behavior: - -- {{% icon-feature %}} **Improved error message when NGNIX Management Suite server is not running** - - The Security Monitoring module now displays the message "Upstream unavailable" when the NGINX Instance Manager server is not running, instead of the previous message "Oops something went wrong." - -- {{% icon-feature %}} **Single quotes are automatically escaped in filtered values** - - Single quotes in filtered values are automatically escaped to ensure that the data is parsed correctly. - - -### Known Issues{#1-3-0-known-issues} - -You can find information about known issues in the [Known Issues]({{< relref "/nim/monitoring/security-monitoring/releases/known-issues.md" >}}) topic. - ---- - -## 1.2.0 - -January 30, 2023 - -### Upgrade Paths {#1-2-0-upgrade-paths} - -Security Monitoring supports upgrades from these previous versions: - -- 1.0.0 - 1.1.0 - -If your Security Monitoring version is older, you may need to upgrade to an intermediate version before upgrading to the target version. - - - -### What's New{#1-2-0-whats-new} -This release includes the following updates: - -- {{% icon-feature %}} **Get the latest Signature and Geolocation Databases** - - [Update the Signature database]({{< relref "/nim/monitoring/security-monitoring/configure/update-signatures" >}}) to get the latest attack signature details. - - [Update the Geolocation Database]({{< relref "/nim/monitoring/security-monitoring/configure/update-geo-db" >}}) to get the most accurate mapping of IP address to Geolocation. - - -### Resolved Issues{#1-2-0-resolved-issues} -This release fixes the following issues. Select an issue's ID link to view its details. - -- {{% icon-resolved %}} The field retrieving URIs is incorrectly listed as URL [(38377)]({{< relref "/nim/monitoring/security-monitoring/releases/known-issues.md#38377" >}}) - -### Known Issues{#1-2-0-known-issues} - -You can find information about known issues in the [Known Issues]({{< relref "/nim/monitoring/security-monitoring/releases/known-issues.md" >}}) topic. - ---- - -## 1.1.0 - -December 20, 2022 - -### Upgrade Paths {#1-1-0-upgrade-paths} - -Security Monitoring supports upgrades from these previous versions: - -- 1.0.0 - -If your Security Monitoring version is older, you may need to upgrade to an intermediate version before upgrading to the target version. - - - -### Changes in Default Behavior{#1-1-0-changes-in-behavior} -This release has the following changes in default behavior: - -- {{% icon-feature %}} **Removal of Total Requests count** - - The Total Requests count was removed from the Security Monitoring dashboards, to avoid customer confusion, as the value didn't convey different configuration scenarios for NGINX App Protect on NGINX instances. - -- {{% icon-feature %}} **Removal of WAF PASSED requests count** - - The count of WAF `PASSED` requests was removed from the Security Monitoring dashboards to avoid customer confusion, as it counted only requests with violations and not all requests filtered by NGINX App Protect WAF. - - -### Known Issues{#1-1-0-known-issues} - -You can find information about known issues in the [Known Issues]({{< relref "/nim/monitoring/security-monitoring/releases/known-issues.md" >}}) topic. - ---- - -## 1.0.0 - -November 17, 2022 - - -### What's New{#1-0-0-whats-new} -This release includes the following updates: - -- {{% icon-feature %}} **Introducing the NGINX Security Monitoring module** - - Use the NGINX Security Monitoring module to monitor the NGINX App Protect WAF protection of your apps and APIs. View protection insights for analyzing possible threats and tuning policies. - - The Security Monitoring module includes the following: - - - Informative dashboards that provide valuable protection insights - - In-depth security log details to help with analyzing possible threats and making policy decisions - - Refer to the [Installation Guide]({{< relref "/nim/deploy/_index.md" >}}) to get started. - - -### Known Issues{#1-0-0-known-issues} - -You can find information about known issues in the [Known Issues]({{< relref "/nim/monitoring/security-monitoring/releases/known-issues.md" >}}) topic. - diff --git a/content/nim/monitoring/security-monitoring/troubleshooting.md b/content/nim/monitoring/security-monitoring/troubleshooting.md deleted file mode 100644 index 75230b7b2..000000000 --- a/content/nim/monitoring/security-monitoring/troubleshooting.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -description: This topic describes possible issues users might encounter when using - the Security Monitoring module. When possible, suggested workarounds are provided. -docs: DOCS-1226 -doctypes: -- reference -tags: -- docs -title: Troubleshooting -toc: true -weight: 1000 ---- - -## Security Event log backup with Security Monitoring - -### Description - -If a Security Violation event is not received by the Security Monitoring module, the data representing the attack is lost. - -### Resolution - -F5 NGINX App Protect supports logging to multiple destinations, enabling the user to send a log to NGINX agent and a copy to be stored as a backup. In the event of a failure to receive Security Events in Security Monitoring, the backup log can be checked to verify attack details. Change the settings below to enable backup logging: - -1. Instance with Security Monitoring only - -```nginx -app_protect_policy_file "/etc/app_protect/conf/NginxDefaultPolicy.json"; -app_protect_security_log_enable on; -app_protect_security_log "/etc/app_protect/conf/log_sm.json" syslog:server=127.0.0.1:514; -app_protect_security_log "/etc/app_protect/conf/log_sm.json" ; -# Example: app_protect_security_log "/etc/app_protect/conf/log_sm.json" /var/log/app_protect/security.log; -``` - -1. Instance with Security Monitoring and NGINX Instance Manager - -```nginx -app_protect_policy_file "/etc/nms/NginxDefaultPolicy.tgz"; -app_protect_security_log_enable on; -app_protect_security_log "/etc/nms/secops_dashboard.tgz" syslog:server=127.0.0.1:514; -app_protect_security_log "/etc/nms/secops_dashboard.tgz" ; -# Example: app_protect_security_log "/etc/nms/secops_dashboard.tgz" /var/log/app_protect/security.log; -``` - ---- - -## How to Get Support - -{{< include "support/how-to-get-support.md" >}} - diff --git a/content/nim/monitoring/security-monitoring/_index.md b/content/nim/nginx-app-protect/security-monitoring/_index.md similarity index 100% rename from content/nim/monitoring/security-monitoring/_index.md rename to content/nim/nginx-app-protect/security-monitoring/_index.md diff --git a/content/nim/nginx-app-protect/security-monitoring/give-access-to-security-monitoring-dashboards.md b/content/nim/nginx-app-protect/security-monitoring/give-access-to-security-monitoring-dashboards.md new file mode 100644 index 000000000..ffb2a1cfe --- /dev/null +++ b/content/nim/nginx-app-protect/security-monitoring/give-access-to-security-monitoring-dashboards.md @@ -0,0 +1,65 @@ +--- +title: Add user access to Security Monitoring dashboards +weight: 200 +toc: true +type: how-to +product: NIM +docs: DOCS-1026 +--- + +## Overview + +F5 NGINX Security Monitoring tracks activity on NGINX App Protect WAF instances. The dashboards and logs show insights, detect threats, and help improve security policies. + +This guide explains how to create a role to give users access to Security Monitoring and assign it to users or groups. + +{{< note >}} +This guide follows the principle of least privilege, so users only get access to Security Monitoring. You can create roles with different permissions if needed. +{{}} + +--- + +## Before you begin + +Make sure you complete these steps: + +- Your account must have access to User Management in NGINX Instance Manager. Minimum permissions are: + + - **Module**: Settings + - **Feature**: User Management + - **Access**: `READ`, `CREATE`, `UPDATE` + +- Use the table below to find the permissions you need: + + {{}} + + | Module(s) | Feature(s) | Access | Description | + |-----------------------------------|-----------------------|----------------------------|----------------------------------------------------------------------------------------------------------| + | Instance Manager
Security Monitoring | Analytics
Security Monitoring | `READ`
`READ` | Gives read-only access to Security Monitoring dashboards. Users cannot access NGINX Instance Manager or Settings. | + | Instance Manager
Security Monitoring
Settings | Analytics
Security Monitoring
User Management | `READ`
`READ`
`CREATE`, `READ`, `UPDATE` | Lets users view dashboards and manage accounts and roles.

{{< fa "lightbulb" >}} Best for "super-users" who manage dashboard access. Does not allow deleting accounts. | + + {{}} + +--- + +## Create a role + +{{< include "nim/rbac/create-roles.md" >}} + +--- + +## Assign the role + +Assign the Security Monitoring role to users or groups. + +--- + +### Assign the role to users + +{{< include "nim/rbac/assign-roles-to-users.md" >}} + +--- + +### Assign the role to user groups + +{{< include "nim/rbac/assign-roles-to-user-groups.md" >}} \ No newline at end of file diff --git a/content/nim/nginx-app-protect/security-monitoring/set-up-app-protect-instances.md b/content/nim/nginx-app-protect/security-monitoring/set-up-app-protect-instances.md new file mode 100644 index 000000000..9e58b4f51 --- /dev/null +++ b/content/nim/nginx-app-protect/security-monitoring/set-up-app-protect-instances.md @@ -0,0 +1,192 @@ +--- +title: Set up App Protect WAF instances for Security Monitoring +weight: 100 +toc: true +type: how-to +product: NIM +docs: DOCS-1107 +--- + +## Overview + +F5 NGINX Security Monitoring supports two main use cases: + +- **Security Monitoring only**: Monitor data from NGINX App Protect WAF instances. You can view security dashboards to identify threats and adjust policies. WAF configurations are managed outside NGINX Instance Manager. +- **Security Monitoring and Instance Manager**: Monitor security data and manage WAF configurations and policies in one place. Push pre-compiled updates to individual instances or groups. + +--- + +## Before you begin + +Complete these steps before starting: + +1. If you’re new to NGINX App Protect WAF, follow these guides: + + - [Install NGINX App Protect WAF](https://docs.nginx.com/nginx-app-protect/admin-guide/install/) on each data plane instance. Ensure connectivity to the NGINX Instance Manager host. + - [Configure NGINX App Protect WAF](https://docs.nginx.com/nginx-app-protect/configuration-guide/configuration/#policy-configuration-overview) as needed for each instance. + +2. Review NGINX App Protect WAF dependencies: + + {{< include "nim/tech-specs/security-data-plane-dependencies.md" >}} + +3. Determine your use case: **Security Monitoring only** or **Security Monitoring and Configuration Management**. + +--- + +## Install NGINX Agent + +NGINX Agent collects metrics, manages configurations, and sends events. Install and configure it on each WAF data plane host. + +1. Connect to the host via SSH. +2. Install the NGINX Agent package from the NGINX Instance Manager host: + + {{< include "agent/installation/install-agent-api.md" >}} + +3. Edit `/etc/nginx-agent/nginx-agent.conf` to enable `nap_monitoring`. Add this configuration: + + ```yaml + dataplane: + status: + poll_interval: 30s + report_interval: 24h + events: + enable: true + metrics: + bulk_size: 20 + report_interval: 1m + collection_interval: 15s + mode: aggregated + config_dirs: "/etc/nginx:/usr/local/etc/nginx:/usr/share/nginx/modules:/etc/nms:/etc/app_protect" + extensions: + - nginx-app-protect + - nap-monitoring + nginx_app_protect: + report_interval: 15s + precompiled_publication: true + nap_monitoring: + collector_buffer_size: 50000 + processor_buffer_size: 50000 + syslog_ip: "127.0.0.1" + syslog_port: 514 + ``` + +4. If `location /api` isn’t configured in `nginx.conf`, add this directive: + + ```nginx + server { + location /api { + api write=on; + allow 127.0.0.1; + deny all; + } + } + ``` + + Restart NGINX: + + ```bash + sudo systemctl restart nginx + ``` + +5. **Important:** The `syslog:server=:` must match the `syslog_ip` and `syslog_port` values in the NGINX Agent configuration file. The dashboards won’t display data if these settings don’t match. + + - For NGINX App Protect Version 5, networking changes prevent using `127.0.0.1` as a syslog server address. Instead, use the `docker0` interface address (typically `192.0.10.1`) or the IP address of the data plane host. + +6. Use the NGINX Agent installation script to add `nginx_app_protect` and `nap_monitoring` fields to the configuration. Follow these steps: + + ```bash + # Download the installation script via API + curl https:///install/nginx-agent > install.sh + + # Use the --nap-monitoring flag to set the child fields for nap_monitoring. + # The values will match the example configuration above. + # Use -m | --nginx-app-protect-mode to set up NGINX App Protect management. + # Example: Specify 'precompiled-publication' for precompiled policy publication, + # which sets 'precompiled_publication' to 'true'. To set it to 'false', use 'none'. + + sudo sh ./install.sh --nap-monitoring true --nginx-app-protect-mode precompiled-publication + ``` + + {{}}The `--nap-monitoring` flag adds fields under `nap_monitoring`. The `--nginx-app-protect-mode` flag sets up management of NGINX App Protect with the following options: + - Use `precompiled-publication` to enable precompiled policy publication (`precompiled_publication: true`). + - Use `none` if you don’t want to enable precompiled publication (`precompiled_publication: false`).{{}} + +7. Restart the NGINX Agent: + + ```bash + sudo systemctl restart nginx-agent + ``` + +--- + +## Create instances for Security Monitoring only + +Use these steps if you’re only monitoring security data without managing configurations in NGINX Instance Manager. + +1. Connect to the data plane host via SSH. +2. Create a log format file at `/etc/app_protect/conf/log_sm.json`: + + ```json + { + "filter": { + "request_type": "illegal" + }, + "content": { + "format": "user-defined", + "format_string": "%blocking_exception_reason%,%dest_port%,%ip_client%,%severity%,%uri%", + "escaping_characters": [ + { + "from": ",", + "to": "%2C" + } + ], + "max_request_size": "2048", + "max_message_size": "5k" + } + } + ``` + +3. In the NGINX configuration, add: + + ```nginx + app_protect_security_log_enable on; + app_protect_security_log "/etc/app_protect/conf/log_sm.json" syslog:server=127.0.0.1:514; + ``` + +4. Restart NGINX Agent and NGINX: + + ```bash + sudo systemctl restart nginx-agent + sudo systemctl restart nginx + ``` + +--- + +## Create instances for Security Monitoring with Instance Manager + +Follow these steps to use Security Monitoring and Instance Manager together. + +1. Log in to the NGINX Instance Manager interface. +2. Navigate to **Modules** > **Instance Manager**. +3. Select **Edit Config** for the desired instance or group. +4. Add the following to the configuration file: + + ```nginx + app_protect_enable on; + app_protect_policy_file "/etc/nms/NginxDefaultPolicy.tgz"; + app_protect_security_log_enable on; + app_protect_security_log "/etc/nms/secops_dashboard.tgz" syslog:server=127.0.0.1:514; + ``` + +5. **Important:** Add the `app_protect_policy_file` directive with a reference to a security policy. Use the `.tgz` file extension for precompiled publication or `.json` for non-precompiled configurations. Ensure the policy file exists at the specified location. If using custom policies, update them in NGINX Instance Manager. + +6. Add the `app_protect_security_log_enable` and `app_protect_security_log` directives to log attack data. Ensure the configuration references the correct `syslog:server` values. + +7. Select **Publish** to push updates to instances. + +--- + +## See also + +- [Add user access to Security Monitoring dashboards]({{< relref "/nim/nginx-app-protect/security-monitoring/give-access-to-security-monitoring-dashboards.md" >}}) +- [Manage your app protect WAF configs]({{< relref "/nim/nginx-app-protect/setup-waf-config-management" >}}) diff --git a/content/nim/nginx-app-protect/security-monitoring/troubleshooting.md b/content/nim/nginx-app-protect/security-monitoring/troubleshooting.md new file mode 100644 index 000000000..983405844 --- /dev/null +++ b/content/nim/nginx-app-protect/security-monitoring/troubleshooting.md @@ -0,0 +1,46 @@ +--- +docs: DOCS-1226 +doctypes: +- reference +tags: +- docs +title: Troubleshooting +toc: true +weight: 1000 +--- + +## Security event log backup with Security Monitoring + +### Description + +If a Security Violation event is not received by the Security Monitoring module, the attack data is lost. + +### Resolution + +F5 NGINX App Protect supports logging to multiple destinations. This allows users to send logs to the NGINX agent and store a backup. If Security Monitoring fails to receive Security Events, you can check the backup log to verify attack details. Use the following settings to enable backup logging: + +1. **For an instance with Security Monitoring only:** + + ```nginx + app_protect_policy_file "/etc/app_protect/conf/NginxDefaultPolicy.json"; + app_protect_security_log_enable on; + app_protect_security_log "/etc/app_protect/conf/log_sm.json" syslog:server=127.0.0.1:514; + app_protect_security_log "/etc/app_protect/conf/log_sm.json" ; + # Example: app_protect_security_log "/etc/app_protect/conf/log_sm.json" /var/log/app_protect/security.log; + ``` + +2. **For an instance with Security Monitoring and NGINX Instance Manager:** + + ```nginx + app_protect_policy_file "/etc/nms/NginxDefaultPolicy.tgz"; + app_protect_security_log_enable on; + app_protect_security_log "/etc/nms/secops_dashboard.tgz" syslog:server=127.0.0.1:514; + app_protect_security_log "/etc/nms/secops_dashboard.tgz" ; + # Example: app_protect_security_log "/etc/nms/secops_dashboard.tgz" /var/log/app_protect/security.log; + ``` + +--- + +## How to get support + +{{< include "support/how-to-get-support.md" >}} diff --git a/content/nim/nginx-app-protect/security-monitoring/update-geo-db.md b/content/nim/nginx-app-protect/security-monitoring/update-geo-db.md new file mode 100644 index 000000000..7d5a2495f --- /dev/null +++ b/content/nim/nginx-app-protect/security-monitoring/update-geo-db.md @@ -0,0 +1,42 @@ +--- +title: Update the geolocation database used in dashboards +weight: 400 +toc: true +type: how-to +product: NIM +docs: DOCS-1108 +--- + +## Overview + +The F5 NGINX Security Monitoring module tracks security violations on NGINX App Protect WAF instances. It uses MaxMind's GeoLite2 Free Database to provide geolocation data in analytics dashboards. + +Follow these steps to update the Security Monitoring module with the latest geolocation database, ensuring dashboards display accurate geolocation data. + +--- + +## Before you begin + +Ensure the following prerequisites are met: + +- NGINX App Protect is configured, and the Security Monitoring dashboard is collecting security violations. + +--- + +## Update the geolocation database + +1. Create a [MaxMind](https://dev.maxmind.com/geoip/geolite2-free-geolocation-data/) account and subscribe to receive updates for the GeoLite2 database. +2. Download the GeoLite2 Country database (Edition ID: GeoLite2-Country) in GeoIP2 Binary `.mmdb` format from the [MaxMind](https://www.maxmind.com/en/accounts/current/geoip/downloads) website. The database is included in a `.gzip` file. +3. Extract the `.gzip` file to access the GeoLite2 Country database file, named `GeoLite2-Country.mmdb`. +4. Replace the existing `GeoLite2-Country.mmdb` file on the NGINX Instance Manager control plane at `/usr/share/nms/geolite2/GeoLite2-Country.mmdb` with the new database: + + ```bash + sudo scp /path/to/GeoLite2-Country.mmdb {user}@{host}:/usr/share/nms/geolite2/GeoLite2-Country.mmdb + ``` + +5. Restart the NGINX Instance Manager services to apply the update: + + ```bash + sudo systemctl restart nms-ingestion + sudo systemctl restart nms-core + ``` diff --git a/content/nim/nginx-app-protect/security-monitoring/update-signatures.md b/content/nim/nginx-app-protect/security-monitoring/update-signatures.md new file mode 100644 index 000000000..374a75076 --- /dev/null +++ b/content/nim/nginx-app-protect/security-monitoring/update-signatures.md @@ -0,0 +1,49 @@ +--- +title: Update the Attack Signature Database +weight: 300 +toc: true +type: how-to +product: NIM +docs: DOCS-1109 +--- + +## Overview + +The F5 NGINX Security Monitoring module tracks security violations on NGINX App Protect WAF instances. Its analytics dashboards use a Signature Database to provide details about Attack Signatures, including their name, accuracy, and risk. + +If the Signature Database is outdated and doesn’t match the version used in App Protect WAF, new signatures may appear without attributes like a name, risk, or accuracy. + +Follow these steps to update the Security Monitoring module with the latest Attack Signature data, ensuring the dashboards display complete and accurate information. + +--- + +## Before you begin + +Ensure the following prerequisites are met: + +- NGINX App Protect is configured, and the Security Monitoring dashboard is collecting security violations. + +--- + +## Update the Signature Database + +1. Open an SSH connection to the data plane host and log in. +2. Generate a Signature Report file using the [Attack Signature Report Tool]({{< relref "/nap-waf/v4/configuration-guide/configuration.md#attack-signature-report-tool" >}}). Save the file as `signature-report.json`: + + ```bash + sudo /opt/app_protect/bin/get-signatures -o ./signature-report.json + ``` + +3. Open an SSH connection to the management plane host and log in. +4. Copy the `signature-report.json` file to the NGINX Instance Manager control plane at `/usr/share/nms/sigdb/`: + + ```bash + sudo scp /path/to/signature-report.json {user}@{host}:/usr/share/nms/sigdb/signature-report.json + ``` + +5. Restart the NGINX Instance Manager services to apply the update: + + ```bash + sudo systemctl restart nms-ingestion + sudo systemctl restart nms-core + ``` diff --git a/content/nim/nginx-app-protect/setup-waf-config-management.md b/content/nim/nginx-app-protect/setup-waf-config-management.md index 71bbe7256..7a1e73f0f 100644 --- a/content/nim/nginx-app-protect/setup-waf-config-management.md +++ b/content/nim/nginx-app-protect/setup-waf-config-management.md @@ -23,7 +23,7 @@ Complete the following prerequisites before proceeding with this guide. - You have one or more instances of [NGINX App Protect WAF](https://docs.nginx.com/nginx-app-protect/admin-guide/install/) installed and running. See [Support for NGINX App Protect WAF]({{< relref "tech-specs#support-for-nginx-app-protect-waf" >}}) for a list of supported versions. - {{}}If you are using configuration management and the NGINX Management Suite Security Monitoring module, follow the instructions in the [setup guide]({{}}) to set up your NGINX App Protect instances before proceeding with this guide.{{}} + {{}}If you are using configuration management and the NGINX Management Suite Security Monitoring module, follow the instructions in the [setup guide]({{}}) to set up your NGINX App Protect instances before proceeding with this guide.{{}} - You have Instance Manager v2.6.0 or later [installed]({{< relref "/nim/deploy/vm-bare-metal/_index.md" >}}), licensed, and running. If you have a subscription to NGINX App Protect WAF, you can find your Instance Manager license in the subscription details section of [MyF5](https://my.f5.com). @@ -398,7 +398,7 @@ curl -X POST 'https://{{NMS_FQDN}}//api/platform/v1/security/threat-campaigns' \ The Security Monitoring module's analytics dashboards make use of a Signature Database to provide more information on Attack Signatures that have triggered Security Violations, such as the Signature's name, accuracy, and risk level. -To ensure that the dashboards show the most up-to-date information, you need to [update the Security Monitoring Signature Database]({{< relref "/nim/monitoring/security-monitoring/configure/update-signatures" >}}) +To ensure that the dashboards show the most up-to-date information, you need to [update the Security Monitoring Signature Database]({{< relref "/nim/nginx-app-protect/security-monitoring/update-signatures" >}}) --- @@ -922,7 +922,7 @@ server { app_protect_security_log "/etc/nms/secops_dashboard.tgz" syslog:server=127.0.0.1:514; ``` -Refer to the [Security Monitoring setup guide]({{< relref "/nim/monitoring/security-monitoring/configure/set-up-app-protect-instances" >}}) to learn more. {{}} +Refer to the [Security Monitoring setup guide]({{< relref "/nim/nginx-app-protect/security-monitoring/set-up-app-protect-instances" >}}) to learn more. {{}} {{}} NGINX configuration for NGINX App Protect Version 5 requires the following changes: diff --git a/content/nim/releases/known-issues.md b/content/nim/releases/known-issues.md index 40b6d2007..bae3cfeec 100644 --- a/content/nim/releases/known-issues.md +++ b/content/nim/releases/known-issues.md @@ -14,6 +14,83 @@ weight: 200 {{< tip >}}We recommend you upgrade to the latest version of Instance Manager to take advantage of new features, improvements, and bug fixes.{{< /tip >}} +--- + +## 2.18.0 +November 8, 2024 + +### {{% icon-resolved %}} Error messages persist after fix {#45024} + +{{}} + +| Issue ID | Status | +|----------------|--------| +| 45024 | Fixed in Instance Manager 2.19.0 | + +### Description +There is an issue that causes previous error messages to persist in the web interface, even after fixing the error causing the message. + +{{}} + +#### Description +There is an issue that causes previous error messages to persist in the web interface, even after fixing the error. + +### {{% icon-resolved %}} .tgz files are not accepted in templates {#45301} + +{{}} + +| Issue ID | Status | +|----------------|--------| +| 45301 | Fixed in Instance Manager 2.19.0 | + +{{}} + +#### Description +`.tgz` files are not accepted in templates while `.tar.gz` files are. + +### {{% icon-resolved %}} NGINX configuration error messages overlap outside the error window {#45570} + +{{}} + +| Issue ID | Status | +|----------------|--------| +| 45570 | Fixed in Instance Manager 2.19.0 | + +{{}} + +#### Description +If there is an NGINX configuration error when pushing a template configuration, the text overlaps outside the error window. + +### {{% icon-resolved %}} Syntax errors while saving template configuration {#45573} + +{{}} + +| Issue ID | Status | +|----------------|--------| +| 45573 | Fixed in Instance Manager 2.19.0 | + +{{}} + +#### Description +Saving templates as “staged configs” causes syntax errors due to Augment templates being multiple directories down the tree. + +--- + +## 2.17.3 +September 13, 2024 + +### {{% icon-resolved %}} The web interface can't display more than 100 certificates {#45565} + +{{}} + +| Issue ID | Status | +|----------------|--------| +| 45565 | Fixed in Instance Manager 2.19.0 | + +{{}} + +#### Description +The Certificate Management screen can only show up to 100 certificates. --- diff --git a/content/nim/releases/release-notes.md b/content/nim/releases/release-notes.md index 3b91a208d..94383295e 100644 --- a/content/nim/releases/release-notes.md +++ b/content/nim/releases/release-notes.md @@ -16,6 +16,95 @@ The release notes for F5 NGINX Instance Manager highlight the latest features, i --- +## 2.19.0 + +February 6, 2025 + +### Upgrade Paths {#2-19-0-upgrade-paths} + +NGINX Instance Manager supports upgrades from these previous versions: + +- 2.16.x - 2.18.x + +If your NGINX Instance Manager version is older, you may need to upgrade to an intermediate version before upgrading to the target version. + +### Important Note about upgrades to NGINX Instance Manager 2.19 for API Connectivity Manager (ACM) users + +NGINX Instance Manager 2.19 is the first iteration of NGINX Instance Manager as a standalone product without modules such as API Connectivity Manager (which is [EoS](https://my.f5.com/manage/s/article/K000137989)). NGINX Instance Manager now includes Security Monitoring (previously a module) as a feature under App Protect in the web interface. The Instance Manager helm charts and docker compose options include Security Monitoring also. + +Instance Manager 2.19 will not be compatible or supported with EoS API Connectivity Manager. API Connectivity Manager users get support of Instance Manager up to 2.18 and upgrades to Instance Manager 2.19 will not succeed if API Connectivity Manager is installed. + +### What's New{#2-19-0-whats-new} +This release includes the following updates: + +- {{% icon-feature %}} **NGINX Instance Manager is now a standalone product** + + Starting with this release, NGINX Instance Manager is a standalone product without any dependencies from other NGINX products (NGINX Management Suite, API Connectivity Manager). + + The Security Monitoring module is now a feature of NGINX Instance Manager found in the "App Protect" section. + + If NGINX API Connectivity Manager is currently running as a module in NGINX Instance Manager or NGINX Management Suite in your environment, you will need to remove the module before upgrading to 2.19.0. + +- {{% icon-feature %}} **Forward proxy support using the HTTP CONNECT method** + + NGINX Instance Manager can now be configured to use the CONNECT HTTP method to request that a proxy establish a HTTP(S) tunnel to an outbound server. This covers all use-cases that require outbound access such as App Protect Signature updates, licensing and usage reporting. + + - Documentation: [Configure NGINX Instance Manager to use a forward proxy]({{< relref "nim/system-configuration/configure-forward-proxy.md" >}}) + +- {{% icon-feature %}} **Support for OpenShift Deployments using Helm** + + Added an `OpenShift` flag to the Helm charts that creates a security context constraint resource to support NGINX Instance Manager in OpenShift. + + - Documentation: [Deploy NGINX Instance Manager using Helm]({{< relref "nim/deploy/kubernetes/deploy-using-helm.md" >}}) + +- {{% icon-feature %}} **VM-based active-passive HA Support with keepalived** + + This release includes documentation for a basic HA (High availability) setup with two nodes, for bare metal and VM based environments. This feature uses keepalived and a failover script if a primary NGINX Instance Manager node fails. + + - Documentation: [Configure high availability (HA) for NGINX Instance Manager]({{< relref "nim/system-configuration/configure-high-availability.md" >}}) + +- {{% icon-feature %}} **Added "Export" feature for templates** + + We have added a new option to export templates using the NGINX Instance Manager web interface. + +### Changes in Default Behavior{#2-19-0-changes-in-behavior} + +This release has the following changes in default behavior: + +- {{% icon-feature %}} **Prompt to specify an FQDN for NIM when generating SSL certificates during installation** + + When installing, users will be prompted to enter a fully qualified domain name (FQDN) to include in the Subject Alternative Name (SAN) of the NGINX Instance Manager's self-signed certificate generated during installation. This FQDN can serve as the server name for NGINX Instance Manager. Users can also specify this FQDN in the Installation Script + + {{< note >}}Starting with NGINX Plus R33, usage data reporting requires validating the SSL certificate of NGINX Instance Manager via the `ssl_verify` directive in the `mgmt` block. Proper SAN configuration ensures seamless SSL verification.{{< /note >}} + +- {{% icon-feature %}} **Watchdog enhancements to improve stability** + + We have introduced new configurable element in `nms.conf` called `enable_watchdog_notifications`. When enabled, if any process takes longer than expected to respond the customer will get a notification in the web interface warning about the unresponsive process. Previously, a Watchdog process was stopping the process and led to configurations not applying. + +- {{% icon-feature %}} **Expired unmanaged certificates are eventually removed from the web interface** + + Starting in 2.19.0, remote certificates that are expired are removed from the web interface after 30 days. + +### Resolved Issues{#2-19-0-resolved-issues} +This release fixes the following issues. Select an issue's ID link to view its details. + +- {{% icon-resolved %}} .tgz files are not accepted in templates [(45301)]({{< relref "/nim/releases/known-issues.md#45301" >}}) + +- {{% icon-resolved %}} The web interface can't display more than 100 certificates [(45565)]({{< relref "/nim/releases/known-issues.md#45565" >}}) + +- {{% icon-resolved %}} Syntax errors while saving template configuration [(45573)]({{< relref "/nim/releases/known-issues.md#45573" >}}) + +- {{% icon-resolved %}} Error messages persist after fix [(45024)]({{< relref "/nim/releases/known-issues.md#45024" >}}) + +- {{% icon-resolved %}} NGINX configuration error messages overlap outside the error window [(45570)]({{< relref "/nim/releases/known-issues.md#45570" >}}) + + +### Known Issues{#2-19-0-known-issues} + +You can find information about known issues in the [Known Issues]({{< relref "/nim/releases/known-issues.md" >}}) topic. + +--- + ## 2.18.0 November 8, 2024 @@ -57,7 +146,7 @@ This release includes the following updates: - {{% icon-feature %}} **Resilient Docker Compose NGINX Instance Manager deployment** - In 2.17, we released a [bundled container image]({{< relref "nim/deploy/docker/deploy-nginx-instance-manager-docker.md" >}}) with all NGINX Instance Manager components. While this is a great option for demos and lab environments, it is not the most fault-tolerant for production. + In 2.17, we released a [bundled container image]({{< relref "nim/deploy/docker/deploy-nginx-instance-manager-docker.md" >}}) with all NGINX Instance Manager components. While this is a great option for demos and lab environments, it is not the most fault-tolerant for production. This [Docker Compose option]({{< relref "nim/deploy/docker/deploy-nginx-instance-manager-docker-compose.md" >}}) unlocks another easy, production-ready installation method for customers using Docker. It will also make upgrades easier when new Docker images are released by F5 NGINX. This option includes health checking, NGINX App Protect compilation support, and security monitoring. @@ -80,6 +169,8 @@ This release fixes the following issues. Select an issue's ID link to view its d You can find information about known issues in the [Known Issues]({{< relref "/nim/releases/known-issues.md" >}}) topic. +--- + ## 2.17.4 November 06, 2024 diff --git a/content/nim/system-configuration/configure-forward-proxy.md b/content/nim/system-configuration/configure-forward-proxy.md new file mode 100644 index 000000000..115038dc3 --- /dev/null +++ b/content/nim/system-configuration/configure-forward-proxy.md @@ -0,0 +1,246 @@ +--- +Title: Configure NGINX Instance Manager to use a forward proxy +weight: 2 +toc: true +type: how-to +product: NIM +docs: +--- + +## Overview + +This guide explains how to configure NGINX Instance Manager to use a third-party forward proxy for outbound internet access. Many organizations require a proxy for security and compliance, restricting direct internet connections. This feature allows NGINX Instance Manager to send outbound traffic, such as license verification, telemetry, and updates, through a configured HTTP or HTTPS proxy. + +--- + +## Before you begin + +Ensure you have: + +- NGINX Instance Manager **2.19 or later** +- Access to a configured HTTP or HTTPS forward proxy +- Permissions to modify `/etc/nms/nms.conf` +- Proxy authentication credentials, if required + +{{}} +#### Proxy SSL verification + +- `proxy_ssl_verify` applies **only when** `proxy_protocol` is set to `https`. +- If not explicitly set, **`proxy_ssl_verify` defaults to `true`**. The proxy’s root CA certificate must be in the system’s trusted CA store for verification to succeed. +- To disable SSL verification, set `proxy_ssl_verify: false` (not recommended). + +#### OpenShift limitation for HTTPS forward proxies + +On OpenShift, pods run as non-root users, which prevents the use of `update-ca-certificates` or `update-ca-trust` to add custom CA certificates for HTTPS forward proxies. As a result, HTTPS proxy configurations (with or without authentication) may not work if the proxy requires a trusted CA certificate. + +**Workarounds:** +- **Recommended**: Use an HTTP proxy instead of HTTPS. +- **Alternative (not recommended)**: Disable certificate verification by setting `proxy_ssl_verify: false`, which allows connections to proxies with untrusted or self-signed certificates. + +#### Feature limitations + +- **Mutual TLS (mTLS) authentication is not supported.** +- **OpenID Connect (OIDC) authentication is not supported in forward-proxy mode.** +- **OpenTelemetry (OTel) telemetry is not supported in forward-proxy mode.** +{{}} + +--- + +## Proxy configuration parameters + +The following table describes the available proxy configuration parameters in `/etc/nms/nms.conf`: + +{{}} +| Parameter | Description | +|------------------------|-------------| +| `proxy_enable` | Defines whether NGINX Instance Manager routes outbound traffic through a forward proxy.
**Supported values:** `true` (routes certain outbound requests through the proxy) or `false` (sends data directly to servers). | +| `proxy_host` | IP address of the third-party forward proxy. | +| `proxy_port` | Port on which the third-party proxy is running. | +| `proxy_protocol` | Protocol used to interact with the proxy.
**Supported values:** `http`, `https`. | +| `proxy_auth_required` | Determines whether authentication is enforced for proxy access.
**Supported values:** `true` (proxy requires authentication) or `false` (proxy does not require authentication). | +| `proxy_username` | Username for authentication with the proxy (if `proxy_auth_required: true`). | +| `proxy_password` | Password for authentication with the proxy (if `proxy_auth_required: true`). | +| `proxy_ssl_verify` | Controls SSL certificate verification when `proxy_protocol` is `https`.
**Default value:** `true`.
**Supported values:** `true` (only trusted proxies allowed) or `false` (allows untrusted/self-signed certificates). | +{{}} + +--- + +## Configure the forward proxy + +### VM or bare-metal + +In a VM or bare-metal deployment, configure a forward proxy by updating the `nms.conf` file on the NGINX Instance Manager host. + +To configure a forward proxy: + +1. Edit the `/etc/nms/nms.conf` file. + +2. Add or modify the `proxy_config` section to include the proxy configuration: + + ```yaml + proxy_config: + proxy_enable: true + proxy_host: + proxy_port: + proxy_protocol: [http|https] + proxy_auth_required: [true|false] + proxy_ssl_verify: [true|false] + ``` + + - If the proxy requires authentication, set `proxy_auth_required` to `true`, and add the following fields: + + ```yaml + proxy_username: "" + proxy_password: "" + ``` + + - Set `proxy_protocol` to either `http` or `https`, depending on your proxy type. + - If not explicitly set, `proxy_ssl_verify` **defaults to `true`**, meaning the proxy must have a valid certificate from a trusted Certificate Authority (CA). Note: This setting applies only when `proxy_protocol` is `https`. + + If the proxy uses a self-signed or untrusted certificate, you have two options: + - **Recommended**: Follow the steps in the [Trust proxy certificates](#trust-proxy-certificates-if-required) section to add the proxy's CA certificate to the system's trusted store. + - **Alternative (not recommended)**: Disable SSL verification by setting `proxy_ssl_verify=false`, which allows connections to proxies with untrusted or self-signed certificates. + +3. Save the configuration file. + +4. Restart NGINX Instance Manager to apply changes: + + ```shell + sudo systemctl restart nms + ``` + +### Kubernetes + +In a Kubernetes deployment, configure a forward proxy by modifying the `nms-conf` ConfigMap. + +To edit the ConfigMap, run: + +```shell +kubectl edit cm nms-conf -n +``` + +- Replace `` with the namespace where NGINX Instance Manager is installed. +- Update the `proxy_config` section to match your proxy settings. See the [examples under "Configure the forward proxy"](#configure-the-forward-proxy). + +### Docker Compose + +If you’re deploying NGINX Instance Manager with Docker Compose, update the `docker-compose.yaml` file to configure a forward proxy. + +1. **Before you begin**: Follow the [Docker Compose deployment guide]({{< relref "nim/deploy/docker/deploy-nginx-instance-manager-docker-compose.md" >}}) to set up Docker for the NGINX container registry. The deployment guide also covers additional environment variables you may want to consider before deployment. +2. {{}} {{}} +3. Update `docker-compose.yaml` with the proxy settings: + + Modify the `services.nim.environment` section to include the proxy configuration: + + ```yaml + services: + nim: + image: private-registry.nginx.com/nms/nim-standalone-compose: + depends_on: + clickhouse: + condition: service_healthy + hostname: nim + ports: + - 443:443 + networks: + - external_network + - clickhouse + environment: + - PROXY_ENABLE=true + - PROXY_HOST= + - PROXY_PORT= + - PROXY_PROTOCOL=[http|https] + - PROXY_AUTH_REQUIRED=[true|false] + - PROXY_SSL_VERIFY=[true|false] + volumes: + - nim-data:/data + - proxy-certs:/usr/local/share/ca-certificates + - ./:/usr/local/share/ca-certificates/ + ``` + + - If the proxy requires authentication, set `PROXY_AUTH_REQUIRED` to `true`, and add the following fields: + + + ```yaml + - PROXY_AUTH_USERNAME= + - PROXY_PASSWORD= + ``` + + - Replace `` with the filename of the proxy CA certificate. + - Set `PROXY_PROTOCOL` to either `http` or `https`, depending on your proxy type. + - If not explicitly set, **`PROXY_SSL_VERIFY` defaults to `true`**, meaning the proxy must have a valid certificate issued by a trusted Certificate Authority (CA). Note: This setting applies only when `PROXY_PROTOCOL` is `https`. + + If the proxy uses a self-signed or untrusted certificate, you have two options: + - **Recommended**: Follow the steps in the [Trust proxy certificates](#trust-proxy-certificates-if-required) section to add the proxy's CA certificate to the system's trusted store. + - **Alternative (not recommended)**: Disable SSL verification by setting `PROXY_SSL_VERIFY=false`, which allows connections to proxies with untrusted or self-signed certificates. + + +4. Deploy NGINX Instance Manager: + + ```shell + docker compose up -d + ``` + +--- + +## Trust proxy certificates (if required) + +If your proxy uses HTTPS and `proxy_ssl_verify` is set to `true`, NGINX Instance Manager expects the proxy’s CA certificate to be trusted. If the proxy certificate is self-signed or issued by an untrusted Certificate Authority (CA), you must manually add it to the system’s trusted store. + +{{}}For Kubernetes deployments, perform these steps inside the **integrations pod**.{{}} + +1. Copy the proxy CA certificate into the system’s trusted certificate directory. The path varies by distribution: + - **Debian/Ubuntu**: `/usr/local/share/ca-certificates/` + - **RHEL/CentOS**: `/etc/ssl/certs/` + +2. Run the appropriate command to update the system’s trusted certificates: + + - **Debian/Ubuntu**: + + ```bash + sudo update-ca-certificates + ``` + + - **RHEL/CentOS**: + + ```bash + sudo update-ca-trust + ``` + +3. Apply the changes: + + - **VM/bare-metal**: Restart NGINX Instance Manager: + + ```bash + sudo systemctl restart nms + ``` + + - **Kubernetes**: Restart the **integrations pod**. + +--- + +## Verify proxy connectivity + +After applying the configuration, verify that NGINX Instance Manager is using the proxy: + +- **Check system logs:** Review logs for messages confirming that traffic is being routed through the proxy. The exact log message may vary but should indicate the configured proxy details. + +- **Test outbound connectivity:** Use a tool such as `curl` or `wget` to confirm that requests are routed through the proxy. The exact command depends on your proxy configuration. + +- **Monitor network traffic:** If needed, use network debugging tools like `tcpdump` or `netstat` to verify that outbound requests are sent through the proxy. + +If proxy traffic is not working as expected, review the [troubleshooting section](#troubleshoot-common-issues) for possible causes. + +--- + +## Troubleshoot common issues + +{{}} +| **Issue** | **Log Message** | **Possible Cause** | **Resolution** | +|-----------|---------------|---------------------|--------------| +| **Authentication failed** | N/A | Incorrect proxy credentials. | Double-check `proxy_username` and `proxy_password`. | +| **Invalid proxy configuration** | `Error: failed to initialize LLM:`
`invalid forward proxy config: ` | The proxy configuration section is missing or improperly formatted. | - Ensure the proxy configuration is correct in `/etc/nms/nms.conf`.
- Verify all required parameters (`proxy_enable`, `proxy_host`, `proxy_port`, `proxy_protocol`) are set. | +| **Proxy initialization failure** | `unable to add proxy support,`
`err - ` | The proxy settings are misconfigured, or the proxy service is unavailable. | - Ensure that the proxy service is running and accessible.
- Verify that `proxy_enable` is set to `true` and all required parameters are correctly configured. | +| **Proxy not reachable** | N/A | Incorrect proxy IP or port. | Verify `proxy_host` and `proxy_port` in `/etc/nms/nms.conf`. | +| **TLS certificate verification error** | `proxyconnect tcp: tls:`
`failed to verify certificate:`
`x509: certificate signed by unknown authority` | SSL verification is enabled (default), but the proxy certificate is untrusted. | - Add the proxy’s CA certificate to the system’s trusted CA store.
- If necessary, disable SSL verification by setting proxy SSL verify to false (not recommended). | +{{}} diff --git a/content/nim/system-configuration/configure-high-availability.md b/content/nim/system-configuration/configure-high-availability.md new file mode 100644 index 000000000..ecff01f4b --- /dev/null +++ b/content/nim/system-configuration/configure-high-availability.md @@ -0,0 +1,262 @@ +--- +Title: Configure high availability (HA) for NGINX Instance Manager +weight: 3 +toc: true +type: how-to +product: NGINX Instance Manager +docs: +--- + +## Overview + +High availability (HA) keeps a system running even if some components fail. In an **active-passive** HA setup, two servers work together: + +- The active server handles all requests. +- The passive server stays on standby and takes over if the active server fails. + +This guide shows how to configure HA for NGINX Instance Manager using `keepalived`. This setup includes: + +- A virtual IP address (VIP) +- A shared Network File System (NFS) +- Automated health checks to detect failures and trigger failover + +--- + +## Before you begin + +Before setting up high availability (HA) for NGINX Instance Manager, make sure you have: + +- Two physical servers with NGINX Instance Manager installed +- A reserved virtual IP address (VIP) that always points to the active instance +- An NFS share that both servers can access +- Permissions to manage IP addresses at the operating system level +- `keepalived` installed on both servers + +Some cloud platforms don’t allow direct IP management with `keepalived`. If you’re using a cloud environment, check whether it supports VIP assignment. + +### Limitations + + This HA setup has the following restrictions: + +- This setup **supports only two nodes** — one active and one passive. Configurations with three or more nodes are not supported. +- Active/active HA is not supported. This configuration works only in an active-passive setup. +- Do not modify `keepalived`. Changes beyond what is documented may cause failures. +- OpenID Connect (OIDC) authentication is not supported when NGINX Instance Manager is running in [forward-proxy mode]({{< relref "nim/system-configuration/configure-forward-proxy.md" >}}). OIDC is configured on the NGINX Plus layer and cannot pass authentication requests through a forward proxy. + +--- + +## Reserve a virtual IP address + +A **virtual IP address (VIP)** ensures that users always connect to the active server. During failover, `keepalived` automatically moves the VIP from the primary to the secondary server. + +1. Choose an **unused IP address** in your network to serve as the VIP. +2. Ensure that the IP address does not conflict with existing devices. +3. Configure firewalls and security rules to allow traffic to and from the VIP. +4. Note the **VIP address**, as you will reference it in the `keepalived.conf` file. + +Replace `` with this IP when configuring `keepalived`. + +--- + +## Install and configure keepalived + +`keepalived` is a Linux tool that monitors system health and assigns a virtual IP (VIP) to the active server in an HA setup. + +### Install keepalived + +Install `keepalived` on both servers. + +- For **Debian-based systems (Ubuntu, Debian):** + + ```sh + sudo apt update + sudo apt install keepalived -y + ``` + +- For **RHEL-based systems (CentOS, RHEL):** + + ```sh + sudo yum install keepalived -y + ``` + +### Define monitored services + +`keepalived` monitors specific services to determine if a node is operational. Update `/etc/nms/scripts/nms-notify-keepalived.sh` to include the services you want to monitor. + +```sh +check_nms_services=( + "clickhouse-server" + "nginx" + "nms-core" + "nms-dpm" + "nms-integrations" + "nms-ingestion" +) +``` + +{{}}If you switch between connected and disconnected modes, you must update **/etc/nms/nms.conf** on both the primary and secondary nodes if `nms-integrations` is included in `check_nms_services`. NGINX Instance Manager runs in connected mode by default. For instructions on changing the mode, see the [installation guide for disconnected environments]({{< relref "nim/disconnected/offline-install-guide.md#set-mode-disconnected" >}}).{{}} + + +### Configure keepalived + +Edit `/etc/keepalived/keepalived.conf` on both servers and replace the placeholders with your actual network details. + +```sh +vrrp_script nms_check_keepalived { + script "/etc/nms/scripts/nms-check-keepalived.sh" + interval 10 + weight 10 +} + +vrrp_instance VI_28 { + state MASTER # Set to BACKUP on the secondary server + interface # Replace with the correct network interface + priority 100 + virtual_router_id 251 + advert_int 1 + authentication { + auth_type PASS + auth_pass # Replace with a secure password + } + virtual_ipaddress { + # Replace with your reserved VIP + } + track_script { + nms_check_keepalived + } + notify /etc/nms/scripts/nms-notify-keepalived.sh +} +``` + +Replace: +- `` with your actual network interface (e.g., `ens32`). +- `` with a secure authentication password. +- `` with your reserved VIP. + +Ensure the configuration is identical on both servers, except for the `state` value: +- Set `MASTER` on the primary server. +- Set `BACKUP` on the secondary server. + +Restart `keepalived` to apply the configuration: + +```sh +sudo systemctl restart keepalived +``` + +--- + +## Configure Network File System (NFS) for shared storage + +NGINX Instance Manager requires shared storage for configuration files and logs. + +### Mount NFS on both servers + +Replace `` with the actual IP address of your NFS server in the following commands. + +```sh +sudo mount -t nfs4 \ + -o rw,relatime,vers=4.2, \ + rsize=524288,wsize=524288,namlen=255, \ + hard,proto=tcp,timeo=600,retrans=2,sec=sys \ + :/mnt/nfs_share/clickhouse \ + /var/lib/clickhouse + +sudo mount -t nfs4 \ + -o rw,relatime,vers=4.2, \ + rsize=524288,wsize=524288,namlen=255, \ + hard,proto=tcp,timeo=600,retrans=2,sec=sys \ + :/mnt/nfs_share/nms \ + /var/lib/nms +``` + +### Persist NFS mounts + +Add the following lines to `/etc/fstab` on both servers, replacing `` with your actual NFS server's IP. + +```sh +:/mnt/nfs_share/clickhouse /var/lib/clickhouse nfs defaults 0 0 +:/mnt/nfs_share/nms /var/lib/nms nfs defaults 0 0 +``` + +### Verify NFS mounts + +Run these commands to confirm that the NFS mounts are working: + +```sh +sudo mount -a +df -h +ls -lart /mnt/nfs_share/clickhouse +ls -lart /var/lib/nms +sudo ls -lart /var/lib/clickhouse +telnet 2049 +rpcinfo -p +sudo showmount -e +dmesg | grep nfs +``` + +--- + +## Test failover + +Failover can be tested by simulating a failure on the active server. + +### Methods to trigger failover + +- Restart `keepalived`: + + ```sh + sudo systemctl restart keepalived + ``` + +- Stop a monitored service: + + ```sh + sudo systemctl stop clickhouse-server + ``` + +- Reboot the active server: + + ```sh + sudo reboot + ``` + +- Simulate a network failure by disconnecting the active server. + +### Verify failover + +To check if the passive server has taken over, run the following command on the backup server: + +```sh +ip a | grep +``` + +The VIP should now be assigned to the secondary server. + +--- + +## Troubleshooting + +If failover does not work as expected, check the following: + +- Ensure `keepalived` is running: + ```sh + systemctl status keepalived + ``` +- Check logs for errors: + ```sh + journalctl -u keepalived --no-pager | tail -50 + ``` +- Verify that NFS mount points are accessible: + ```sh + df -h + ``` +- Check the `keepalived` configuration for syntax errors: + ```sh + cat /etc/keepalived/keepalived.conf + ``` + +--- + +## Need help? + +For additional support, visit the [F5 Support Portal](https://support.f5.com). \ No newline at end of file diff --git a/content/nms/acm/how-to/install-acm.md b/content/nms/acm/how-to/install-acm.md index 9a83bd09c..04b9b9e84 100644 --- a/content/nms/acm/how-to/install-acm.md +++ b/content/nms/acm/how-to/install-acm.md @@ -155,10 +155,6 @@ Complete the following steps for each data plane instance you want to use with A - [Install the Developer Portal]({{< relref "/nms/acm/how-to/devportals/installation/install-dev-portal.md" >}}) -### Install Other NGINX Management Suite Modules - -- [Install Security Monitoring]({{< relref "/nim/monitoring/security-monitoring/install-security-monitoring.md" >}}) - ### Get Started with API Connectivity Manager - [Create Workspaces and Environments for your API Infrastructure]({{< relref "/nms/acm/how-to/infrastructure/manage-api-infrastructure.md" >}}) diff --git a/content/nms/acm/how-to/policies/advanced-security.md b/content/nms/acm/how-to/policies/advanced-security.md index f87ac5445..648519470 100644 --- a/content/nms/acm/how-to/policies/advanced-security.md +++ b/content/nms/acm/how-to/policies/advanced-security.md @@ -40,7 +40,6 @@ To complete the steps in this guide, you need the following: - You have one or more [Environments with an API Gateway]({{< relref "/nms/acm/getting-started/add-api-gateway" >}}). - You have [published one or more API Gateways]({{< relref "/nms/acm/getting-started/publish-api-proxy" >}}). - You have [installed and set up NGINX App Protect]({{< relref "/nap-waf/v4/admin-guide/install-nms" >}}). -- NGINX Management Suite Security Monitoring is [installed]({{< relref "/nim/monitoring/security-monitoring/install-security-monitoring.md" >}}) and running. --- diff --git a/static/scripts/docker-compose/docker-compose.yaml b/static/scripts/docker-compose/docker-compose.yaml index 130193bc7..dcd6b2b99 100644 --- a/static/scripts/docker-compose/docker-compose.yaml +++ b/static/scripts/docker-compose/docker-compose.yaml @@ -14,7 +14,7 @@ secrets: # file: ./certs/nim_ca.pem services: nim: - image: private-registry.nginx.com/nms/nim-standalone-compose:2.18.0 + image: private-registry.nginx.com/nms/nim-standalone-compose:2.19.0 depends_on: clickhouse: condition: service_healthy @@ -26,6 +26,7 @@ services: - clickhouse volumes: - nim-data:/data + - proxy-certs:/usr/local/share/ca-certificates # Uncomment to set custom service limits #deploy: # resources: @@ -62,6 +63,23 @@ services: NIM_WATCHDOG_TIMEOUT: "60" # set the NIM license mode of operation to either connected or disconnected. Default is connected. NIM_LICENSE_MODE_OF_OPERATION: "connected" + # Enable this setting to use proxy + PROXY_ENABLE: false + # Configure this setting to set the host of the proxy server to be used + PROXY_HOST: "" + # Configure this setting to set the protocol of the proxy server to be used - http/https (default - http) + PROXY_PROTOCOL: "http" + # Configure this setting to set the port of the proxy server to be used + PROXY_PORT: 3128 + # Enable this setting to use basic auth for proxy + PROXY_AUTH_REQUIRED: false + # Configure this setting to set the user name in basic auth (proxy_auth_required: true) + PROXY_AUTH_USERNAME: "" + # Configure this setting to set the password in basic auth (proxy_auth_required: true) + # Recommended to use .env file for the password + # PROXY_PASSWORD: "" + # Configure this setting to set the proxy connection verification (is the proxy trusted by the host) + PROXY_SSL_VERIFY: true clickhouse: image: clickhouse/clickhouse-server:23-alpine hostname: clickhouse @@ -107,8 +125,10 @@ networks: driver: bridge internal: true volumes: - # By default docker compose will create a named volume - # Refer to https://docs.docker.com/reference/compose-file/volumes/ for additional storage options such as nfs + # By default docker compose will create a named volume + # Refer to https://docs.docker.com/reference/compose-file/volumes/ for additional storage options such as nfs + proxy-certs: + driver: local nim-data: driver: local #driver_opts: