diff --git a/.style-guide b/.style-guide new file mode 160000 index 0000000000..76a6bdc546 --- /dev/null +++ b/.style-guide @@ -0,0 +1 @@ +Subproject commit 76a6bdc54632a806f07aad9b3be382ff16d00cc8 diff --git a/content/includes/nim/rbac/assign-roles-to-user-groups.md b/content/includes/nim/rbac/assign-roles-to-user-groups.md index a8c62d0412..47cc1b1ae0 100644 --- a/content/includes/nim/rbac/assign-roles-to-user-groups.md +++ b/content/includes/nim/rbac/assign-roles-to-user-groups.md @@ -6,7 +6,7 @@ nd-files: - content/nim/security-monitoring/give-access-to-security-monitoring-dashboards.md --- -{{< call-out "important" "User groups require an OIDC identity provider" >}}User groups require an external identity provider configured for OpenID Connect (OIDC) authentication, as described in [Getting started with OIDC]({{< ref "/nim/admin-guide/authentication/oidc/getting-started.md" >}}). Users from an external identity provider cannot be assigned roles directly in NGINX Instance Manager. Instead, they inherit roles based on their group membership.{{< /call-out >}} +{{< call-out "important" "User groups require an OIDC identity provider" >}}User groups require an external identity provider set up for OpenID Connect (OIDC) authentication, as described in [Getting started with OIDC]({{< ref "/nim/admin-guide/authentication/oidc/getting-started.md" >}}). You can't assign roles directly to users from an external identity provider in NGINX Instance Manager. Instead, they inherit roles based on their group membership.{{< /call-out >}} To assign roles to a user group, follow these steps: @@ -14,5 +14,5 @@ To assign roles to a user group, follow these steps: 2. Select the **Settings** gear icon in the upper-right corner. 3. From the left navigation menu, select **User Groups**. 4. Select a user group from the list, then select **Edit**. -5. In the **Roles** list, choose the role(s) you want to assign to the group. +5. In the **Roles** list, select the role(s) you want to assign to the group. 6. Select **Save**. diff --git a/content/includes/nim/rbac/assign-roles-to-users.md b/content/includes/nim/rbac/assign-roles-to-users.md index ba21abeaf0..1f3ac3c671 100644 --- a/content/includes/nim/rbac/assign-roles-to-users.md +++ b/content/includes/nim/rbac/assign-roles-to-users.md @@ -12,5 +12,5 @@ To assign roles to a user in NGINX Instance Manager, follow these steps: 2. Select the **Settings** gear icon in the upper-right corner. 3. From the left navigation menu, select **Users**. 4. Select a user from the list, then select **Edit User**. -5. In the **Roles** list, choose the role(s) you want to assign to the user. +5. In the **Roles** list, select the role(s) you want to assign to the user. 6. Select **Save**. diff --git a/content/includes/nim/rbac/create-roles.md b/content/includes/nim/rbac/create-roles.md index 92c11690cc..40420f6130 100644 --- a/content/includes/nim/rbac/create-roles.md +++ b/content/includes/nim/rbac/create-roles.md @@ -11,7 +11,7 @@ nd-files: Roles in NGINX Instance Manager are a critical part of [role-based access control (RBAC)]({{< ref "/nim/admin-guide/rbac/overview-rbac.md" >}}). By creating roles, you define the access levels and permissions for different user groups that correspond to groups in your Identity Provider (IdP). -NGINX Instance Manager comes pre-configured with an administrator role called `admin`. Additional roles can be created as needed. +NGINX Instance Manager includes a built-in administrator role called `admin`. You can create additional roles as needed. The `admin` user or any user with `CREATE` permission for the **User Management** feature can create a role. @@ -30,10 +30,10 @@ Follow these steps to create a role and set its permissions: 1. To add permissions: 1. Select **Add Permission**. - 2. Choose the NGINX Instance Manager module you're creating the permission for from the **Module** list. - 3. Select the feature you're granting permission for from the **Feature** list. To learn more about features, refer to [Get started with RBAC]({{< ref "/nim/admin-guide/rbac/overview-rbac.md" >}}). + 2. Select the NGINX Instance Manager module you're creating the permission for from the **Module** list. + 3. Select the feature you're granting permission for from the **Feature** list. To learn more about features, see [Get started with RBAC]({{< ref "/nim/admin-guide/rbac/overview-rbac.md" >}}). 4. Select **Add Additional Access** to choose a CRUD (Create, Read, Update, Delete) access level. - - Choose the access level(s) you want to grant from the **Access** list. + - Select the access level(s) you want to grant from the **Access** list. 5. Select **Save**. 1. Repeat step 6 if you need to add more permissions for other features. @@ -41,4 +41,4 @@ Follow these steps to create a role and set its permissions: #### Example scenario -Suppose you need to create an "app-developer" role. This role allows users to create and edit applications but not delete them or perform administrative tasks. You would name the role `app-developer`, select the relevant features, and grant permissions that align with the application development process while restricting administrative functions. +Suppose you need to create an "app-developer" role. With this role, users can create and edit applications but not delete them or do administrative tasks. Name the role `app-developer`, select the relevant features, and grant permissions that align with the application development process while restricting administrative functions. diff --git a/content/includes/nim/support/how-to-get-support.md b/content/includes/nim/support/how-to-get-support.md index 17606a8372..c26739e655 100644 --- a/content/includes/nim/support/how-to-get-support.md +++ b/content/includes/nim/support/how-to-get-support.md @@ -6,7 +6,7 @@ nd-files: - content/nim/troubleshooting.md --- -If you need additional assistance, refer to the following topics for guidance on how to contact Support and create a Support Package: +If you need more help, see the following topics: - [Contact Support]({{< ref "/nim/support/contact-support.md" >}}) - [Create a Support Package]({{< ref "/nim/support/support-package.md" >}}) diff --git a/content/includes/nim/waf/upload-cert-and-key.md b/content/includes/nim/waf/upload-cert-and-key.md index e08a5e21ab..9d2e1d1187 100644 --- a/content/includes/nim/waf/upload-cert-and-key.md +++ b/content/includes/nim/waf/upload-cert-and-key.md @@ -33,7 +33,7 @@ Follow these steps to get and upload the certificate and key: 1. Upload the file to NGINX Instance Manager using the REST API: ```shell - curl -X POST 'https://{{NIM_FQDN}}/api/platform/v1/certs' --header "Authorization: Bearer " --header "Content-Type: application/json" -d @nginx-repo-certs.json + curl -X POST 'https:///api/platform/v1/certs' --header "Authorization: Bearer " --header "Content-Type: application/json" -d @nginx-repo-certs.json ``` 1. If successful, you’ll see a response similar to this: diff --git a/content/nim/admin-guide/report-usage-connected-deployment.md b/content/nim/admin-guide/report-usage-connected-deployment.md index e19983fa14..d5b12eafe2 100644 --- a/content/nim/admin-guide/report-usage-connected-deployment.md +++ b/content/nim/admin-guide/report-usage-connected-deployment.md @@ -31,6 +31,17 @@ Before submitting usage data to F5, first ensure that the appropriate network po ### Configure network ports for reporting usage + +#### NGINX Instance Manager 2.22 and later + +To allow NGINX Instance Manager to report usage data to F5, make sure port 443 is open for this URL: `https://product.connect.nginx.com/api/nginx-usage/batch` + +{{< call-out "important" >}} + There is no [Manual reporting]({{< ref "/nim/admin-guide/report-usage-connected-deployment.md#manual-reporting" >}}) option for connected mode in NGINX Instance Manager 2.22 and later versions (The "licensing page", "Enable Continuous Connection" toggle and "Send Usage to F5" button are not available). + {{< /call-out >}} + +#### NGINX Instance Manager 2.21 and earlier + To allow NGINX Instance Manager to report usage data to F5, make sure port `443` is open for these URLs: - `https://product.apis.f5.com/` diff --git a/content/nim/disconnected/report-usage-disconnected-deployment.md b/content/nim/disconnected/report-usage-disconnected-deployment.md index 69d4d1b54e..4c27d04bd5 100644 --- a/content/nim/disconnected/report-usage-disconnected-deployment.md +++ b/content/nim/disconnected/report-usage-disconnected-deployment.md @@ -30,13 +30,99 @@ To configure NGINX Plus (R33 and later) to report usage data to NGINX Instance M --- -## Submit usage report to F5 {#submit-usage-report} +## Submit usage report to F5 with NGINX Instance Manager 2.22 and later {#submit-usage-report} + +{{< call-out "note" >}}Starting with NGINX Instance Manager 2.22, it's not possible to report usage with the REST API option.{{< /call-out >}} + +{{}} + +{{%tab name="bash script (recommended)"%}} + +To submit the usage report in a disconnected environment, use the provided `offline_usage.sh` script. Run this script on a system that can access NGINX Instance Manager and connect to the `https://product.connect.nginx.com/api/nginx-usage/batch` endpoint on port `443`. Replace each placeholder with your specific values. + +Download the {{}}[offline_usage.sh](/scripts/offline_usage.sh) script and make the script executable: + +```shell + chmod +x /offline_usage.sh +``` + +### Download usage report + +The download feature of the script takes the following arguments: +- ``: The admin username for NGINX Instance Manager authentication. +- ``: The admin password for NGINX Instance Manager authentication. +- ``: The IP address of the NGINX Instance Manager instance. + +And uses the following environment variable: + +| Variable | Description | Default value | +| --- | --- | --- | +| CURL_TIMEOUT | 30 | Connection timeout for curl requests in seconds | + +To download the usage report from NGINX Instance Manager, run the following command: + +```shell +./offline_usage.sh download +``` +1. The script verifies connectivity to the NGINX Instance Manager instance over HTTPS. +1. Checks that the device is in DISCONNECTED mode (exits with an error if mode is CONNECTED). +1. Downloads the usage report as a ZIP file to `/tmp/response.zip`. + +### Upload usage report + +To upload the usage acknowledgment to NGINX One Console, run the following command: + +```shell +./offline_usage.sh upload --result-dir [--endpoint-url ] +``` +Where: + +| Argument | Description | Required | +| --- | --- | --- | +| `` | The path to the usage acknowledgment ZIP file downloaded using the `download` operation. | Yes | +| --result-dir, -r | Directory used to track uploaded files and store unzipped contents. | Yes | +| --endpoint-url, -e | Upload endpoint URL. Default: https://product.connect.nginx.com/api/nginx-usage/batch | No | + +The script provides the following output: + +| File | Description | +| --- | --- | +| `/uploaded_filex.txt` | A text file containing the names of the succesfully uploaded files. | +| `/unzip/` | Extracted contents of the usage report | +| `/upload_usage.log` | Detailed log of all upload attempts (in CWD) | + +And returns one the following exit codes: + +| Code | Description | +| --- | --- | +| 0 | Operation completed successfully | +| 1 | Error — missing arguments, connectivity failure, invalid file, wrong device mode, or upload failure | + +{{%/tab%}} + +{{%tab name="Web interface"%}} + +Download usage report from the `https:///ui/nginx-plus` page. Replace `` with your NGINX Instance Manager's fully qualified domain name. + +Move the file to a machine with internet access, run the bash script with upload option. + +{{< call-out "note" "Behavior change" >}}Starting with NGINX Instance Manager 2.22, it's not necessary to reupload the usage acknowledgement file back to NGINX Instance Manager.{{< /call-out >}} + +{{%/tab%}} + +{{}} + +{{< call-out "note" "File size increase" >}}NGINX Instance Manager 2.22 and later have moved from reporting aggregated usage data to reporting the raw data that data planes send; the file sizes will be larger than before.{{< /call-out >}} + +--- + +## Submit usage report to F5 with NGINX Instance Manager 2.21 and earlier {#submit-usage-report-2.21} {{< call-out "tip" "Using the REST API" "" >}}{{< include "nim/how-to-access-nim-api.md" >}}{{}}
-{{}} +{{}} {{%tab name="bash script (recommended)"%}} diff --git a/content/nim/security-monitoring/give-access-to-security-monitoring-dashboards.md b/content/nim/security-monitoring/give-access-to-security-monitoring-dashboards.md index 86b9b8a985..4d7679c7ab 100644 --- a/content/nim/security-monitoring/give-access-to-security-monitoring-dashboards.md +++ b/content/nim/security-monitoring/give-access-to-security-monitoring-dashboards.md @@ -9,7 +9,7 @@ nd-docs: DOCS-1026 ## Overview -F5 NGINX Security Monitoring tracks activity on F5 WAF for NGINX instances. The dashboards and logs show insights, detect threats, and help improve security policies. +Security Monitoring tracks activity on F5 WAF for NGINX 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. @@ -21,7 +21,7 @@ This guide follows the principle of least privilege, so users only get access to ## Before you begin -Make sure you complete these steps: +Make sure you have the following: - Your account must have access to User Management in NGINX Instance Manager. Minimum permissions are: @@ -29,14 +29,14 @@ Make sure you complete these steps: - **Feature**: User Management - **Access**: `READ`, `CREATE`, `UPDATE` -- Use the table below to find the permissions you need: +- Use the following table 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.

