Skip to content

Overview ↵

About the Splunk Add-on for NGINX

Component Description
Version 3.3.0
Vendor products NGINX Plus R16 v1.15.2, R17 v1.15.7, R18 v1.15.10, R19 v1.17.3, R20 v1.17.6, R21 v1.17.9, R22 v1.19.0, R24 v1.19.10, R25 v1.21.3, R27 v1.21.6
NGINX App Protect v1.3.0, v2.0, v3.5, v3.6, v3.11
Visible in Splunk Web No. This add-on does not contain any views.

The Splunk Add-on for NGINX allows a Splunk software administrator to collect Web Server activity, performance metrics, and error logs using file monitoring and API inputs. After the Splunk platform indexes the events, you can analyze the data using the add-on.

Release notes

For a summary of new features, fixed issues, known issues, and previous releases, see Release notes.

Compatibility

This add-on provides the inputs and CIM-compatible knowledge to use with other Splunk apps, such as Splunk Enterprise Security, the Splunk App for PCI Compliance, and Splunk IT Service Intelligence.

For detailed information about compatibility with other software, CIM versions, and platforms, see Release notes for the Splunk Add-on for NGINX.

Source types and lookups

For more information about the source types and lookups for Splunk Add-on for NGINX, see Source types and lookups.

Download the add-on

Download the Splunk Add-on for NGINX from Splunkbase.

Install and configure the add-on

To install and configure the Splunk Add-on for NGINX, see Installation and configuration overview for the Splunk Add-on for NGINX.

Hardware and software requirements

For more information, see Hardware and software requirements.

Additional resources

See Troubleshooting guidelines specific for this add-on.

Discuss the Splunk Add-on for NGINX on Splunk Community.

Release notes for the Splunk Add-on for NGINX

Version 3.3.0 (latest)

Version 3.3.0 of the Splunk Add-on for NGINX was released on September 16, 2024.

Compatibility

Component Description
Splunk platform versions 10.2.x, 10.1.x, 10.0.x, 9.4.x, 9.3.x, 9.2.x, 9.1.x, 9.0.x
CIM 5.0.1
Platforms Platform independent
Vendor Products NGINX Plus versions R16 v1.15.2, R17 v1.15.7, R18 v1.15.10, R19 v1.17.3, R20 v1.17.6, R21 v1.17.9, R22 v1.19.0, R24 v1.19.10, R25 v1.21.3, R27 v1.21.6

NGINX App Protect v1.3.0, v2.0, v3.5, v3.6, v3.11

Note

The field alias functionality is compatible with the current version of this add-on. The current version of this add-on does not support older field alias configurations.

For more information about the field alias configuration change, refer to the Splunk Enterprise Release Notes.

New features

Version 3.3.0 of the Splunk Add-on for NGINX has the following new features:

  • Python 3.9 compatibility.
  • Added support for IPv6.
  • Fixed the security vulnerabilities found in the certifi, and urllib3 libraries by upgrading its version from 2023.11.17 to 2024.7.4 and 1.26.18 to 1.26.19.

Fixed issues

Version 3.3.0 of the Splunk Add-on for NGINX fixes the following, if any, issues:

Known issues

Version 3.3.0 of the Splunk Add-on for NGINX has the following, if any, known issues:

Third-party software attributions

Version 3.3.0 of the Splunk Add-on for NGINX incorporates the following third-party libraries:

Third-party software attributions for the Splunk Add-on for NGINX.

Version 3.2.2

Version 3.2.2 of the Splunk Add-on for NGINX was released on December 11, 2023.

Compatibility

Component Description
Splunk platform versions 9.0.x, 9.1.x
CIM 5.0.1
Platforms Platform independent
Vendor products NGINX Plus versions R16 v1.15.2, R17 v1.15.7, R18 v1.15.10, R19 v1.17.3, R20 v1.17.6, R21 v1.17.9, R22 v1.19.0, R24 v1.19.10, R25 v1.21.3, R27 v1.21.6

NGINX App Protect v1.3.0, v2.0, v3.5, v3.6, v3.11

Note

The field alias functionality is compatible with the current version of this add-on. The current version of this add-on does not support older field alias configurations.

