# Set up F5 WAF for NGINX instances for Security Monitoring > Connect F5 WAF for NGINX instances to Security Monitoring in F5 NGINX Instance Manager to collect and display security violation data. ## Overview 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 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 F5 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 Make sure you've completed the following before you start. 1. If you're new to F5 WAF for NGINX, follow the installation and configuration guides: - [Install F5 WAF for NGINX](/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](/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](/nim/licensing-and-reporting/add-license-connected-deployment.md). ## Install NGINX Agent 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 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. **Note:** Make sure `gpg` is installed on your system before continuing. You can install NGINX Agent using command-line tools like `curl` or `wget`. If your NGINX Instance Manager host doesn't use valid TLS certificates, you can use the insecure flags to bypass verification. Here are some example commands: #### curl - **Secure:** ```bash curl https:///install/nginx-agent | sudo sh ``` - **Insecure:** ```bash curl --insecure https:///install/nginx-agent | sudo sh ``` To add the instance to a specific instance group during installation, use the `--instance-group` (or `-g`) flag: ```shell curl https:///install/nginx-agent -o install.sh chmod u+x install.sh sudo ./install.sh --instance-group ``` By default, the install script uses a secure connection to download packages. If it can’t establish one, it falls back to an insecure connection and logs this message: ```text Warning: An insecure connection will be used during this nginx-agent installation ``` To enforce a secure connection, set the `--skip-verify` flag to false: ```shell curl https:///install/nginx-agent -o install.sh chmod u+x install.sh sudo ./install.sh --skip-verify false ``` #### wget - **Secure:** ```shell wget https:///install/nginx-agent -O - | sudo sh -s --skip-verify false ``` - **Insecure:** ```shell wget --no-check-certificate https:///install/nginx-agent -O - | sudo sh ``` To add your instance to a group during installation, use the `--instance-group` (or `-g`) flag: ```shell wget https:///install/nginx-agent -O install.sh chmod u+x install.sh sudo ./install.sh --instance-group ``` 1. Edit the `/etc/nginx-agent/nginx-agent.conf` file to add the `nap_monitoring` configuration. ```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 F5 WAF for NGINX details to the management plane. extensions: - nginx-app-protect - nap-monitoring # Enable reporting F5 WAF for NGINX details to the control plane. nginx_app_protect: # Report interval for F5 WAF for NGINX details - the frequency the NGINX Agent checks F5 WAF for NGINX 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 # F5 WAF for NGINX 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 `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; } } ``` After adding the directive, restart NGINX to apply the changes: ```shell sudo systemctl restart nginx ``` **Note:** You can change the values of `syslog_ip` and `syslog_port` to meet your needs. 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. **Note:** You can use the NGINX Agent installation script to add the fields for `nginx_app_protect` and `nap_monitoring`: ```shell # 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 F5 WAF for NGINX 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 ``` Restart NGINX Agent: ```shell sudo systemctl restart nginx-agent ``` ## Create instances for Security Monitoring only 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 these steps on each F5 WAF for NGINX data plane instance. 1. Use SSH to connect to the data plane host. 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 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 { "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 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; ``` **Note:** 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. 1. Restart NGINX Agent and the NGINX web server. ```shell sudo systemctl restart nginx-agent sudo systemctl restart nginx ``` You can now view data from your F5 WAF for NGINX instances in the Security Monitoring dashboards. ## 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** 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. 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 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; 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. 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'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](/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 `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. **Note:** 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. 1. Select **Publish** to push the configuration updates to your instance or instance group. You can now view data from your F5 WAF for NGINX instances in the Security Monitoring dashboard. ## See also - [Add user access to Security Monitoring dashboards](/nim/security-monitoring/give-access-to-security-monitoring-dashboards.md) - [Manage your F5 WAF for NGINX configs](/nim/waf-integration/configuration/_index.md)