{{< icon "lightbulb" >}} Best for "super-users" who manage dashboard access. Does not allow deleting accounts. | + | Instance Manager
Security Monitoring
Settings | Analytics
Security Monitoring
User Management | `READ`
`READ`
`CREATE`, `READ`, `UPDATE` | Users can view dashboards and manage accounts and roles.

{{< icon "lightbulb" >}} Best for "super-users" who manage dashboard access. Doesn't allow deleting accounts. | {{}} diff --git a/content/nim/security-monitoring/set-up-app-protect-instances.md b/content/nim/security-monitoring/set-up-app-protect-instances.md index 3617671ca2..5caa042b55 100644 --- a/content/nim/security-monitoring/set-up-app-protect-instances.md +++ b/content/nim/security-monitoring/set-up-app-protect-instances.md @@ -9,32 +9,32 @@ nd-docs: DOCS-1107 ## Overview -F5 NGINX Security Monitoring supports two main use cases: +Security Monitoring supports two main use cases: -- **Security Monitoring only**: Use only the Security Monitoring module to monitor data from F5 WAF for NGINX instances. You will be able to review the security dashboards to assess potential threats and identify opportunities to fine-tune your policies. Your F5 WAF for NGINX 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 F5 WAF for NGINX configurations and security policies in a single location and push pre-compiled updates to an instance or instance group. +- **Security Monitoring only**: Use only the Security Monitoring module to monitor data from F5 WAF for NGINX instances. You can review the security dashboards to assess potential threats and find opportunities to fine-tune your policies. You manage your F5 WAF for NGINX configurations outside of NGINX Instance Manager. +- **Security Monitoring and NGINX Instance Manager**: Use the Security Monitoring module with NGINX Instance Manager. In addition to monitoring your application security, you can manage your F5 WAF for NGINX configurations and security policies in one place and push precompiled updates to an instance or instance group. ## Before you begin -Complete the following prerequisites before proceeding with the steps in this guide. +Make sure you've completed the following before you start. -1. If you are new to F5 WAF for NGINX, follow the instructions in the installation and configuration guides to get up and running: +1. If you're new to F5 WAF for NGINX, follow the installation and configuration guides: - - [Install F5 WAF for NGINX]({{< ref "/waf/install/" >}}) on one or more data plane instances. Each data plane instance must have connectivity to the NGINX Instance Manager host. - - [Configure F5 WAF for NGINX]({{< ref "/waf/policies/configuration.md" >}}) according to your needs on each of the data plane instance. + - [Install F5 WAF for NGINX]({{< ref "/waf/install/" >}}) on one or more data plane instances. Each instance must be able to reach the NGINX Instance Manager host. + - [Configure F5 WAF for NGINX]({{< ref "/waf/policies/configuration.md" >}}) to fit your needs on each data plane instance. 1. Determine your use case: **Security Monitoring only** or **Security Monitoring and Configuration Management**. 1. [Upload your license]({{< ref "/nim/admin-guide/add-license.md" >}}). ## Install NGINX Agent -NGINX Agent is a companion daemon for NGINX Open Source or NGINX Plus instance that provides: +NGINX Agent is a companion daemon for your NGINX Open Source or NGINX Plus instance. It 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 F5 WAF for NGINX 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.** +Repeat these steps on each F5 WAF for NGINX data plane host to install and configure NGINX Agent for Security Monitoring. **These settings apply to both 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. @@ -108,7 +108,7 @@ Repeat the steps in this section on each F5 WAF for NGINX data plane host to ins ``` {{< call-out "important" >}}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 F5 WAF for NGINX 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.{{< /call-out >}} + Use the same values when you configure logging for the Security Monitoring module. If the `syslog:` configuration doesn't match these settings, the monitoring dashboards won't show any data. F5 WAF for NGINX Version 5 networking changes don't support `127.0.0.1` as a syslog server address. For Version 5, use the `docker0` interface address (typically `192.0.10.1`) or the data plane host IP address instead.{{< /call-out >}} {{< call-out "note" >}}You can use the NGINX Agent installation script to add the fields for `nginx_app_protect` and `nap_monitoring`: @@ -135,17 +135,17 @@ 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. +Complete the steps in this section if you're only using the Security Monitoring module to monitor your application security. In this use case, you're **not** using NGINX Instance Manager to manage your WAF security policies. -Repeat the steps below on each F5 WAF for NGINX data plane instance. +Repeat these steps on each F5 WAF for NGINX 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. +1. Create a log format definition file named `/etc/app_protect/conf/log_sm.json` with the following contents. 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`. + This sets the maximum request payload to 2048 bytes and the maximum message size to 5k. Messages larger than 5k are truncated. +2. Add character escaping so the `,` separator is escaped with its standard URL encoding `%2C`. ``` json { @@ -168,15 +168,15 @@ Repeat the steps below on each F5 WAF for NGINX data plane instance. } ``` -1. Find the context in your NGINX configuration where F5 WAF for NGINX 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. +1. Find the context in your NGINX configuration where F5 WAF for NGINX logging is turned on. + In the same context, add the following `app_protect_security_log` directive to configure attack data logging for 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; ``` - {{< call-out "important" >}}The `syslog:server=:` must match the `syslog_ip` and `syslog_port` values specified in the [NGINX Agent configuration file](#install-nginx-agent). The dashboards won't display any data if these settings don't match. Also, the networking changes for F5 WAF for NGINX 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.{{< /call-out >}} + {{< call-out "important" >}}The `syslog:server=:` must match the `syslog_ip` and `syslog_port` values in the [NGINX Agent configuration file](#install-nginx-agent). The dashboards won't show any data if these settings don't match. F5 WAF for NGINX Version 5 networking changes don't support `127.0.0.1` as a syslog server address. For Version 5, use the `docker0` interface address (typically `192.0.10.1`) or the data plane host IP address instead.{{< /call-out >}} 1. Restart NGINX Agent and the NGINX web server. @@ -185,18 +185,18 @@ Repeat the steps below on each F5 WAF for NGINX data plane instance. sudo systemctl restart nginx ``` -You should now be able to view data from your F5 WAF for NGINX instances in the NGINX Security Monitoring dashboards. +You can now view data from your F5 WAF for NGINX instances in the Security Monitoring dashboards. -## Create instances for Security Monitoring with Instance Manager +## Create instances for Security Monitoring with NGINX 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 F5 WAF for NGINX configurations and security policies. +Complete the steps in this section if you want to use the Security Monitoring module **and** NGINX Instance Manager. In this use case, you'll use NGINX Instance Manager to monitor threats and manage your F5 WAF for NGINX configurations and security policies. -Take the steps below to update your F5 WAF for NGINX configurations by using Instance Manager. +Follow these steps to update your F5 WAF for NGINX configurations with NGINX 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 F5 WAF for NGINX logs required by the Security Monitoring dashboards. An example configuration is provided below. +1. Select **Edit Config** from the **Actions** menu for the instance or instance group you want to update. +1. Edit the configuration file. Add directives that reference the security policy bundle and turn on the F5 WAF for NGINX logs that the Security Monitoring dashboards need. ```nginx app_protect_enable on; @@ -207,21 +207,21 @@ Take the steps below to update your F5 WAF for NGINX configurations by using Ins - 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 F5 WAF for NGINX 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 policies and log profiles. In this case, the file path referenced in the NGINX configuration must reside on the Instance. + When you use NGINX Instance Manager for precompiled publication, the policy reference must use the `.tgz` file extension. The file path must exist on the NGINX Instance Manager host, but the policy file doesn't need to exist yet. If your instance isn't set up for precompiled publication, use the `.json` file extension for policies and log profiles. In this case, the file path in the NGINX configuration must exist 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 F5 WAF for NGINX Configuration Management]({{< ref "/nim/waf-integration/configuration/manage-waf-configurations" >}}) to add your custom security policy files to NGINX Instance Manager and update your NGINX configuration. + If you're using custom security policies, you can use the default policy from the example for now. After you finish this guide, see [Set Up F5 WAF for NGINX Configuration Management]({{< ref "/nim/waf-integration/configuration/manage-waf-configurations" >}}) 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 F5 WAF for NGINX is enabled and you want to be able to review attack data. + - Add the `app_protect_security_log_enable on` and `app_protect_security_log` directives to any NGINX context where F5 WAF for NGINX is on and you want 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. - {{< call-out "important" >}}The `syslog:server=:` must match the `syslog_ip` and `syslog_port` values specified in the [NGINX Agent configuration file](#install-nginx-agent). The Security Monitoring dashboards won't display any data if these settings don't match. Also, the networking changes for F5 WAF for NGINX 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.{{< /call-out >}} + {{< call-out "important" >}}The `syslog:server=:` must match the `syslog_ip` and `syslog_port` values in the [NGINX Agent configuration file](#install-nginx-agent). The Security Monitoring dashboards won't show any data if these settings don't match. F5 WAF for NGINX Version 5 networking changes don't support `127.0.0.1` as a syslog server address. For Version 5, use the `docker0` interface address (typically `192.0.10.1`) or the data plane host IP address instead.{{< /call-out >}} -1. Select **Publish** to immediately push the configuration file updates out to your NGINX instance or instance group. +1. Select **Publish** to push the configuration updates to your instance or instance group. -You should now be able to view data from your F5 WAF for NGINX instances in the Security Monitoring dashboard. +You can now view data from your F5 WAF for NGINX instances in the Security Monitoring dashboard. ## See also diff --git a/content/nim/security-monitoring/troubleshooting.md b/content/nim/security-monitoring/troubleshooting.md index 2bc929ac20..1269321e98 100644 --- a/content/nim/security-monitoring/troubleshooting.md +++ b/content/nim/security-monitoring/troubleshooting.md @@ -11,11 +11,11 @@ nd-docs: DOCS-1226 ### Description -If a Security Violation event is not received by the Security Monitoring module, the attack data is lost. +If the Security Monitoring module doesn't receive a security violation event, the attack data is lost. ### Resolution -F5 WAF for NGINX 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: +F5 WAF for NGINX supports logging to multiple destinations. You can send logs to NGINX Agent and keep a backup. If Security Monitoring doesn't receive security events, check the backup log to verify attack details. Use the following settings to turn on backup logging: 1. **For an instance with Security Monitoring only:** diff --git a/content/nim/security-monitoring/update-geo-db.md b/content/nim/security-monitoring/update-geo-db.md index e6c79b5d07..3e44ad8ea0 100644 --- a/content/nim/security-monitoring/update-geo-db.md +++ b/content/nim/security-monitoring/update-geo-db.md @@ -9,17 +9,17 @@ nd-docs: DOCS-1108 ## Overview -The F5 NGINX Security Monitoring module tracks security violations on F5 WAF for NGINX instances. It uses MaxMind's GeoLite2 Free Database to provide geolocation data in analytics dashboards. +The Security Monitoring module tracks security violations on F5 WAF for NGINX 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. +Follow these steps to update the Security Monitoring module with the latest geolocation database so your dashboards show accurate geolocation data. --- ## Before you begin -Ensure the following prerequisites are met: +Make sure you have the following: -- F5 WAF for NGINX is configured, and the Security Monitoring dashboard is collecting security violations. +- F5 WAF for NGINX is set up, and the Security Monitoring dashboard is collecting security violations. --- @@ -27,8 +27,8 @@ Ensure the following prerequisites are met: 1. Create a [MaxMind](https://dev.maxmind.com/geoip/geolite2-free-geolocation-data/) account and subscribe to receive updates for the GeoLite2 database. 1. 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. -1. Extract the `.gzip` file to access the GeoLite2 Country database file, named `GeoLite2-Country.mmdb`. -1. 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: +1. Extract the `.gzip` file to get the GeoLite2 Country database file, `GeoLite2-Country.mmdb`. +1. Copy the new `GeoLite2-Country.mmdb` file to `/usr/share/nms/geolite2/GeoLite2-Country.mmdb` on the NGINX Instance Manager control plane, replacing the existing file: ```shell sudo scp /path/to/GeoLite2-Country.mmdb {user}@{host}:/usr/share/nms/geolite2/GeoLite2-Country.mmdb diff --git a/content/nim/security-monitoring/update-signatures.md b/content/nim/security-monitoring/update-signatures.md index fc0a97e860..237e7b5e11 100644 --- a/content/nim/security-monitoring/update-signatures.md +++ b/content/nim/security-monitoring/update-signatures.md @@ -7,19 +7,19 @@ nd-product: NIMNGR nd-docs: DOCS-1109 --- -The F5 NGINX Security Monitoring module tracks security violations on F5 WAF for NGINX instances. Its analytics dashboards use a Signature Database to provide details about Attack Signatures, including their name, accuracy, and risk. +The Security Monitoring module tracks security violations on F5 WAF for NGINX instances. Its analytics dashboards use a Signature Database to show details about Attack Signatures, including their name, accuracy, and risk. -If the Signature Database is outdated and doesn’t match the version used in F5 WAF for NGINX, new signatures may appear without attributes like a name, risk, or accuracy. +If the Signature Database is outdated and doesn't match the version used in F5 WAF for NGINX, 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. +Follow these steps to update the Security Monitoring module with the latest Attack Signature data so the dashboards show complete and accurate information. --- ## Before you begin -Ensure the following prerequisites are met: +Make sure you have the following: -- [F5 WAF for NGINX is configured]({{< ref "/nim/waf-integration/configuration/_index.md" >}}), and the Security Monitoring dashboard is collecting security violations. +- [F5 WAF for NGINX is set up]({{< ref "/nim/waf-integration/configuration/_index.md" >}}), and the Security Monitoring dashboard is collecting security violations. --- diff --git a/content/nim/waf-integration/configuration/setup-signatures-and-threats/manual-update.md b/content/nim/waf-integration/configuration/setup-signatures-and-threats/manual-update.md index 08ae1fb6c3..f46ae76409 100644 --- a/content/nim/waf-integration/configuration/setup-signatures-and-threats/manual-update.md +++ b/content/nim/waf-integration/configuration/setup-signatures-and-threats/manual-update.md @@ -139,7 +139,7 @@ Use the NGINX Instance Manager REST API to upload the `.tgz` files. **Upload attack signatures** ```shell -curl -X POST 'https://{{NIM_FQDN}}/api/platform/v1/security/attack-signatures' \ +curl -X POST 'https:///api/platform/v1/security/attack-signatures' \ --header "Authorization: Bearer " \ --form 'revisionTimestamp="2022.11.16"' \ --form 'filename=@"/attack-signatures.tgz"' @@ -148,7 +148,7 @@ curl -X POST 'https://{{NIM_FQDN}}/api/platform/v1/security/attack-signatures' \ **Upload bot signatures** ```shell -curl -X POST 'https://{{NIM_FQDN}}/api/platform/v1/security/bot-signatures' \ +curl -X POST 'https:///api/platform/v1/security/bot-signatures' \ --header "Authorization: Bearer " \ --form 'revisionTimestamp="2025.07.09"' \ --form 'filename=@"/bot-signatures.tgz"' @@ -157,7 +157,7 @@ curl -X POST 'https://{{NIM_FQDN}}/api/platform/v1/security/bot-signatures' \ **Upload threat campaigns** ```shell -curl -X POST 'https://{{NIM_FQDN}}/api/platform/v1/security/threat-campaigns' \ +curl -X POST 'https:///api/platform/v1/security/threat-campaigns' \ --header "Authorization: Bearer " \ --form 'revisionTimestamp="2022.11.15"' \ --form 'filename=@"/threat-campaigns.tgz"' diff --git a/content/nim/waf-integration/policies-and-logs/bundles/create-bundle.md b/content/nim/waf-integration/policies-and-logs/bundles/create-bundle.md index 8b2da5e26f..c6731b777b 100644 --- a/content/nim/waf-integration/policies-and-logs/bundles/create-bundle.md +++ b/content/nim/waf-integration/policies-and-logs/bundles/create-bundle.md @@ -61,7 +61,7 @@ If you don’t include `attackSignatureVersionDateTime`, `botSignatureVersionDat Example: ```shell -curl -X POST https://{{NIM_FQDN}}/api/platform/v1/security/policies/bundles \ +curl -X POST https:///api/platform/v1/security/policies/bundles \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d @security-policy-bundles.json diff --git a/content/nim/waf-integration/policies-and-logs/bundles/download-bundle.md b/content/nim/waf-integration/policies-and-logs/bundles/download-bundle.md index 7ad65d5eac..883b257747 100644 --- a/content/nim/waf-integration/policies-and-logs/bundles/download-bundle.md +++ b/content/nim/waf-integration/policies-and-logs/bundles/download-bundle.md @@ -37,7 +37,7 @@ You must have `"READ"` permission for the bundle to retrieve it. Example: ```shell -curl -X GET https://{{NIM_FQDN}}/api/platform/v1/security/policies//bundles/ \ +curl -X GET https:///api/platform/v1/security/policies//bundles/ \ -H "Authorization: Bearer " ``` @@ -46,7 +46,7 @@ The response includes a `content` field that contains the bundle in base64 forma Example: ```shell -curl -X GET "https://{{NIM_FQDN}}/api/platform/v1/security/policies//bundles/" \ +curl -X GET "https:///api/platform/v1/security/policies//bundles/" \ -H "Authorization: Bearer " | jq -r '.content' | base64 -d > security-policy-bundle.tgz ``` diff --git a/content/nim/waf-integration/policies-and-logs/bundles/list-bundles.md b/content/nim/waf-integration/policies-and-logs/bundles/list-bundles.md index a2df4f7b33..f2cfde10d1 100644 --- a/content/nim/waf-integration/policies-and-logs/bundles/list-bundles.md +++ b/content/nim/waf-integration/policies-and-logs/bundles/list-bundles.md @@ -43,7 +43,7 @@ If no time range is provided, the API defaults to showing bundles modified in th Example: ```shell -curl -X GET https://{{NIM_FQDN}}/api/platform/v1/security/policies/bundles \ +curl -X GET https:///api/platform/v1/security/policies/bundles \ -H "Authorization: Bearer " ``` diff --git a/content/nim/waf-integration/policies-and-logs/log-profiles/compile-log-profile.md b/content/nim/waf-integration/policies-and-logs/log-profiles/compile-log-profile.md new file mode 100644 index 0000000000..e626382426 --- /dev/null +++ b/content/nim/waf-integration/policies-and-logs/log-profiles/compile-log-profile.md @@ -0,0 +1,125 @@ +--- +nd-content-type: how-to +nd-docs: DOCS-000 +nd-product: NIMNGR +title: Compile log profiles (REST API) +description: "Compile an F5 WAF for NGINX security log profile into a deployment bundle using the NGINX Instance Manager REST API." +weight: 300 +toc: true +nd-keywords: "compile log profile, security log profile, WAF, NGINX Instance Manager, NIM, log profile bundle, tgz, REST API, app protect, compiler version, logprofiles, bundles" +nd-summary: > + Compile an existing F5 WAF for NGINX security log profile into a bundle (.tgz) for a specific WAF compiler version using the NGINX Instance Manager REST API. + Compiling a log profile is required before the profile can be deployed to NGINX instances. + The compiled bundle includes a hash and size value that you can use to validate bundle integrity at download time. +nd-audience: operator +--- + +## Overview + +Use this guide to compile an existing F5 WAF for NGINX security log profile into a bundle using the NGINX Instance Manager REST API. Compiling a log profile produces a compressed archive (.tgz) for a specific WAF compiler version. The bundle must be compiled before the log profile can be deployed to NGINX instances. + +The API response includes a hash and size for each bundle. Use these values to validate bundle integrity when you download the bundle. + +--- + +## Before you begin + +Before you begin, make sure you have: + +- **NGINX Instance Manager access**: An account with sufficient permissions to manage WAF log profiles. See [Manage roles and permissions]({{< ref "/nim/admin-guide/rbac/overview-rbac.md" >}}). +- **An existing security log profile**: A log profile already created in NGINX Instance Manager. See [Configure log profiles]({{< ref "/nim/waf-integration/policies-and-logs/log-profiles/configure-log-profile.md" >}}). +- **A REST API client**: A tool such as curl or [Postman](https://www.postman.com/) to send requests to the NGINX Instance Manager REST API. +- **Authentication credentials**: A valid access token or other credentials for the NGINX Instance Manager REST API. See [API overview]({{< ref "/nim//fundamentals/api-overview.md" >}}) for supported authentication methods. + +--- + +## Access the REST API + +The NGINX Instance Manager REST API base URL uses the following format: + +```text +https:///api/[nim|platform]/ +``` + +Replace `` with the fully qualified domain name of your NGINX Instance Manager host and `` with the target API version. All requests require authentication. For details on authentication methods, see the [API overview]({{< ref "/nim//fundamentals/api-overview.md" >}}). + +--- + +## Compile a security log profile bundle + +Send a POST request to the Security Log Profiles API to compile one or more log profiles into bundles. + +| Method | Endpoint | +|--------|----------| +| POST | `/api/platform/v1/security/logprofiles/bundles` | + +### Send the request + +1. Prepare a JSON request body that specifies the log profile name and target compiler version for each bundle you want to compile. + + You can compile multiple log profiles in a single request by adding entries to the `bundles` array. + + + +2. Send the POST request using curl or your preferred API client. + + + curl -X POST https:///api/platform/v1/security/logprofiles/bundles \ + -H "Authorization: Bearer " \ + -d @default-log-example-bundles.json + ``` + + Replace `` with your NGINX Instance Manager hostname and `` with your authentication token. + +3. Review the JSON response to confirm that compilation has started or completed for each log profile. + + ```json + { + "items": [ + { + "compilationStatus": { + "status": "compiling" + }, + "metadata": { + "compilerVersion": "", + "created": "2026-04-08T03:42:33.902171669Z", + "hash": "", + "logProfileName": "", + "logProfileUid": "d974876d-0c70-4bae-b396-692023968cd2", + "modified": "2026-04-08T03:42:33.902171669Z", + "size": 0, + "uid": "0fea39c3-5512-4a4d-83c9-32e95435fd0d" + } + }, + { + "compilationStatus": { + "status": "compiled" + }, + "metadata": { + "compilerVersion": "", + "created": "2026-04-08T03:42:30.424Z", + "hash": "7b669d6b9907162ca45cc1f62e866a8c8aaee875743ab0f68c99e0afcbb1e050", + "logProfileName": "", + "logProfileUid": "858d0ee3-da6a-4b38-a151-51db36ff163d", + "modified": "2026-04-08T03:42:32.379Z", + "size": 1647, + "uid": "63db6f0e-f82c-405c-8b88-dbadeea68190" + } + } + ] + } + ``` + + A `status` of `compiling` means the bundle is still being processed. A `status` of `compiled` means the bundle is ready. For bundles with a `compiled` status, the response includes a `hash` and `size` that you can use to validate integrity when downloading the bundle. + +--- + +## References + +For more information, see: + +- [Configure log profiles]({{< ref "/nim/waf-integration/policies-and-logs/log-profiles/configure-log-profile.md" >}}) +- [Review log profiles]({{< ref "/nim/waf-integration/policies-and-logs/log-profiles/review-log-profile.md" >}}) +- [Deploy log profiles]({{< ref "/nim/waf-integration/policies-and-logs/log-profiles/deploy-log-profile.md" >}}) +- [API overview]({{< ref "/nim//fundamentals/api-overview.md" >}}) +- [Security Logs]({{< ref "/waf/logging/security-logs.md" >}}) \ No newline at end of file diff --git a/content/nim/waf-integration/policies-and-logs/log-profiles/configure-log-profile.md b/content/nim/waf-integration/policies-and-logs/log-profiles/configure-log-profile.md new file mode 100644 index 0000000000..5140c1bdac --- /dev/null +++ b/content/nim/waf-integration/policies-and-logs/log-profiles/configure-log-profile.md @@ -0,0 +1,170 @@ +--- +nd-content-type: how-to +nd-docs: DOCS-000 +nd-product: NIMNGR +title: Configure and deploy log profiles +description: "Configure F5 WAF for NGINX security log profiles in NGINX Instance Manager, controlling request filtering, log format, size limits, and deployment to NGINX instances." +weight: 100 +toc: true +nd-keywords: "log profiles, WAF, NGINX Instance Manager, NIM, security logs, app protect, request logs, traffic logs, Splunk, ArcSight, syslog" +nd-summary: > + Configure log profiles for F5 WAF for NGINX security logs in NGINX Instance Manager. + Log profiles define which HTTP requests are captured, how log messages are formatted, where logs are sent, and what security event details are included. + Log profiles must be compiled into a bundle before deployment to NGINX instances. +nd-audience: operator +--- + +## Overview + +Use this guide to configure log profiles for F5 WAF for NGINX security logs in F5 NGINX Instance Manager. Security logs (also called Request logs or Traffic logs) provide visibility into what F5 WAF for NGINX detects and how F5 WAF for NGINX processes traffic according to your policies. F5 WAF for NGINX uses its own logging mechanism rather than NGINX's default access logging. + +With log profiles, you control: + +- **Filtering**: Which requests are logged (all requests, requests with violations, or blocked requests only) +- **Format**: How log messages are structured (default, custom, Splunk, ArcSight, or BIG-IQ formats) +- **Destination**: Where logs are sent (file or syslog server) +- **Content**: What information is included in each log message (request details, violations, attack signatures, and more) +- **Size limits**: Maximum sizes for log messages and request data + +For detailed information about security logging capabilities and available log attributes, see [Security Logs]({{< ref "/waf/logging/security-logs.md" >}}) and [Security logs examples]({{< ref "/waf/logging/security-logs.md#examples" >}}). + +--- + +## Before you begin + +Before you begin, make sure you have: + +- **F5 NGINX Instance Manager access**: An account with sufficient permissions to create and manage WAF log profiles. See [Manage roles and permissions]({{< ref "/nim/admin-guide/rbac/overview-rbac.md" >}}). +- **F5 WAF for NGINX license**: A valid license with WAF capabilities for your NGINX Instance Manager deployment. +- **NGINX instances**: One or more NGINX instances registered in NGINX Instance Manager. You'll deploy the log profile to these. + +--- + +## Add a log profile + +1. In NGINX Instance Manager, select **WAF** > **Log Profiles**. +1. Select **Add Log Profile**. + The log profile configuration screen opens. +1. In **General Settings**, enter a name and optional description for the log profile. + +Next, configure the filter settings to determine which requests are logged. + +### Configure filter settings + +The **Request Type** filter determines which requests are logged based on what F5 WAF detects: + +- **All**: Logs all requests, both legal and illegal. +- **Illegal**: Logs requests with violations (alerted or blocked). +- **Blocked**: Logs requests with violations that were blocked. + +Select the filter option that matches your monitoring and compliance needs. For production environments, start with **Blocked** to reduce log volume, then expand to **Illegal** or **All** as needed for troubleshooting. + +Next, configure the content format and options for how log messages are structured. + +### Configure content settings + +The content section specifies the format and structure of log messages. + +#### Select a format + +Select one of the following log formats: + +- **Default**: Default format for F5 WAF with comma-separated key-value pairs. +- **GRPC**: Variant of the default format suited for gRPC traffic. +- **User-defined**: Custom format that you define using a format string with placeholders. +- **Splunk**: Formatted for Splunk SIEM with F5 plugin. +- **ArcSight**: Formatted according to ArcSight Common Event Format (CEF) with custom fields adapted for F5. +- **BIG-IQ**: Formatted for BIG-IQ, the F5 centralized management platform for BIG-IP. + +#### Set size limits + +Configure size restrictions for log messages: + +- **Max request size**: Limit in bytes for the `request` and `request_body_base64` fields. The accepted range is 1–10240 bytes, with a default of 2000 bytes. You can also set this to `any`, which is equivalent to 10240 bytes. +- **Max message size**: Total size limit in KB for the entire log message. The accepted range is 1k–64k, with a default of 2k. This value must not be smaller than `max_request_size`. + +#### (Optional) Create a custom format string + +If you select **User-defined** format, create a custom format string using placeholders for log attributes. Each attribute name is delimited by percent signs. For example: + +``` text +Request ID %support_id%: %method% %uri% received on %date_time% from IP %ip_client% had the following violations: %violations% +``` + +Available placeholders include attributes such as `%ip_client%`, `%request%`, `%violations%`, `%attack_type%`, and others. See [Available security log attributes]({{< ref "/waf/logging/security-logs.md#available-security-log-attributes" >}}). + +#### (Optional) Configure advanced formatting options + +Configure additional options for how list values appear in your logs: + +- **List delimiter**: Character or string that separates list elements (default: comma). +- **List prefix**: Character or string that starts a list (default: none). +- **List suffix**: Character or string that ends a list (default: none). +- **Escaping characters**: Replace specific characters in log values with alternative characters. Configure the `from` character to be replaced and the `to` result character. + +For detailed information about the JSON structure of security log configuration files, see [Security log configuration file]({{< ref "/waf/logging/security-logs.md#security-log-configuration-file" >}}). + +--- + +Finally, select **Add Profile** to save the log profile. Next, you can optionally compile the log profile into a bundle before deploying it to your NGINX instances. + +## Compile the log profile + +Before deploying a log profile, you can optionally compile the JSON configuration file into a bundle. If you do not compile manually, the deployment process automatically compiles the log profile. + +The compiled bundle is in compressed tar format (.tgz) and contains all the necessary configuration to enable security logging on your NGINX instances. + +### Manage bundles for different compiler versions + +1. Go to **WAF** > **Log Profiles**. + + A list of all log profiles appears. + +2. In the **Actions** column for a log profile, select one of the following: + + - **Edit**: Open the log profile configuration editor to reconfigure settings. + - **Make a Copy**: Create a new log profile by copying the JSON content. + - **Export as JSON**: Download the log profile JSON configuration. + - **Manage Bundles**: View and manage compiled bundles for different WAF compiler versions. + - **Delete**: Remove the log profile. + +3. Select **Manage Bundles** to view all supported WAF compiler versions. + + For each version, you can see whether the log profile is compiled for that version. + +4. For a specific compiler version, select one of the following: + + - **Compile**: Compile the log profile into a bundle for that compiler version. + - **Download**: Download an existing compiled bundle for that compiler version. + +Use this to maintain compatibility with different versions of F5 WAF across your infrastructure. + +--- + +## Deploy the log profile + +After saving a log profile, deploy it to your NGINX instances to enable logging of WAF security events. See [Deploy log profiles]({{< ref "/nim/waf-integration/policies-and-logs/log-profiles/deploy-log-profile/" >}}) for detailed deployment steps. + +The deployment process configures the required NGINX directives (`app_protect_security_log_enable` and `app_protect_security_log`) and ensures the log profile bundle is accessible to your instances. For detailed information about these directives and their configuration options, see [Security log directives]({{< ref "/waf/logging/security-logs.md#directives-in-nginxconf" >}}). + +For container-specific setup requirements, see the [Log profiles]({{< ref "/nim/waf-integration/overview.md#log-profiles" >}}) configuration section in the overview. + +--- + +## Review and manage log profiles + +From NGINX Instance Manager, you can review the log profiles you've saved. For detailed information about reviewing and managing log profiles, see [Update log profiles]({{< ref "/nim/waf-integration/policies-and-logs/log-profiles/update-log-profile.md" >}}). + +--- + +## References + +For more information, see: + +- [Deploy log profiles]({{< ref "/nginx-one-console/waf-integration/log-profiles/deploy-log-profiles.md" >}}) +- [Update log profiles]({{< ref "/nim/waf-integration/policies-and-logs/log-profiles/update-log-profile.md" >}}) +- [Security Logs]({{< ref "/waf/logging/security-logs.md" >}}) +- [Security log configuration file]({{< ref "/waf/logging/security-logs.md#security-log-configuration-file" >}}) +- [Available security log attributes]({{< ref "/waf/logging/security-logs.md#available-security-log-attributes" >}}) +- [Security log directives]({{< ref "/waf/logging/security-logs.md#directives-in-nginxconf" >}}) +- [Log profiles overview]({{< ref "/nim/waf-integration/overview.md#log-profiles" >}}) \ No newline at end of file diff --git a/content/nim/waf-integration/policies-and-logs/log-profiles/create-log-profile.md b/content/nim/waf-integration/policies-and-logs/log-profiles/create-log-profile.md index 19f1d58045..4365a3ceb7 100644 --- a/content/nim/waf-integration/policies-and-logs/log-profiles/create-log-profile.md +++ b/content/nim/waf-integration/policies-and-logs/log-profiles/create-log-profile.md @@ -1,16 +1,17 @@ --- -title: Create a security log profile +title: Create and deploy profiles (REST API) description: Create and upload a new F5 WAF for NGINX security log profile to NGINX Instance Manager using the REST API. toc: true -weight: 100 +weight: 600 nd-content-type: how-to nd-product: NIMNGR --- + You can create and upload new F5 WAF for NGINX security log profiles using the NGINX Instance Manager REST API. A log profile defines how security events are recorded and exported from your NGINX instances. -To upload a log profile, send a `POST` request to the Security Log Profiles API endpoint. The log profile must be encoded in `base64`; sending plain JSON will cause the request to fail. +To upload a log profile, send a `POST` request to the Security Log Profiles API endpoint. The log profile must be encoded in `base64`; sending plain JSON causes the request to fail. {{< call-out "note" "Access the REST API" >}} {{< include "nim/how-to-access-nim-api.md" >}} @@ -28,7 +29,7 @@ To upload a log profile, send a `POST` request to the Security Log Profiles API Example: ```shell -curl -X POST https://{{NIM_FQDN}}/api/platform/v1/security/logprofiles \ +curl -X POST https:///api/platform/v1/security/logprofiles \ -H "Authorization: Bearer " \ -d @default-log-example.json ``` diff --git a/content/nim/waf-integration/policies-and-logs/log-profiles/delete-log-profile.md b/content/nim/waf-integration/policies-and-logs/log-profiles/delete-log-profile.md index fe6c91de7e..5b3330edcc 100644 --- a/content/nim/waf-integration/policies-and-logs/log-profiles/delete-log-profile.md +++ b/content/nim/waf-integration/policies-and-logs/log-profiles/delete-log-profile.md @@ -1,8 +1,8 @@ --- -title: Delete a security log profile +title: Delete security log profiles (REST API) description: Remove an existing F5 WAF for NGINX security log profile from NGINX Instance Manager using the REST API. toc: true -weight: 300 +weight: 800 nd-content-type: how-to nd-product: NIMNGR --- @@ -23,13 +23,13 @@ To delete a security log profile, send a `DELETE` request to the Security Log Pr 1. Retrieve the UID: ```shell - curl -X GET https://{{NIM_FQDN}}/api/platform/v1/security/logprofiles \ + curl -X GET https:///api/platform/v1/security/logprofiles \ -H "Authorization: Bearer " ``` 2. Send the delete request: ```shell - curl -X DELETE https://{{NIM_FQDN}}/api/platform/v1/security/logprofiles/ \ + curl -X DELETE https:///api/platform/v1/security/logprofiles/ \ -H "Authorization: Bearer " ``` diff --git a/content/nim/waf-integration/policies-and-logs/log-profiles/deploy-log-profile.md b/content/nim/waf-integration/policies-and-logs/log-profiles/deploy-log-profile.md new file mode 100644 index 0000000000..f9b5a25ec6 --- /dev/null +++ b/content/nim/waf-integration/policies-and-logs/log-profiles/deploy-log-profile.md @@ -0,0 +1,109 @@ +--- +nd-content-type: how-to +nd-docs: DOCS-000 +nd-product: NIMNGR +title: Deploy log profiles +description: "Deploy an F5 WAF for NGINX security log profile to NGINX instances or instance groups in NGINX Instance Manager." +weight: 300 +toc: true +nd-keywords: "deploy log profile, security log profile, WAF, NGINX Instance Manager, NIM, app protect, instance groups, log profile bundle, tgz, app_protect_security_log, app_protect_security_log_enable, configuration editor" +nd-summary: > + Deploy a configured F5 WAF for NGINX security log profile to NGINX instances or instance groups in NGINX Instance Manager. + A log profile must be deployed before it can capture security events on your NGINX instances. + If the log profile has not yet been compiled for the target WAF compiler version, NGINX Instance Manager automatically compiles it into a bundle before deployment. +nd-audience: operator +--- + +## Overview + +Use this guide to deploy a security log profile to NGINX instances or instance groups in NGINX Instance Manager. A log profile doesn't capture security events until you deploy it. You can deploy a log profile directly from the Log Profiles screen, or as part of editing the NGINX configuration for an instance or instance group. + +--- + +## Before you begin + +Before you begin, make sure you have: + +- **A configured log profile**: A log profile already created and saved in NGINX Instance Manager. See [Configure a log profile]({{< ref "/nim/waf-integration/policies-and-logs/log-profiles/configure-log-profile.md" >}}). +- **A target instance or instance group**: One or more NGINX instances or instance groups registered in NGINX Instance Manager to deploy the log profile to. +- **NGINX Instance Manager access**: An account with sufficient permissions to deploy WAF log profiles. See [Manage roles and permissions]({{< ref "/nim/admin-guide/rbac/overview-rbac.md" >}}). + +--- + +## Deploy a log profile + +1. In NGINX Instance Manager, select **WAF** > **Log Profiles**. + +2. Select the log profile that you want to deploy. + +3. From **Actions**, select **Deploy**. + + The **Deploy Log Profile** window opens. + +4. Confirm the name of the log profile shown. NGINX Instance Manager defaults to the selected log profile. + +5. In the **Target** section, select **Instance** or **Instance Group**. + +6. In the drop-down menu that appears, select the instance or instance group to deploy to. + +7. Choose how to deploy the log profile: + + - **Add a new log profile path**: Specify a new file path where the log profile bundle should be deployed. + - **Update all log profiles**: Sync all log profiles on the target instance or instance group. This updates all existing log profiles by compiling their latest JSON contents into bundles and deploying them to all existing file paths. + + If the log profile has not already been compiled for the WAF compiler version used by the target instance or instance group, NGINX Instance Manager automatically compiles it into a bundle before deployment. + +--- + +## (Optional) Deploy during configuration editing + +You can also deploy a log profile directly when editing the NGINX configuration for an instance or instance group. Use this method to integrate log profile deployment into your regular configuration workflow. + +1. In NGINX Instance Manager, select **Instances** or **Instance Groups** and select the target instance or instance group. + +1. Select the **Configuration** tab, then select **Edit Configuration**. + +1. Select **Apply security** and select which log profile to deploy. + +1. Copy the code snippet with the required directives and paste it into your NGINX configuration. The snippet includes: + + - `app_protect_security_log_enable on` + - `app_protect_security_log` with the log profile bundle path and destination + + For example: + + ```nginx + app_protect_security_log_enable on; + app_protect_security_log /etc/nginx/log-profile-bundle.tgz syslog:server=localhost:514; + ``` + +8. Select **Save**, then select **Publish**. + +--- + +## Verify log profile deployment + +After deployment, verify that the log profile is active on the target instances or instance groups. + +1. Confirm that the NGINX configuration includes the required directives: + + - `app_protect_security_log_enable on` + - `app_protect_security_log` with the correct log profile bundle path and destination + +2. Check that security logs are being generated at the configured destination (file path or syslog server). + +3. Review the log entries to confirm they match the format and filter settings configured in the log profile. + +To troubleshoot log profile deployment issues, see the [Container-related configuration requirements]({{< ref "/nim/waf-integration/overview.md#container-related-configuration-requirements" >}}) section to ensure volumes and paths are correctly configured. + +--- + +## References + +For more information, see: + +- [Configure a log profile]({{< ref "/nim/waf-integration/policies-and-logs/log-profiles/configure-log-profile.md" >}}) +- [Review log profiles]({{< ref "/nim/waf-integration/policies-and-logs/log-profiles/review-log-profile.md" >}}) +- [Compile a security log profile]({{< ref "/nim/waf-integration/policies-and-logs/log-profiles/compile-log-profile.md" >}}) +- [Security log directives]({{< ref "/waf/logging/security-logs.md#directives-in-nginxconf" >}}) +- [Security Logs]({{< ref "/waf/logging/security-logs.md" >}}) \ No newline at end of file diff --git a/content/nim/waf-integration/policies-and-logs/log-profiles/download-log-profile.md b/content/nim/waf-integration/policies-and-logs/log-profiles/download-log-profile.md new file mode 100644 index 0000000000..6d39aa6dd4 --- /dev/null +++ b/content/nim/waf-integration/policies-and-logs/log-profiles/download-log-profile.md @@ -0,0 +1,101 @@ +--- +nd-content-type: how-to +nd-docs: DOCS-000 +nd-product: NIMNGR +title: Download log profile bundles (REST API) +description: "Download a compiled F5 WAF for NGINX security log profile bundle from NGINX Instance Manager using the REST API." +weight: 500 +toc: true +nd-keywords: "download log profile bundle, security log profile, WAF, NGINX Instance Manager, NIM, log profile bundle, tgz, REST API, app protect, compiler version, logprofiles, bundles, hash, integrity" +nd-summary: > + Download a compiled F5 WAF for NGINX security log profile bundle from NGINX Instance Manager using the REST API. + The downloaded bundle is the compiled output produced by the compile a security log profile API. + The response includes a hash and size that you can use to verify the integrity of the downloaded bundle against the values returned at compile time. +nd-audience: operator +--- + +## Overview + +Use this guide to download a compiled F5 WAF for NGINX security log profile bundle from NGINX Instance Manager using the REST API. The bundle is the compiled output produced by the [compile a security log profile]({{< ref "/nim/waf-integration/policies-and-logs/log-profiles/compile-log-profile.md" >}}) API. + +The response includes a `hash` and `size` for the downloaded bundle. Verify these values against the `hash` and `size` returned when the bundle was compiled to confirm the integrity of the download. + +--- + +## Before you begin + +Before you begin, make sure you have: + +- **NGINX Instance Manager access**: An account with sufficient permissions to manage WAF log profiles. See [Manage roles and permissions]({{< ref "/nim/admin-guide/rbac/overview-rbac.md" >}}). +- **A compiled log profile bundle**: A log profile that has already been compiled in NGINX Instance Manager. See [Compile a security log profile]({{< ref "/nim/waf-integration/policies-and-logs/log-profiles/compile-log-profile.md" >}}). +- **A REST API client**: A tool such as curl or [Postman](https://www.postman.com/) to send requests to the NGINX Instance Manager REST API. +- **Authentication credentials**: A valid access token or other credentials for the NGINX Instance Manager REST API. See [API overview]({{< ref "/nim/fundamentals/api-overview/" >}}) for supported authentication methods. + +--- + +## Access the REST API + +The NGINX Instance Manager REST API base URL uses the following format: + +```text +https:///api/[nim|platform]/ +``` + +Replace `` with the fully qualified domain name of your NGINX Instance Manager host and `` with the target API version. All requests require authentication. For details on authentication methods, see the [API overview]({{< ref "/nim/fundamentals/api-overview/" >}}). + +--- + +## Download a security log profile bundle + +Send a GET request to the Security Log Profiles API to download a compiled bundle for a specific log profile and compiler version. + +| Method | Endpoint | +|--------|----------| +| GET | `/api/platform/v1/security/logprofiles/{logProfileName}/{compilerVersion}/bundle` | + +### Send the request + +1. Identify the log profile name and compiler version of the bundle you want to download. + + These values correspond to the `logProfileName` and `compilerVersion` fields used when the bundle was compiled. See [Compile a security log profile]({{< ref "/nim/waf-integration/policies-and-logs/log-profiles/compile-log-profile.md" >}}). + +2. Send the GET request using curl or your preferred API client. + + ```sh + curl --location 'https:///api/platform/v1/security/logprofiles///bundle' \ + --header 'Authorization: Bearer ' + ``` + + Replace `` with your NGINX Instance Manager hostname. Replace `` with the name of the log profile. Replace `` with the target WAF compiler version. Replace `` with your authentication token. + +3. Review the JSON response to confirm the download succeeded and to retrieve the bundle content and integrity values. + + ```json + { + "compiledBundle": "H4sIAAAAAAAAB+2bWnQcRRTuabNpQyKLq8TTsEQTNDzb9eR/B1KJQ5hF2EMRiUJc3V1922mmbe7u2mZqGiZQ3od4EHITEx70Ih495BCVePXgISfy5NmEQkHwWU5mdn6zu65lKhyvb9rq6Vmv7r2q8867Xd1FrGRe0Xrtsl7YXBBtgEOpwCKY4uGWWEovQm1jIBt6NqEudkIPIZy7StNalEOUGBQmz5uNJ+tWi+pe1g6VYmNkpBGKXj/u8vyOrJRmwN1PBt6vFIuOZ+W7PC9SlRXuRrN6kyVEpYfCeBPBFoS3hRqRRNDQCfq5SGAxpQ5stkF8Qj3cIhYLvDAlmPs+8WMwsX1F4MNmnoeLpWPm+7JMsyl7v/O63W67vsfs0HNjginkfsJoZYlMEopj5lDeV9pgdmto8rU8ajcvIPEGsmBJ+4JrF3kKbrHum6CRsS7MbrOs9TenPWt9VIisUqY9DsnR67eb2MLPhkW3LO+aRdoVt219vfGkR7UQFJMxHGRyl28uzonkuGvbB/IfMMt/TLDStBgn0j7+5/zfj/8shB9gQhx//tR3iI7/MnBJ/J+5ey+dL8eOP8aOrP87/owHY4y/ycJIbxvHkz9FGOo4LwOPQ/6WhWey4F/Fo2Jd/5fCxcRgoiD2k+D49cgJQ3X9l4HWZmvz8lWReb6m2Y0G2Zg4/6uYz1yh3NuUuQEP/44G……", + "metadata": { + "compilerVersion": "5.575.0", + "created": "2026-03-21T11:17:45.312Z", + "hash": "a3f82c1e6d09b74f5c3a1e8b2d7f0c94e5b6a1d8f2c3e7b0a4d9f1e6c8b2a35", + "logProfileName": "log_profile_01", + "logProfileUid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "modified": "2026-03-21T11:18:02.741Z", + "size": 1823, + "uid": "f0e1d2c3-b4a5-6789-cdef-012345678901" + } + } + ``` + + The `compiledBundle` field contains the base64-encoded bundle content. The `hash` and `size` values in `metadata` should match the values returned when the bundle was compiled. If the values don't match, don't deploy the bundle. Recompile the log profile instead. + +--- + +## References + +For more information, see: + +- [Compile a security log profile]({{< ref "/nim/waf-integration/policies-and-logs/log-profiles/compile-log-profile.md" >}}) +- [Configure log profiles]({{< ref "/nim/waf-integration/policies-and-logs/log-profiles/configure-log-profile.md" >}}) +- [Deploy log profiles]({{< ref "/nim/waf-integration/policies-and-logs/log-profiles/deploy-log-profile.md" >}}) +- [API overview]({{< ref "/nim/fundamentals/api-overview/" >}}) +- [Security Logs]({{< ref "/waf/logging/security-logs.md" >}}) \ No newline at end of file diff --git a/content/nim/waf-integration/policies-and-logs/log-profiles/review-log-profile.md b/content/nim/waf-integration/policies-and-logs/log-profiles/review-log-profile.md new file mode 100644 index 0000000000..a4dab07fa7 --- /dev/null +++ b/content/nim/waf-integration/policies-and-logs/log-profiles/review-log-profile.md @@ -0,0 +1,68 @@ +--- +title: Review log profiles +weight: 400 +toc: true +nd-content-type: how-to +nd-product: NIMNGR +nd-summary: > + Review WAF log profiles in NGINX Instance Manager to inspect configuration details, deployment status, and bundle compilation state. + Manage profiles via Actions to edit, copy, export as JSON, manage bundles, or delete. +nd-keywords: "log profiles, WAF, NGINX Instance Manager, NIM, review log profiles, security logs, app protect, deployment status, bundle compilation, instance groups, manage bundles, export JSON" +nd-audience: operator +--- + +## Overview + +Use this guide to review security log profiles for F5 WAF for NGINX in NGINX Instance Manager. Before you deploy a log profile to an NGINX instance or instance group, you can inspect its configuration, check deployment history, and verify bundle compilation state. + +--- + +## Review F5 WAF for NGINX security log profiles + +1. In NGINX Instance Manager, select **WAF** > **Log Profiles**. + +1. Select the log profile name you want to review. + + The log profile detail view opens with the following tabs: + + - **Details**: Displays log profile information, including: + - Last modified date and time (for example, 1/16/2026, 3:35:25 PM PST) + - Total deployments + - Log profile JSON configuration + + - **Deployments**: Shows deployment details for each instance or instance group, including: + - Compiled version + - Deployment status + - Date deployed + - Whether the latest log profile JSON was deployed + + - **Bundles**: Lists all WAF compiler versions with the following information: + - Compiler version + - Compilation status (Compiled, Not compiled, or Compiling) + - Actions to compile or download the compiled bundle + +--- + +## Modify existing log profiles + +1. In NGINX Instance Manager, select **WAF** > **Log Profiles**. + +2. Identify the log profile you want to modify, then select **Actions**. + +3. From the menu that appears, select one of the following: + + - **Edit**: Opens the log profile configuration editor where you can reconfigure settings. See [Configure log profiles]({{< ref "/nim/waf-integration/policies-and-logs/log-profiles/configure-log-profile.md" >}}) for details. + - **Make a Copy**: Creates a new log profile by copying the JSON content into a new log profile object. Use an existing log profile as a baseline for further customization. + - **Export as JSON**: Downloads the log profile JSON configuration. + - **Manage Bundles**: Opens a view to manage compiled bundles for different WAF compiler versions. + - **Delete**: Removes the log profile. After you confirm, all configuration work on that log profile is permanently lost. + +--- + +## References + +For more information, see: + +- [Configure log profiles]({{< ref "/nim/waf-integration/policies-and-logs/log-profiles/configure-log-profile.md" >}}) +- [Deploy log profiles]({{< ref "/nim/waf-integration/policies-and-logs/log-profiles/deploy-log-profile.md" >}}) +- [Security Logs]({{< ref "/waf/logging/security-logs.md" >}}) \ No newline at end of file diff --git a/content/nim/waf-integration/policies-and-logs/log-profiles/update-log-profile.md b/content/nim/waf-integration/policies-and-logs/log-profiles/update-log-profile.md index 7641a01859..e66c7111bf 100644 --- a/content/nim/waf-integration/policies-and-logs/log-profiles/update-log-profile.md +++ b/content/nim/waf-integration/policies-and-logs/log-profiles/update-log-profile.md @@ -1,8 +1,8 @@ --- -title: Update a security log profile +title: Update log profiles (REST API) description: Update an existing F5 WAF for NGINX security log profile or create a new revision using the NGINX Instance Manager REST API. toc: true -weight: 200 +weight: 700 nd-content-type: how-to nd-product: NIMNGR --- @@ -25,7 +25,7 @@ To update a log profile, use one of the following methods: ### Create a new revision ```shell -curl -X POST https://{{NIM_FQDN}}/api/platform/v1/security/logprofiles?isNewRevision=true \ +curl -X POST https:///api/platform/v1/security/logprofiles?isNewRevision=true \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d @update-default-log.json @@ -38,7 +38,7 @@ To overwrite an existing security log profile: 1. Retrieve the profile’s UID: ```shell - curl -X PUT https://{{NIM_FQDN}}/api/platform/v1/security/logprofiles/ \ + curl -X PUT https:///api/platform/v1/security/logprofiles/ \ -H "Authorization: Bearer " \ -H "Content-Type application/json" \ -d @update-log-profile.json @@ -47,7 +47,7 @@ To overwrite an existing security log profile: 2. Update the log profile using the UID: ```shell - curl -X PUT https://{{NIM_FQDN}}/api/platform/v1/security/logprofiles/ \ + curl -X PUT https:///api/platform/v1/security/logprofiles/ \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d @update-log-profile.json diff --git a/content/nim/waf-integration/policies-and-logs/policies/create-policy.md b/content/nim/waf-integration/policies-and-logs/policies/create-policy.md index 0b6b5bb932..33956ae83f 100644 --- a/content/nim/waf-integration/policies-and-logs/policies/create-policy.md +++ b/content/nim/waf-integration/policies-and-logs/policies/create-policy.md @@ -89,7 +89,7 @@ To create a security policy using the REST API, send a `POST` request to the Sec **Example:** ```shell -curl -X POST https://{{NIM_FQDN}}/api/platform/v1/security/policies \ +curl -X POST https:///api/platform/v1/security/policies \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d @ignore-xss-example.json diff --git a/content/nim/waf-integration/policies-and-logs/policies/delete-policy.md b/content/nim/waf-integration/policies-and-logs/policies/delete-policy.md index 1f7dc97a4b..1a2d0979a2 100644 --- a/content/nim/waf-integration/policies-and-logs/policies/delete-policy.md +++ b/content/nim/waf-integration/policies-and-logs/policies/delete-policy.md @@ -32,7 +32,7 @@ To delete a policy using the REST API: 1. Retrieve the policy’s UID by sending a `GET` request to the Security Policies endpoint: ```shell - curl -X GET https://{{NIM_FQDN}}/api/platform/v1/security/policies \ + curl -X GET https:///api/platform/v1/security/policies \ -H "Authorization: Bearer " ``` @@ -47,7 +47,7 @@ To delete a policy using the REST API: **Example:** ```shell -curl -X DELETE https://{{NIM_FQDN}}/api/platform/v1/security/policies/ \ +curl -X DELETE https:///api/platform/v1/security/policies/ \ -H "Authorization: Bearer " ``` diff --git a/content/nim/waf-integration/policies-and-logs/policies/update-policy.md b/content/nim/waf-integration/policies-and-logs/policies/update-policy.md index 2eabf09254..f7dcb28187 100644 --- a/content/nim/waf-integration/policies-and-logs/policies/update-policy.md +++ b/content/nim/waf-integration/policies-and-logs/policies/update-policy.md @@ -43,7 +43,7 @@ To update a policy using the REST API, send either a `POST` or `PUT` request to **Example using POST (create new revision):** ```shell -curl -X POST https://{{NIM_FQDN}}/api/platform/v1/security/policies?isNewRevision=true \ +curl -X POST https:///api/platform/v1/security/policies?isNewRevision=true \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d @update-xss-policy.json @@ -54,14 +54,14 @@ curl -X POST https://{{NIM_FQDN}}/api/platform/v1/security/policies?isNewRevisio 1. Retrieve the policy’s unique identifier (UID): ```shell - curl -X GET https://{{NIM_FQDN}}/api/platform/v1/security/policies \ + curl -X GET https:///api/platform/v1/security/policies \ -H "Authorization: Bearer " ``` 1. Include the UID in your `PUT` request: ```shell - curl -X PUT https://{{NIM_FQDN}}/api/platform/v1/security/policies/ \ + curl -X PUT https:///api/platform/v1/security/policies/ \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d @update-xss-policy.json diff --git a/content/nim/waf-integration/policies-and-logs/publish/check-publication-status.md b/content/nim/waf-integration/policies-and-logs/publish/check-publication-status.md index 824107d362..247c1d28a1 100644 --- a/content/nim/waf-integration/policies-and-logs/publish/check-publication-status.md +++ b/content/nim/waf-integration/policies-and-logs/publish/check-publication-status.md @@ -28,7 +28,7 @@ To view deployment status for a specific policy, send a `GET` request to the Sec Example: ```shell -curl -X GET "https://{{NIM_FQDN}}/api/platform/v1/security/deployments/associations/ignore-xss" \ +curl -X GET "https:///api/platform/v1/security/deployments/associations/ignore-xss" \ -H "Authorization: Bearer " ``` @@ -45,7 +45,7 @@ In the response, check the `lastDeploymentDetails` field under `instance` or `in Example: ```shell -curl -X GET "https://{{NIM_FQDN}}/api/platform/v1/security/deployments/logprofiles/associations/default-log" \ +curl -X GET "https:///api/platform/v1/security/deployments/logprofiles/associations/default-log" \ -H "Authorization: Bearer " ``` @@ -64,7 +64,7 @@ To view deployment status for a specific instance, provide the system UID and in Example: ```shell -curl -X GET "https://{{NIM_FQDN}}/api/platform/v1/systems//instances/" \ +curl -X GET "https:///api/platform/v1/systems//instances/" \ -H "Authorization: Bearer " ``` @@ -84,7 +84,7 @@ You can use this ID to check the final result of the publication. Example: ```shell -curl -X GET "https://{{NIM_FQDN}}/api/platform/v1/systems/instances/deployments/" \ +curl -X GET "https:///api/platform/v1/systems/instances/deployments/" \ -H "Authorization: Bearer " ``` diff --git a/content/nim/waf-integration/policies-and-logs/publish/publish-to-instances.md b/content/nim/waf-integration/policies-and-logs/publish/publish-to-instances.md index 6600baf62c..e990b599d8 100644 --- a/content/nim/waf-integration/policies-and-logs/publish/publish-to-instances.md +++ b/content/nim/waf-integration/policies-and-logs/publish/publish-to-instances.md @@ -34,7 +34,7 @@ Include the following details in your request body, depending on what you’re p ### Example request ```shell -curl -X POST https://{{NIM_FQDN}}/api/platform/v1/security/publish \ +curl -X POST https:///api/platform/v1/security/publish \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d @publish-request.json diff --git a/static/scripts/offline_usage.sh b/static/scripts/offline_usage.sh new file mode 100644 index 0000000000..028cac0b8d --- /dev/null +++ b/static/scripts/offline_usage.sh @@ -0,0 +1,294 @@ +#!/bin/bash + +# F5, Inc 2026 + +# Copyright (C) 2026 F5, Inc. All rights reserved. +# This script is for reference only. You should copy and modify it to suit your particular deployment. + +# offline_usage.sh +# Downloads usage report from NGINX Instance Manager. +# Uploads usage report to NGINX One console. +# +# Usage: +# ./offline_usage.sh download +# ./offline_usage.sh upload --result-dir [--endpoint-url ] +# +# Arguments: +# download: Requires operation, username, password, and nim_ip for NGINX Instance Manager +# upload: Requires operation and file_path; flags are optional +# +# Output: +# /tmp/response.zip - downloaded usage report (download) +# upload_usage.log - log file for upload operation + +set -euo pipefail + +require_cmd() { command -v "$1" >/dev/null 2>&1 || { echo "Missing required command: $1" >&2; exit 1; }; } +require_cmd unzip require_cmd jq +if [[ $# -lt 1 ]]; then + echo "Usage:" + echo " $0 download " + echo " $0 upload --result-dir [--endpoint-url ]" + exit 1 +fi + +OPERATION="$1" + +if [[ "$OPERATION" == "download" ]]; then + if [[ $# -lt 4 ]]; then + echo "Usage:" + echo " $0 download " + exit 1 + fi + USERNAME="$2" + PASSWORD="$3" + NIM_IP="$4" + # Set timeouts for operations + CURL_TIMEOUT=${CURL_TIMEOUT:-30} + + # Ensure /tmp directory exists (should always exist on Linux) + if [ ! -d "/tmp" ]; then + echo "/tmp directory does not exist. Creating it now..." + mkdir -p /tmp || { echo "Failed to create /tmp directory. Exiting."; exit 1; } + fi + + # Encode credentials for Basic Auth + AUTH_HEADER=$(echo -n "$USERNAME:$PASSWORD" | base64) + + echo "Checking connectivity to NGINX Instance Manager using Curl ..." + if ! curl -sk --output /dev/null --silent --fail --max-time "${CURL_TIMEOUT}" "https://$NIM_IP"; then + echo "The NGINX Instance Manager UI is not reachable on $NIM_IP" + exit 1 + fi + + # Send GET request and capture response and status code + response=$(curl -sk -w "%{http_code}" -o /tmp/device_mode.json "https://$NIM_IP/api/platform/v1/report/device_mode" \ + -H 'accept: application/json' -H "Authorization: Basic $AUTH_HEADER") + + # Extract status code and response body + http_code="${response: -3}" + body=$(cat /tmp/device_mode.json) + + # Check response code + if [[ "$http_code" != "200" ]]; then + echo "Request failed with status code $http_code" + exit 1 + fi + + # Parse device_mode using jq + device_mode=$(echo "$body" | jq -r '.device_mode') + + echo "Device mode is: $device_mode" + + if [[ "$device_mode" == "CONNECTED" ]]; then + echo "Device mode is CONNECTED. This script is only for DISCONNECTED mode" + exit 1 + fi + + # Download the usage report + echo "Downloading usage report from NGINX Instance Manager at $NIM_IP..." + HTTP_RESPONSE=$(curl -k -sS -w "\n%{http_code}" --location "https://$NIM_IP/api/platform/v1/report/download?format=zip" \ + --header "accept: application/json" \ + --header "authorization: Basic $AUTH_HEADER" \ + --header "content-type: application/json" \ + --header "origin: https://$NIM_IP" \ + --output /tmp/response.zip) + + HTTP_STATUS=$(echo "$HTTP_RESPONSE" | tail -n1) + if [ "$HTTP_STATUS" -ne 200 ]; then + echo "Failed to download usage report from NGINX Instance Manager. HTTP Status Code: $HTTP_STATUS" >&2 + echo "Please verify that NGINX Instance Manager is reachable and the credentials are correct." >&2 + echo "(or) Verify that NGINX Instance Manager is licensed before using the 'telemetry' flag (run it with 'initial' first)." + exit 1 + fi + + echo "Usage report downloaded successfully to /tmp/response.zip" + exit 0 +fi + +# Upload operation +if [[ "$OPERATION" == "upload" ]]; then + LOG_FILE="upload_usage.log" + # Only set permissions if file is newly created + if [ ! -f "$LOG_FILE" ]; then + touch "$LOG_FILE" + chmod 600 "$LOG_FILE" + fi + + FAILED_UPLOADS=() + DEFAULT_ENDPOINT_URL="https://product.connect.nginx.com/api/nginx-usage/batch" + + # Argument parsing: + # upload --result-dir [--endpoint-url ] + if [ "$#" -lt 2 ]; then + echo "Usage: $0 upload --result-dir [--endpoint-url ]" + echo " Path to exported usage .zip file (required)" + echo " --endpoint-url, -e Upload endpoint URL (default: $DEFAULT_ENDPOINT_URL)" + echo " --result-dir, -r Directory to track uploaded files (required)" + exit 1 + fi + + EXPORTED_USAGE="$2" + ENDPOINT_URL="$DEFAULT_ENDPOINT_URL" + RESULT_DIR="" + + if [ ! -f "$EXPORTED_USAGE" ]; then + echo "Error: upload file not found: $EXPORTED_USAGE" >&2 + exit 1 + fi + + # Basic validation that the provided file is a ZIP archive. + # (Prefer a content check over relying only on the .zip extension.) + if ! unzip -tq "$EXPORTED_USAGE" >/dev/null 2>&1; then + echo "Error: upload file is not a valid .zip archive: $EXPORTED_USAGE" >&2 + exit 1 + fi + + shift 2 + while [ "$#" -gt 0 ]; do + case "$1" in + --endpoint-url|-e) + if [ "$#" -lt 2 ]; then + echo "Error: $1 requires a value" >&2 + exit 1 + fi + ENDPOINT_URL="$2" + shift 2 + ;; + --result-dir|-r) + if [ "$#" -lt 2 ]; then + echo "Error: $1 requires a value" >&2 + exit 1 + fi + RESULT_DIR="$2" + shift 2 + ;; + --help|-h) + echo "Usage: $0 upload --result-dir [--endpoint-url ]" + echo " Path to exported usage .zip file (required)" + echo " --endpoint-url, -e Upload endpoint URL (default: $DEFAULT_ENDPOINT_URL)" + echo " --result-dir, -r Directory to track uploaded files (required)" + exit 0 + ;; + *) + echo "Unknown argument: $1" >&2 + echo "Usage: $0 upload --result-dir [--endpoint-url ]" >&2 + exit 1 + ;; + esac + done + + # result-dir is required + if [ -z "$RESULT_DIR" ]; then + echo "Error: --result-dir (or -r) is required" >&2 + echo "Usage: $0 upload --result-dir [--endpoint-url ]" >&2 + exit 1 + fi + + UNZIP_DIR="$RESULT_DIR/unzip" + + mkdir -p "$RESULT_DIR" + chmod 700 "$RESULT_DIR" + mkdir -p "$UNZIP_DIR" + chmod 700 "$UNZIP_DIR" + mkdir -p "$RESULT_DIR" + chmod 700 "$RESULT_DIR" + + # Display the contents of the directory + unzip -o -q "$EXPORTED_USAGE" -d "$UNZIP_DIR" + echo "Contents of the UNZIP_DIR directory '$UNZIP_DIR':" + echo "" + ls -alh "$UNZIP_DIR" + echo "" + + while IFS= read -r -d '' TOKEN_DIR; do + JWT_FILE="$TOKEN_DIR/jwt.txt" + if [ ! -f "$JWT_FILE" ]; then + echo "No jwt.txt found in $TOKEN_DIR, skipping." + echo "$(date '+%Y-%m-%d %H:%M:%S') [SKIP] No jwt.txt found in $TOKEN_DIR" >> "$LOG_FILE" + continue + fi + JWT=$(cat "$JWT_FILE") + for GZIP_FILE in "$TOKEN_DIR"/usage*.gzip; do + [ -e "$GZIP_FILE" ] || continue + UPLOADED_LIST="$RESULT_DIR/uploaded_files.txt" + if [ -f "$UPLOADED_LIST" ] && grep -Fxq "$GZIP_FILE" "$UPLOADED_LIST"; then + echo "Already uploaded: $GZIP_FILE (listed in $UPLOADED_LIST), skipping." + echo "$(date '+%Y-%m-%d %H:%M:%S') [SKIP] $GZIP_FILE already uploaded (listed in $UPLOADED_LIST)" >> "$LOG_FILE" + continue + fi + RETRIES=0 + MAX_RETRIES=5 + SUCCESS=0 + while [ $RETRIES -lt $MAX_RETRIES ]; do + CURL_CMD="curl -s -o /dev/null -w \"%{http_code}\" -X POST \"$ENDPOINT_URL\" --header \"Authorization: Bearer \$JWT\" --header \"Content-Type: application/gzip\" --data-binary @\"$GZIP_FILE\"" + echo "DEBUG: Posting with curl command: $CURL_CMD" + echo "$(date '+%Y-%m-%d %H:%M:%S') [DEBUG] curl command: $CURL_CMD" >> "$LOG_FILE" + HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" \ + -X POST "$ENDPOINT_URL" \ + --header @<(echo "Authorization: Bearer $JWT") \ + --header "Content-Type: application/gzip" \ + --data-binary @"$GZIP_FILE") + echo "$(date '+%Y-%m-%d %H:%M:%S') [ATTEMPT] $GZIP_FILE -> $ENDPOINT_URL (HTTP $HTTP_CODE, attempt $((RETRIES+1)))" >> "$LOG_FILE" + if [ "$HTTP_CODE" = "200" ] || [ "$HTTP_CODE" = "201" ] || [ "$HTTP_CODE" = "204" ]; then + SUCCESS=1 + break + elif [[ "$HTTP_CODE" =~ ^(401|403|413|400)$ ]]; then + REASON="unknown" + case "$HTTP_CODE" in + 401) REASON="unauthorized";; + 403) REASON="forbidden";; + 413) REASON="request size too big";; + 400) REASON="bad request";; + esac + SKIP_MSG="$(date '+%Y-%m-%d %H:%M:%S') [SKIP] $GZIP_FILE $REASON (HTTP $HTTP_CODE), skipping retries" + echo "$SKIP_MSG" + echo "$SKIP_MSG" >> "$LOG_FILE" + break + else + # Retry backoff with small jitter (5–10ms) + JITTER_MS=$((RANDOM % 6)) + SLEEP_MS=$((5 + JITTER_MS)) + echo "Upload failed for $GZIP_FILE (HTTP $HTTP_CODE), retrying in $SLEEP_MS milliseconds..." + echo "$(date '+%Y-%m-%d %H:%M:%S') [RETRY] $GZIP_FILE failed (HTTP $HTTP_CODE), sleeping $SLEEP_MS milliseconds" >> "$LOG_FILE" + sleep "0.$(printf '%03d' "$SLEEP_MS")" + RETRIES=$((RETRIES+1)) + fi + done + if [ $SUCCESS -eq 1 ]; then + # Small post-success delay to avoid hammering the endpoint. + # Use milliseconds (2–5ms) via fractional seconds; supported by GNU/coreutils sleep. + JITTER_SUCCESS_MS=$((RANDOM % 4)) + SLEEP_SUCCESS_MS=$((2 + JITTER_SUCCESS_MS)) + sleep "0.$(printf '%03d' "$SLEEP_SUCCESS_MS")" + echo "$GZIP_FILE" >> "$UPLOADED_LIST" + echo "Upload succeeded for $GZIP_FILE, path recorded in $UPLOADED_LIST" + echo "$(date '+%Y-%m-%d %H:%M:%S') [SUCCESS] $GZIP_FILE uploaded, path recorded in $UPLOADED_LIST" >> "$LOG_FILE" + else + echo "Upload failed for $GZIP_FILE after $MAX_RETRIES retries." + echo "$(date '+%Y-%m-%d %H:%M:%S') [FAIL] $GZIP_FILE failed after $MAX_RETRIES retries" >> "$LOG_FILE" + FAILED_UPLOADS+=("$GZIP_FILE") + fi + done + done < <(find "$UNZIP_DIR" -mindepth 2 -maxdepth 2 -type d -print0) + + echo "All uploads complete. Successful uploads recorded in $RESULT_DIR" + echo "Log file: $LOG_FILE" + + if [ "${#FAILED_UPLOADS[@]}" -gt 0 ]; then + echo "" + echo "Summary of failed uploads:" + for FILE in "${FAILED_UPLOADS[@]}"; do + echo " $FILE" + done + echo "" + echo "See $LOG_FILE for details." + else + echo "All files uploaded successfully." + fi + exit 0 +fi + +echo "Invalid operation: $OPERATION" +echo "Valid operations are: download, upload" +exit 1