For more information about the field alias configuration change, refer to the Splunk Enterprise Release Notes.

New features

Version 3.2.2 of the Splunk Add-on for NGINX has the following new features:

  • Fixed the security vulnerabilities found in the certifi, requests, and urllib3 libraries by upgrading its version from 2022.12.7 to 2023.11.17, 2.28.1 to 2.31.0, and 1.26.6 to 1.26.18.

Fixed issues

Version 3.2.2 of the Splunk Add-on for NGINX fixes the following, if any, issues:

Known issues

Version 3.2.2 of the Splunk Add-on for NGINX has the following, if any, known issues:

Third-party software attributions

Version 3.2.2 of the Splunk Add-on for NGINX incorporates the following third-party libraries:

Third-party software attributions for the Splunk Add-on for NGINX.

Version 3.2.1

Version 3.2.1 of the Splunk Add-on for NGINX was released on February 22, 2023.

Compatibility

Component Description
Splunk platform versions 8.1.x, 8.2.x, 9.0.0
CIM 5.0.1
Platforms Platform independent
Vendor products NGINX Plus versions R16 v1.15.2, R17 v1.15.7, R18 v1.15.10, R19 v1.17.3, R20 v1.17.6, R21 v1.17.9, R22 v1.19.0, R24 v1.19.10, R25 v1.21.3, R27 v1.21.6

NGINX App Protect v1.3.0, v2.0, v3.5, v3.6, v3.11

Note

The field alias functionality is compatible with the current version of this add-on. The current version of this add-on does not support older field alias configurations.

For more information about the field alias configuration change, refer to the Splunk Enterprise Release Notes.

New features

Version 3.2.1 of the Splunk Add-on for NGINX has the following new features:

  • Upgraded the certifi library to version 2022.12.7
  • Fixed a security vulnerability found in the certifi library

Fixed issues

Version 3.2.1 of the Splunk Add-on for NGINX fixes the following, if any, issues:

Known issues

Version 3.2.1 of the Splunk Add-on for NGINX has the following, if any, known issues:

Third-party software attributions

Version 3.2.1 of the Splunk Add-on for NGINX incorporates the following third-party libraries:

Third-party software attributions for the Splunk Add-on for NGINX.

Version 3.2.0

Version 3.2.0 of the Splunk Add-on for NGINX was released on July 21, 2022.

Compatibility

Component Description
Splunk platform versions 8.1.x, 8.2.x, 9.0.0
CIM 5.0.1
Platforms Platform independent
Vendor products NGINX Plus versions R16 v1.15.2, R17 v1.15.7, R18 v1.15.10, R19 v1.17.3, R20 v1.17.6, R21 v1.17.9, R22 v1.19.0, R24 v1.19.10, R25 v1.21.3, R27 v1.21.6

NGINX App Protect v1.3.0, v2.0, v3.5, v3.6, v3.11

Note

The field alias functionality is compatible with the current version of this add-on. The current version of this add-on does not support older field alias configurations.

For more information about the field alias configuration change, refer to the Splunk Enterprise Release Notes.

New features

  • Support for Nginx Plus R27 v1.21.6.
  • Support for Nginx App Protect v3.11.
  • Support for CIM v5.0.1.
  • Minor bug fixes.

Fixed issues

Version 3.2.0 of the Splunk Add-on for NGINX fixes the following, if any, issues:

Known issues

Version 3.2.0 of the Splunk Add-on for NGINX has the following, if any, known issues:

Third-party software attributions

Version 3.2.0 of the Splunk Add-on for NGINX incorporates the following third-party libraries:

Third-party software attributions for the Splunk Add-on for NGINX.

Version 3.1.0

Version 3.1.0 of the Splunk Add-on for NGINX was released on November 10, 2021.

Component Description
Splunk platform versions 8.0.x, 8.1.x, 8.2.x
CIM 4.20.2
Platforms Platform independent
Vendor products NGINX Plus versions R16 v1.15.2, R17 v1.15.7, R18 v1.15.10, R19 v1.17.3, R20 v1.17.6, R21 v1.17.9, R22 v1.19.0, R24 v1.19.10, R25 v1.21.3

NGINX App Protect v1.3.0, v2.0, v3.5, v3.6

Note

The field alias functionality is compatible with the current version of this add-on. The current version of this add-on does not support older field alias configurations.

For more information about the field alias configuration change, refer to the Splunk Enterprise Release Notes.

New features

  • Support for Nginx Plus R24 v1.19.10 and R25 v1.21.3
  • Support for Nginx App Protect v3.5 and v3.6
  • Removed Python2 support. From this release onwards, add-on only supports python3.
  • Removed support for Splunk 7.x versions. Add-on now supports Splunk 8.x versions only.
  • CIM mapping and enhancements:
    • Added http_referrer_domain, url_length, and url_domain fields to the nginx:plus:access sourcetype.
    • Added http_referrer_domain, url_length, and url_domain fields to the nginx:plus:kv sourcetype.
    • Added support for CIM v4.20.2

Fixed issues

Version 3.1.0 of the Splunk Add-on for NGINX fixes the following, if any, issues:

Known issues

Version 3.1.0 of the Splunk Add-on for NGINX has the following, if any, known issues:

Third-party software attributions

Version 3.1.0 of the Splunk Add-on for NGINX incorporates the following third-party libraries:

Third-party software attributions for the Splunk Add-on for NGINX.

Version 3.0.0

Version 3.0.0 of the Splunk Add-on for NGINX was released on October 16, 2020.

Compatibility

Version 3.0.0 of the Splunk Add-on for NGINX is compatible with the following software, CIM versions and platforms.

Component Description
Splunk platform versions 8.0, 7.3, 7.2
CIM 4.17
Platforms Platform independent
Vendor products NGINX Plus versions R16 v1.15.2, R17 v1.15.7, R18 v1.15.10, R19 v1.17.3, R20 v1.17.6, R21 v1.17.9, R22 v1.19.0

NGINX App Protect v1.3.0, v2.0

Note

The field alias functionality is compatible with the current version of this add-on. The current version of this add-on does not support older field alias configurations.

For more information about the field alias configuration change, refer to the Splunk Enterprise Release Notes.

New or changed features

  • Support for Nginx App Protect
  • Support for additional NGINX Plus versions
  • Support for CIM 4.17.0

Fixed issues

Version 3.0.0 of the Splunk Add-on for NGINX fixes the following, if any, issues:

Known issues

Version 3.0.0 of the Splunk Add-on for NGINX has the following, if any, known issues:

Third-party software attributions

Version 3.0.0 of the Splunk Add-on for NGINX incorporates the following third-party software or libraries:

Version 2.0.2

Version 2.0.2 of the Splunk Add-on for NGINX was released on March 13, 2020.

Compatibility

Version 2.0.2 of the Splunk Add-on for NGINX is compatible with the following software, CIM versions and platforms.

Component Description
Splunk platform versions 8.0.0, 7.3.0, 7.2.x, 7.1.x, 7.0.x
CIM 4.14
Platforms Platform independent
Vendor products NGINX Plus R8(1.9.9), NGINX Plus R15(1.13.10)

New or changed features

  • Updated .conf to execute python3 files.

Fixed issues

Version 2.0.2 of the Splunk Add-on for NGINX fixes the following, if any, issues:

Known issues

Version 2.0.2 of the Splunk Add-on for NGINX has the following, if any, known issues:

Third-party software attributions

Version 2.0.2 of the Splunk Add-on for NGINX incorporates the following third-party software or libraries:

Version 2.0.1

Compatibility

Version 2.0.1 of the Splunk Add-on for NGINX is compatible with the following software, CIM versions, and platforms.

Component Description
Splunk platform versions 7.0.x, 7.1.x, 7.2.x, 7.3.x, 8.0.x
CIM 4.14
Platforms Platform independent
Vendor products NGINX Plus R8 versions 1.9.9

NGINX Plus R15 versions 1.13.10 (New NGINX Plus API not supported)

New or changed features

  • Support for NGINX server v1.13.10 (New NGINX Plus API not supported)
  • Common information model (CIM) version 4.1.4 compatibility
  • Support for Python3
  • Support for HTTPS as the default for status API inputs.
  • Support for authentication of status endpoints that are configured on an NGINX server.

Fixed issues

Version 2.0.1 of the Splunk Add-on for NGINX fixes the following, if any, issues:

Known issues

Version 2.0.1 of the Splunk Add-on for NGINX has the following, if any, known issues:

Third-party software attributions

Version 2.0.1 of the Splunk Add-on for NGINX incorporates the following third-party software or libraries:

Version 1.0.0

Compatibility

Version 1.0.0 of the Splunk Add-on for NGINX is compatible with the following software, CIM versions, and platforms.

Component Description
Splunk platform versions 6.6.x, 7.0.x, 7.1.x, 7.2.x
CIM 4.11
Platforms Platform independent
Vendor products NGINX Plus 1.9.9 and later

Known issues

Version 1.0.0 of the Splunk Add-on for NGINX has the following, if any, known issues:

Third-party software attributions

Version 1.0.0 of the Splunk Add-on for NGINX does not incorporate any third-party software or libraries.

Hardware and software requirements for the Splunk Add-on for NGINX

Splunk admin requirements

To install and configure the Splunk Add-on for NGINX, you must be a member of the admin or sc_admin role.

NGINX setup requirements

You must have administrative privileges on the NGINX server to configure NGINX logging.

Splunk platform requirements

Because this add-on runs on the Splunk platform, all of the system requirements apply for the Splunk software that you use to run this add-on.

  • For Splunk Enterprise system requirements, see System Requirements in the Splunk Enterprise Installation Manual.
  • If you are managing on-premises forwarders to get data into Splunk Cloud, see System Requirements in the Splunk Enterprise Installation Manual, which includes information about forwarders.

Installation and configuration overview for the Splunk Add-on for NGINX

Complete the following steps to install and configure this add-on.

  1. Review hardware and software requirements.
  2. Install the Splunk Add-on for NGINX.
  3. Set up the Splunk Add-on for NGINX.
  4. Configure inputs for the Splunk Add-on for NGINX.

Ended: Overview

Installation ↵

Install the Splunk Add-on for NGINX

  1. Get the Splunk Add-on for NGINX by downloading it from Splunkbase or browsing to it using the app browser within Splunk Web.
  2. Determine where and how to install this add-on in your deployment, using the tables on this page.
  3. Perform any prerequisite steps before installing, if required and specified in the tables on this page.
  4. Complete your installation.

If you need step-by-step instructions on how to install an add-on in your specific deployment environment, see Installation walkthroughs at the bottom of this page for links to single-instance, distributed, and Splunk Cloud deployment instructions.

Distributed deployments

Use the tables on this page to determine where and how to install this add-on in a distributed deployment of Splunk Enterprise, or in any deployment that uses forwarders for data collection. Depending on your environment, preferences, and add-on requirements, you might need to install the add-on in multiple places.

Where to install this add-on

Unless otherwise noted, all supported add-ons can be safely installed to all tiers of a distributed Splunk platform deployment. See Where to install Splunk add-ons in Splunk Add-ons for more information.

This table provides a reference for installing this specific add-on to a distributed deployment of Splunk Enterprise.

Splunk instance type Supported Required Comments
Search heads Yes Yes Install this add-on to all search heads where NGINX knowledge management is required.
Indexers Yes Conditional Not required if you use heavy forwarders to collect data. Required if you use universal forwarders to collect data.
Heavy forwarders Yes Conditional Required for the NGINX status API input. Optional file monitoring inputs. The file monitoring inputs must be enabled on a forwarder that is installed directly on the machine running your NGINX server.
Universal forwarders Yes Conditional Not supported for NGINX status API inputs. Supported only for file monitoring inputs. The file monitoring inputs must be enabled on a forwarder that is installed directly on the machine running your NGINX server.

Distributed deployment feature compatibility

This table describes the compatibility of this add-on with Splunk distributed deployment features.

Distributed deployment feature Supported Actions required
Search head clusters Yes Disable add-on visibility on search heads.
You can install this add-on on a search head cluster for all search-time functionality, but configure inputs on forwarders to avoid duplicate data collection.
Indexer clusters Yes
Deployment server No Supported for deploying unconfigured add-ons only.
Note: Using a deployment server to deploy the configured add-on to multiple forwarders acting as data collectors causes duplication of data.

Installation walkthroughs

The Splunk Add-Ons manual includes an Installing add-ons guide that helps you successfully install any Splunk-supported add-on to your Splunk platform.

For a walkthrough of the installation procedure, follow the link that matches your deployment scenario:

Upgrade the Splunk Add-on for NGINX

There are different upgrade instructions for different versions of the Splunk Add-on for NGINX.

Upgrade from version 2.0.2 to version 3.0.0 and higher

Splunk Add-on for NGINX from version 3.0.0 onward relies on the Python runtime bundled with Splunk Enterprise and no longer requires certain legacy Python libraries that were packaged with version 2.0.2. Architectural decisions made for Splunk Enterprise do not allow modules introduced in previous versions of the add-on to be removed automatically during upgrade. Splunk administrators must manually delete the following files and directories from the $SPLUNK_HOME/etc/apps/Splunk_TA_nginx/bin/ directory on all Splunk servers where the add-on was upgraded:

  • configparser.py
  • backports/
  • builtins/
  • future/
  • reprlib/
  • splunk_ta_nginx/
  • __pycache__/

This guarantees that the add-on uses the Python libraries bundled with Splunk Enterprise and ensures proper modular input functionality and compatibility after the upgrade.

Upgrade to version 3.0.0

  • If you are upgrading the Splunk Add-on for NGINX from a previous version to 3.0.0, you must follow the same instructions as a new install and complete all of the configuration steps from the beginning.
  • You should only upgrade if you are also upgrading (or have already upgraded) your NGINX installation to one of the compatible NGINX versions for 3.0.0.
  • If you upgrade either your NGINX product or Splunk Add-on installation without upgrading the other and completing the configuration steps, the add-on will not be able to ingest new data.

Upgrade to version 2.0.2

If you are using these versions of NGINX, use version 2.0.2 of the Splunk Add-on for NGINX:

  • NGINX Plus R8 versions 1.9.9
  • NGINX Plus R15 versions 1.13.10 (new NGINX Plus API not supported)

There are two ways to upgrade the Splunk Add-on for NGINX to version 2.0.2:

Upgrade using the authentication feature

Versions 2.0.x and later of the Splunk Add-on for NGINX include a feature to use authentication to access status endpoints, if they are configured on an NGINX Server. To use this feature, use the following upgrade steps.

  1. Log in to Splunk Web.
  2. Select Settings > Data inputs > Splunk Add-on for NGINX.
  3. Disable all Splunk Add-on for NGINX inputs.
  4. Download and install the latest version of the Splunk Add-on for NGINX from Splunkbase.
  5. Identify whether your NGINX deployment uses encrypted or unencrypted communication. See the Switch between encrypted and unencrypted communication section of this manual for more information.
  6. Configure authentication on NGINX Server. See the topic on Restricting Access with HTTP Basic Authentication in the NGINX documentation.
  7. Click on the input name and edit the Nginx URL field value to remove the http_scheme. For example, change http://127.0.0.1/status to 127.0.0.1/status
  8. (Optional) Add the NGINX username you use to access the NGINX status JSON REST interface
  9. (Optional) Add the NGINX password you use to access the NGINX status JSON REST interface
  10. Save your changes.
  11. Restart your Splunk platform instance.
  12. Enable each Splunk Add-on for NGINX input.

Upgrade using default settings

By default, all communications from version 2.0.x of the Splunk Add-on for NGINX to your NGINX servers are encrypted by using HTTPS with SSL certificate validation enabled. If you are using the nginx:plus:api input, use the following steps to upgrade from version 1.0.0 to version 2.0.x.

  1. Log in to Splunk Web.
  2. Select Settings > Data inputs > Splunk Add-on for NGINX.
  3. Disable all Splunk Add-on for NGINX inputs.
  4. Download and install the latest version of the Splunk Add-on for NGINX from Splunkbase.
  5. Identify whether your NGINX deployment uses encrypted or unencrypted communication. See the Switch between encrypted and unencrypted communication section of this manual for more information.
  6. Restart your Splunk platform instance.
  7. Log in to Splunk Web.
  8. Select Settings > Data inputs > Splunk Add-on for NGINX.
  9. Click on each input name and edit the Nginx URL field value to remove the http_scheme (For example, change http://127.0.0.1/status to 127.0.0.1/status)
  10. Save your changes.
  11. Restart your Splunk platform instance.
  12. Enable each input.

Ended: Installation

Configuration ↵

Configure NGINX logging and monitoring

You need to set up the NGINX logging and monitoring to enable the Splunk Add-on for NGINX to collect data from the NGINX server including access log, error log, and performance metrics.

Configure NGINX access log

NGINX writes information about client requests in the access log right after the request is processed. By default, the access log is located at /var/log/nginx/access.log, and the information is written to the log in the predefined combined format. You can override the default settings and change the format of logged messages by editing the NGINX configuration file (by default it is the /etc/nginx/nginx.conf file). The Splunk Add-on for NGINX can ingest the NGINX access log in both the predefined combined format and the custom key-value pair format. Splunk recommends using the custom key-value pair format because it contains more information and is easier to parse.

Default NGINX access log

For information about setting up the default NGINX access log, refer to the NGINX documentation: https://www.nginx.com/resources/admin-guide/logging-and-monitoring/#access_log.

Custom NGINX access log

Edit the NGINX configuration file (by default it is the /etc/nginx/nginx.conf file) and use the log_format directive to define the format of logged messages based on your requirements.

Here is an example of logging in raw format for the nginx:plus:access source type:

log_format main '$remote_addr $server_name $remote_user [$time_local] "$request" '
                '$status $body_bytes_sent "$http_referer" '
                '"$http_user_agent" "$http_x_forwarded_for" $server_port '
                '$upstream_bytes_received "$sent_http_content_type" $host "$https" "$http_cookie"';

Here is an example of logging in KV format for the nginx:plus:kv source type:

log_format kv 'site="$server_name" server="$host" dest_port="$server_port" dest_ip="$server_addr" '
              'src="$remote_addr" src_ip="$realip_remote_addr" user="$remote_user" '
              'time_local="$time_local" protocol="$server_protocol" status="$status" '
              'bytes_out="$bytes_sent" bytes_in="$upstream_bytes_received" '
              'http_referer="$http_referer" http_user_agent="$http_user_agent" '
              'nginx_version="$nginx_version" http_x_forwarded_for="$http_x_forwarded_for" '
              'http_x_header="$http_x_header" uri_query="$query_string" uri_path="$uri" '
              'http_method="$request_method" response_time="$upstream_response_time" '
              'cookie="$http_cookie" request_time="$request_time" category="$sent_http_content_type" https="$https"';

Note

Use kv format instead of a raw format for the access log.

See the full list of variables at https://nginx.org/en/docs/varindex.html that you can capture in the log.

For more information about configuring ngx_http_log_module, see the official NGINX documentation at https://nginx.org/en/docs/http/ngx_http_log_module.html.

Set up NGINX error log

NGINX writes information about encountered issues of different severity levels to the error log. For information about setting up the NGINX error log, see https://www.nginx.com/resources/admin-guide/logging-and-monitoring/#error_log.

Set up NGINX live activity monitoring

NGINX Plus provides a real-time live activity monitoring interface that shows key load and performance metrics of your server infrastructure. These metrics can be represented as a RESTful JSON interface and live JSON data can be ingested into Splunk. You need to enable statistics collection in the NGINX Plus configuration file. For information about setting up live activity monitoring, see https://www.nginx.com/resources/admin-guide/Monitoring.

Configure the NGINX App Protect Security log

Security logs (also known as Request logs or Traffic logs) contain information on HTTP requests and responses, how App Protect processes them, and the final decision made based on the configured policy parameters. The policy configuration defines the information contained in the Security log, such as whether requests are passed, blocked or alerted, due to violations, attack signatures, and other criteria.

For information about setting up the default NGINX App Protect Security log, see the NGINX documentation at https://docs.nginx.com/waf/#security-logs.

Edit the /etc/app_protect/conf/log_default.json file and change the format from default to splunk.

For example:

{
  "filter": {
    "request_type": "illegal"
  },
  "content": {
    "format": "splunk",
    "max_request_size": "any",
    "max_message_size": "5k"
  }
}

Configure monitor inputs for the Splunk Add-on for NGINX

Install and configure a forwarder on your NGINX server to monitor the access and error log files generated by the NGINX server. You can use either Splunk Web to create the monitor input or configure inputs.conf directly.

Configure monitoring through Splunk Web

If you have access to Splunk Web on your forwarder:

  1. Log in to Splunk Web.
  2. Select Settings > Data inputs > Files & directories.
  3. Click New.
  4. Click Browse next to the File or Directory field.
  5. Navigate to the log file generated by the NGINX server and click Next.

  6. On the Input Settings page, click the Source type drop-down box and then enter nginx in the filter field and select one of the following source types depending on your access log format:

    • nginx:plus:access: the predefined combined format
    • nginx:plus:kv: the custom key-value pair format
    • nginx:plus:error: NGINX error log
    • nginx:app:protect: NGINX App Protect Security log

  7. Click Next.

  8. Click Review.
  9. After you review the information, click Submit.
  10. Repeat the above steps if you want to ingest more log files.

After you finish configuring inputs, run one or more of the following searches to check that you are ingesting the data that you expect:

sourcetype=nginx:plus:access

sourcetype=nginx:plus:kv

sourcetype=nginx:plus:error

sourcetype=nginx:app:protect

Configure inputs.conf

You can create an inputs.conf file and configure the monitor input in this file instead of using Splunk Web.

  1. Using a text editor, create a file named inputs.conf in the local folder of the add-on:
  • $SPLUNK_HOME/etc/apps/Splunk_TA_nginx/local in Unix-based environments.
  • %SPLUNK_HOME%\etc\apps\Splunk_TA_nginx\local in Windows-based environments.
  1. Add the following stanzas that match the log formats you want to collect, replacing <path> with the actual path to the log file:

  • NGINX access log in the predefined combined format

    [monitor:///<path>]
disabled = false
sourcetype = nginx:plus:access

  • NGINX access log in the custom key-value pair format

    [monitor:///<path>]
disabled = false
sourcetype = nginx:plus:kv

  • NGINX error log

    [monitor:///<path>]
disabled = false
sourcetype = nginx:plus:error

  • NGINX App Protect security log

    [monitor:///<path>]
disabled = false
sourcetype = nginx:app:protect
  1. Save the file.
  2. Restart the forwarder in order for the new input to take effect.

  3. Run one or more of the following searches to check that you are ingesting the data that you expect:

    sourcetype=nginx:plus:access

    sourcetype=nginx:plus:kv

    sourcetype=nginx:plus:error

    sourcetype=nginx:app:protect

Configure NGINX status API input

NGINX Plus provides a real-time live activity monitoring interface that shows key load and performance metrics of your server infrastructure. These metrics are represented as a RESTful JSON interface and this live data can be ingested into Splunk as NGINX Status API input.

Configure the NGINX Status API input through Splunk Web.

  1. Identify whether your NGINX deployment uses encrypted or unencrypted communication. See Switch between encrypted and unencrypted communication in this topic for more information.
  2. Log in to Splunk Web.
  3. Select Settings, and then Data inputs, and then Splunk Add-on for NGINX.
  4. Click New.
  5. On the NGINX Status API Input page, enter the following fields:
    • Name: A unique name that identifies the NGINX Status API input
    • Log level: One of these log levels (with decreasing verbosity): debug, info, warning, error
    • NGINX URL: Location of the NGINX status JSON REST interface. For example, 127.0.0.1/api
    • NGINX API Types: Enter comma-separated NGINX Plus API types for which data needs to be fetched. Allowed values are processes, connections, slabs, http, stream, resolvers, and ssl.
    • NGINX Username (Optional) Add the NGINX username you use to access the NGINX status JSON REST interface.
    • NGINX Password (Optional) Add the NGINX password you use to access the NGINX status JSON REST interface.
  6. Optionally, select More settings and modify the detailed settings field values as needed.
  7. Click Next.
  8. Click Review.
  9. After you review the information, click Submit.

Switch between encrypted and unencrypted communication

Switch between encrypted and unencrypted communication. By default, all the communications from the Splunk Add-on for NGINX to your NGINX servers are encrypted by using HTTPS with SSL certificate validation enabled. If your NGINX server is configured with HTTPS and a valid CA signed certificate, then communications with your NGINX server work with the default configurations.

Configure the Splunk Add-on for NGINX to use a self-signed certificate

If your NGINX server is configured with HTTPS using a self-signed certificate, perform the following steps:

  1. Download the CA certificate of the NGINX server in PEM format.
  2. Move the CA certificate to the $SPLUNK_HOME/etc/apps/Splunk_TA_nginx/local directory.
  3. Navigate to $SPLUNK_HOME/etc/apps/Splunk_TA_nginx/default/.
  4. Copy splunk_ta_nginx_settings.conf and paste in your deployment’s $SPLUNK_HOME/etc/apps/Splunk_TA_nginx/local folder.
  5. In $SPLUNK_HOME/etc/apps/Splunk_TA_nginx/local, open splunk_ta_nginx_settings.conf, and enter the path of the CA certificate file (including the file name) under the ssl_settings stanza.
  6. Save your changes.
  7. Restart the Splunk platform.

Switch from HTTPS to HTTP communications

Switch from HTTPS to HTTP communications when your NGINX server is configured with HTTP communications.

  1. Navigate to $SPLUNK_HOME/etc/apps/Splunk_TA_nginx/local/, and open splunk_ta_nginx_settings.conf in a text editor.
  2. Under the ssl_settings stanza, change the value of the http_scheme field from HTTPS to HTTP.
  3. Save your changes.
  4. Restart your Splunk platform instance.

Validate data collection

After you configure monitoring, run the following search to check that you are ingesting the data that you expect:

sourcetype=nginx:plus:api

Ended: Configuration

Troubleshooting ↵

Troubleshoot the Splunk Add-on for NGINX

General troubleshooting

For troubleshooting tips that you can apply to all add-ons, see Troubleshoot add-ons in Splunk Add-ons. For additional resources, see Support and resource links for add-ons in Splunk Add-ons.

Cannot launch add-on

This add-on does not have views and is not intended to be visible in Splunk Web. If you are trying to launch or load views for this add-on and you are experiencing results you do not expect, turn off visibility for the add-on.

For more details about add-on visibility and instructions for turning visibility off, see Check if the add-on is intended to be visible or not in the Splunk Add-ons Troubleshooting topic.

Cannot find the UI page for modular input configuration after upgrade

If you cannot find the UI page for modular input configuration after upgrading the add-on to version 3.0.0, make sure that you followed the upgrade instructions.

Ended: Troubleshooting

Reference ↵

Lookups for the Splunk Add-on for NGINX

The Splunk Add-on for NGINX has the following lookups that map fields from NGINX systems to CIM-compliant values in the Splunk platform. The lookup files are located in $SPLUNK_HOME/etc/apps/Splunk_TA_nginx/lookups.

Filename Description
nginx_proxy_actions.csv Maps vendor_action to action, transport (when NGINX is configured as a proxy server)
nginx_httpstatus.csv Maps the action field to a status_description value for individual status code.

Source types for the Splunk Add-on for NGINX

The Splunk Add-on for NGINX provides the index-time and search-time knowledge for NGINX Web server activities in the following formats.

Source type Description CIM data models ITSI data models
nginx:plus:access NGINX access log in the predefined combined format Web Web Server
nginx:plus:kv NGINX access log in the custom key-value pair format Web Web Server
nginx:app:protect NGINX App Protect security log in the predefined combined format Intrusion Detection
nginx:plus:api NGINX performance metrics
nginx:plus:error NGINX error log

For the NGINX access log, use the custom key-value pair format, which contains more verbose information and is easier to parse.

Ended: Reference