diff --git a/content/nginx/admin-guide/dynamic-modules/cookie-flag.md b/content/nginx/admin-guide/dynamic-modules/cookie-flag.md index ed344866..f83eb6c1 100644 --- a/content/nginx/admin-guide/dynamic-modules/cookie-flag.md +++ b/content/nginx/admin-guide/dynamic-modules/cookie-flag.md @@ -10,69 +10,14 @@ type: - how-to --- -> **Note**: The module was deprecated in [Release 23]({{< ref "nginx/releases.md#r23" >}}) and removed in [Release 26]({{< ref "nginx/releases.md#r26" >}}). The [`proxy_cookie_flags`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cookie_flags) directive implements native support for setting cookie flags and replaces the module. See [Native Method for Setting Cookie Flags](https://www.nginx.com/blog/nginx-plus-r23-released#cookie-flags) for details. +{{< note >}} The `nginx-plus-module-cookie-flag` package is no longer available.{{< /note >}} -## Installation +The module was deprecated in [NGINX Plus Release 23]({{< ref "nginx/releases.md#r23" >}}) and removed in [NGINX Plus Release 26]({{< ref "nginx/releases.md#r26" >}}). Its functionality has been replaced with natively supported [`proxy_cookie_flags`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cookie_flags) directive. -1. Install the Cookie-Flag module. +To remove the module, follow the [Uninstalling a Dynamic Module]({{< ref "uninstall.md" >}}) instructions. - For Amazon Linux, CentOS, Oracle Linux, and RHEL: +To learn how to replace the module with the native solution, see [Native Method for Setting Cookie Flags](https://www.nginx.com/blog/nginx-plus-r23-released#cookie-flags) and the [`proxy_cookie_flags`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cookie_flags) directive. - ```shell - sudo yum update && \ - sudo yum install nginx-plus-module-cookie-flag - ``` - - For Debian and Ubuntu: - - ```shell - sudo apt update && \ - sudo apt install nginx-plus-module-cookie-flag - ``` - - For SLES: - - ```shell - sudo zypper refresh && \ - sudo zypper install nginx-plus-module-cookie-flag - ``` - - For Alpine: - - ```shell - apk add nginx-plus-module-cookie-flag - ``` - -2. Put the [`load_module`](https://nginx.org/en/docs/ngx_core_module.html#load_module) directive in the top‑level (“`main`”) context of F5 NGINX Plus configuration file, **nginx.conf**: - - ```nginx - load_module modules/ngx_http_cookie_flag_filter_module.so; - - http { - # ... - } - ``` - -3. Perform additional configuration as required by the [module](https://github.com/AirisX/nginx_cookie_flag_module). - -4. Test the NGINX Plus configuration. In a terminal, type-in the command: - - ```shell - nginx -t - ``` - - Expected output of the command: - - ```shell - nginx: the configuration file /etc/nginx/nginx.conf syntax is ok - nginx: configuration file /etc/nginx/nginx.conf is successful - ``` - -5. Reload the NGINX Plus configuration to enable the module: - - ```shell - nginx -s reload - ``` ## More Info diff --git a/content/nginx/admin-guide/dynamic-modules/dynamic-modules.md b/content/nginx/admin-guide/dynamic-modules/dynamic-modules.md index 02ab5e43..2edfeb89 100644 --- a/content/nginx/admin-guide/dynamic-modules/dynamic-modules.md +++ b/content/nginx/admin-guide/dynamic-modules/dynamic-modules.md @@ -15,110 +15,179 @@ F5 NGINX Plus uses a modular architecture. New features and functionality can be NGINX Plus allows features to be plugged in on demand -{{}} -Dynamic modules plug into NGINX Plus to provide additional functionality. -{{}} +Dynamic modules are shared object files (`.so`) that can be loaded at runtime using the [`load_module`](https://nginx.org/en/docs/ngx_core_module.html#load_module) directive in the NGINX configuration. + +NGINX maintains the official NGINX Plus repository, which also provides packaged binaries for both [NGINX‑authored](#nginx-authored-dynamic-modules) and [NGINX‑certified community](#nginx-certified-community-dynamic-modules) dynamic modules. All modules in this repository are fully tested to ensure full compatibility with NGINX Plus. + +For module‑specific installation and usage instructions, select the corresponding package name in the table. + + +{{< bootstrap-table "table table-striped table-bordered" >}} +| Name | Description | Package name | +|---------------------------------|-----------------------------------|--------------------| +| [Brotli](https://github.com/google/ngx_brotli) | Brotli compression support with modules for dynamic compression and for serving pre-compressed `.br` files. | [`nginx-plus-module-brotli`]({{< ref "nginx/admin-guide/dynamic-modules/brotli.md" >}}) | +| [Encrypted-Session](https://github.com/openresty/encrypted-session-nginx-module) | AES-256 based encryption/decryption of NGINX variables. | [`nginx-plus-module-encrypted-session`]({{< ref "nginx/admin-guide/dynamic-modules/encrypted-session.md" >}}) | +| [FIPS Status Check](https://github.com/ogarrett/nginx-fips-check-module) | Verifies if OpenSSL is operating in FIPS mode. | [`nginx-plus-module-fips-check`]({{< ref "nginx/admin-guide/dynamic-modules/fips.md" >}})| +| [GeoIP](https://nginx.org/en/docs/http/ngx_http_geoip_module.html) | Enables IP-based geolocation using the precompiled MaxMind databases. | [`nginx-plus-module-geoip`]({{< ref "nginx/admin-guide/dynamic-modules/geoip.md" >}}) | +| [GeoIP2](https://github.com/leev/ngx_http_geoip2_module) | Uses MaxMind GeoIP2 for enhanced geolocation. | [`nginx-plus-module-geoip2`]({{< ref "nginx/admin-guide/dynamic-modules/geoip2.md" >}})| +| [Headers-More](https://github.com/openresty/headers-more-nginx-module) | Extends the NGINX [Headers](https://nginx.org/en/docs/http/ngx_http_headers_module.html) module to modify request and response headers. | [`nginx-plus-module-headers-more`]({{< ref "nginx/admin-guide/dynamic-modules/headers-more.md" >}}) | +| [HTTP Substitutions Filter](https://github.com/yaoweibin/ngx_http_substitutions_filter_module) | Enables regex and string-based substitutions in response bodies. | [`nginx-plus-module-subs-filter`]({{< ref "nginx/admin-guide/dynamic-modules/http-substitutions-filter.md" >}}) | +| [Image-Filter](https://nginx.org/en/docs/http/ngx_http_image_filter_module.html) | Adds on-the-fly support for JPEG, GIF, PNG, and WebP image resizing and cropping. | [`nginx-plus-module-image-filter`]({{< ref "nginx/admin-guide/dynamic-modules/image-filter.md" >}}) | +| [Lua](https://github.com/openresty/lua-nginx-module) | Embeds Lua programming language. | [`nginx-plus-module-lua`]({{< ref "nginx/admin-guide/dynamic-modules/lua.md" >}})| +| [NGINX Developer Kit](https://github.com/vision5/ngx_devel_kit) | Provides helper macros for module development. | [`nginx-plus-module-ndk`]({{< ref "nginx/admin-guide/dynamic-modules/ndk.md" >}}) | +| [njs Scripting Language](https://nginx.org/en/docs/njs/) | Adds JavaScript-like scripting for advanced server-side logic in NGINX configuration file. | [`nginx-plus-module-njs`]({{< ref "nginx/admin-guide/dynamic-modules/nginscript.md" >}}) | +| [OpenTelemetry](https://nginx.org/en/docs/ngx_otel_module.html#directives) | Adds distributed tracing support via OpenTelemetry. | [`nginx-plus-module-otel`]({{< ref "nginx/admin-guide/dynamic-modules/opentelemetry.md" >}}) | +| [Perl](https://nginx.org/en/docs/http/ngx_http_perl_module.html)| Integrates Perl scripting for advanced customization. | [`nginx-plus-module-perl`]({{< ref "nginx/admin-guide/dynamic-modules/perl.md" >}}) | +| [Phusion Passenger](https://www.phusionpassenger.com/library/install/nginx/) | Application server for Node.js, Python, Ruby. | [`nginx-plus-module-passenger`]({{< ref "nginx/admin-guide/dynamic-modules/passenger-open-source.md" >}}) | +| [Prometheus-njs](https://github.com/nginx/nginx-prometheus-exporter) | Converts [NGINX Plus metrics](https://demo.nginx.com/swagger-ui/) into Prometheus format. | [`nginx-plus-module-prometheus`]({{< ref "nginx/admin-guide/dynamic-modules/prometheus-njs.md" >}}) | +| [RTMP](https://github.com/arut/nginx-rtmp-module) | Adds streaming capabilities (RTMP, HLS, MPEG-DASH, FFmpeg support).| [`nginx-plus-module-rtmp`]({{< ref "nginx/admin-guide/dynamic-modules/rtmp.md" >}}) | +| [Set-Misc](https://github.com/openresty/set-misc-nginx-module) | Adds `set_*` directives for scripting (extend NGINX [Rewrite](https://nginx.org/en/docs/http/ngx_http_rewrite_module.html) module). | [`nginx-plus-module-set-misc`]({{< ref "nginx/admin-guide/dynamic-modules/set-misc.md" >}}) | +| [SPNEGO for Kerberos](https://github.com/stnoonan/spnego-http-auth-nginx-module) | Adds support for [GSS‑API based](https://www.rfc-editor.org/rfc/rfc2743) SPNEGO/Kerberos authentication. | [`nginx-plus-module-auth-spnego`]({{< ref "nginx/admin-guide/dynamic-modules/spnego.md" >}}) | +| [XSLT](https://nginx.org/en/docs/http/ngx_http_xslt_module.html) | Applies XSLT transformations to XML responses. | [`nginx-plus-module-xslt`]({{< ref "nginx/admin-guide/dynamic-modules/xslt.md" >}}) | +{{< /bootstrap-table >}} + +### Community Dynamic Modules +Besides the modules provided in the official repository, a wide range of third-party modules is available through community-driven projects such as [Awesome NGINX GitHub project](https://github.com/agile6v/awesome-nginx#third-party-modules). Many of these modules can be [compiled as dynamic modules](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-plus/#install_modules_oss) and used with your NGINX Plus or NGINX Open Source deployments. + +### NGINX Certified Partner Dynamic Modules + In addition to the modules authored by NGINX and community third‑party developers, NGINX Certified Partner Modules are available for purchase from commercial third parties. Certified Modules are distributed and supported by their authors. NGINX has tested the modules extensively and [certifies](https://www.f5.com/go/partner/nginx-certified-module-program-documentation) that they do not interfere with standard NGINX Plus functionality. + +NGINX Certified Partner Modules can be found on the [F5 Dynamic Modules page](https://www.f5.com/go/product/nginx-modules?filter=module-author%3Anginx-certified-partner). -NGINX maintains a repository of dynamic modules for NGINX Plus. All modules in our repository are fully tested and certified for correct interoperation with NGINX Plus. - -There are many additional third‑party modules that are not included in the repository, but can be found in community projects like [awesome-nginx](https://github.com/agile6v/awesome-nginx#third-party-modules). You can [compile](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-plus/#install_modules_oss) many of them as dynamic modules. +### Prerequisites +To get started using dynamic modules, first install the [latest NGINX Plus release]({{< ref "nginx/releases.md" >}}), following the [installation instructions]({{< ref "nginx/admin-guide/installing-nginx/installing-nginx-plus.md" >}}). Dynamic modules are supported since [NGINX Plus Release 9]({{< ref "/nginx/releases.md#r9" >}}). - ## Getting Started with the Dynamic Modules Repository -You can access and download the modules in the NGINX Plus dynamic modules repository using standard package management tools such as `apt` and `yum`. For example, to install njs dynamic modules for Debian and Ubuntu, run the command: +You can access and install the modules from the NGINX Plus repository using standard package management tools such as `apt`, `dnf`, `pkg`, `yum`, or `zypper`. + + +### Displaying the List of Available Modules + +To see the list of available modules, run this command (for Debian and Ubuntu): ```shell -apt-get install nginx-plus-module-njs +apt update && \ +apt-cache search nginx-plus-module ``` -Then you include the [`load_module`](https://nginx.org/en/docs/ngx_core_module.html#load_module) directive in the NGINX Plus configuration file for each dynamic module. For example, to enable `njs` dynamic modules, specify the `load_module` directives in the top-level (“`main`”) context of the main NGINX Plus configuration file (**nginx.conf**): +The output of the command: -```nginx -load_module modules/ngx_http_js_module.so; -load_module modules/ngx_stream_js_module.so; -``` +```shell +nginx-plus-module-auth-spnego/stable + NGINX Plus 3rd-party kerberos authentication dynamic module -For module‑specific instructions, see the list of modules in the same section of the NGINX Plus Admin Guide as this article: - -- [Brotli]({{< ref "brotli.md" >}}) -- [Cookie-Flag]({{< ref "cookie-flag.md" >}}) -- [Encrypted-Session]({{< ref "encrypted-session.md" >}}) -- [FIPS Status Check]({{< ref "fips.md" >}}) -- [GeoIP]({{< ref "geoip.md" >}}) -- [GeoIP2]({{< ref "geoip2.md" >}}) -- [Headers-More]({{< ref "headers-more.md" >}}) -- [HTTP Substitutions Filter]({{< ref "http-substitutions-filter.md" >}}) -- [Image-Filter]({{< ref "image-filter.md" >}}) -- [Lua]({{< ref "lua.md" >}}) -- [njs Scripting Language]({{< ref "nginscript.md" >}}) -- [NGINX ModSecurity WAF]({{< ref "nginx-waf.md" >}}) -- [NGINX Developer Kit]({{< ref "ndk.md" >}}) -- [OpenTelemetry]({{< ref "opentelemetry.md" >}}) -- [OpenTracing]({{< ref "opentracing.md" >}}) -- [Phusion Passenger Open Source]({{< ref "passenger-open-source.md" >}}) -- [Perl]({{< ref "perl.md" >}}) -- [Prometheus-njs]({{< ref "prometheus-njs.md" >}}) -- [RTMP]({{< ref "rtmp.md" >}}) -- [Set-Misc]({{< ref "nginx/admin-guide/dynamic-modules/set-misc.md" >}}) -- [SPNEGO]({{< ref "spnego.md" >}}) -- [XSLT]({{< ref "xslt.md" >}}) +nginx-plus-module-brotli/stable + NGINX Plus 3rd-party brotli compression dynamic modules -### Prerequisites +nginx-plus-module-encrypted-session/stable + NGINX Plus 3rd-party encrypted session dynamic module -To get started using dynamic modules, first install the latest NGINX Plus release, following the [installation instructions]({{< ref "nginx/admin-guide/installing-nginx/installing-nginx-plus.md" >}}). Dynamic modules are supported in [NGINX Plus Release 9 (R9)]({{< ref "/nginx/releases.md#r9" >}}) and later. +nginx-plus-module-fips-check/stable + NGINX Plus 3rd-party FIPS status check dynamic module +nginx-plus-module-geoip/stable + NGINX Plus GeoIP dynamic modules - -### Displaying the List of Available Modules +nginx-plus-module-geoip2/stable + NGINX Plus 3rd-party GeoIP2 dynamic modules -To see the list of available modules, run this command (for Debian and Ubuntu): +nginx-plus-module-headers-more/stable + NGINX Plus 3rd-party headers-more dynamic module + +nginx-plus-module-image-filter/stable + NGINX Plus image filter dynamic module + +nginx-plus-module-lua/stable + NGINX Plus 3rd-party Lua dynamic modules + +nginx-plus-module-ndk/stable + NGINX Plus 3rd-party NDK dynamic module + +nginx-plus-module-njs/stable + NGINX Plus njs dynamic modules + +nginx-plus-module-opentracing/stable + NGINX Plus 3rd-party OpenTracing dynamic module + +nginx-plus-module-otel/stable + NGINX Plus OpenTelemetry dynamic module + +nginx-plus-module-passenger/stable + NGINX Plus 3rd-party Passenger dynamic module + +nginx-plus-module-perl/stable + NGINX Plus Perl dynamic module + +nginx-plus-module-prometheus/stable + NGINX Plus Prometheus exporter NJS module + +nginx-plus-module-rtmp/stable + NGINX Plus 3rd-party RTMP dynamic module + +nginx-plus-module-set-misc/stable + NGINX Plus 3rd-party set-misc dynamic module + +nginx-plus-module-subs-filter/stable + NGINX Plus 3rd-party substitution dynamic module + +nginx-plus-module-xslt/stable + NGINX Plus xslt dynamic module -```shell -apt-cache search nginx-plus-module ``` -The output of the command: +The command output also includes an optional debugging symbols package available for each module, for example, `nginx-plus-module-njs-dbg`. These packages are intended for troubleshooting and diagnostics and should be installed only in debugging or development environments. For more information, see [Debugging NGINX]({{< ref "nginx/admin-guide/monitoring/debugging.md" >}}). + +### Installing and loading the module + +To install a package, for example, [NGINX JavaScript (njs) dynamic modules]({{< ref "nginscript.md" >}}) for Ubuntu, run the command in a terminal: ```shell -nginx-plus-module-geoip - NGINX Plus, provided by NGINX, Inc. (GeoIP dynamic modules) -nginx-plus-module-geoip-dbg - Debugging symbols for the nginx-plus-module-geoip -nginx-plus-module-geoip2 - NGINX Plus, provided by NGINX, Inc. (3rd-party GeoIP2 dynamic modules) -nginx-plus-module-geoip2-dbg - Debugging symbols for the nginx-plus-module-geoip2 -nginx-plus-module-headers-more - NGINX Plus, provided by NGINX, Inc. (3rd-party headers-more dynamic module) -nginx-plus-module-headers-more-dbg - Debugging symbols for the nginx-plus-module-headers-more -nginx-plus-module-image-filter - NGINX Plus, provided by NGINX, Inc. (image filter dynamic module) -nginx-plus-module-image-filter-dbg - Debugging symbols for the nginx-plus-module-image-filter +sudo apt update && \ +sudo apt install nginx-plus-module-njs ``` -{{< note >}} There is an optional debugging symbols package available for every module. You can load and use the module without installing this package.{{< /note >}} +Then you include the [`load_module`](https://nginx.org/en/docs/ngx_core_module.html#load_module) directive in the NGINX Plus configuration file for each dynamic module. The path to the dynamic modules default directory depends on your operating system: + +- `/usr/lib64/nginx/modules/` for most Linux operating systems +- `/usr/lib/nginx/modules` for Debian, Ubuntu, Alpine +- `/usr/local/etc/nginx/modules` for FreeBSD +For example, to enable the `njs` dynamic modules after the installation of the `nginx-plus-module-njs` package: - -### NGINX Plus Certified Modules +- in a text editor, open the NGINX Plus configuration file: + - `/etc/nginx/nginx.conf` for Linux + - `/usr/local/etc/nginx/nginx.conf` for FreeBSD -In addition to modules authored by NGINX and community third‑party developers, the repository contains NGINX Plus Certified Modules which are available for purchase from commercial third parties. Certified Modules are distributed and supported by their authors. NGINX has tested the modules extensively and certifies that they do not interfere with standard NGINX Plus functionality. +- on the top-level (or the “`main`” context, before any `http` or `stream` blocks), specify the path to the target `.so` file with the [`load_module`](https://nginx.org/en/docs/ngx_core_module.html#load_module) directive: -NGINX Plus Certified Modules can be found on the [Dynamic Modules page](https://www.f5.com/go/product/nginx-modules?filter=module-author%3Anginx-certified-partner). + ```nginx + load_module modules/ngx_http_js_module.so; + load_module modules/ngx_stream_js_module.so; + http { + #... + } + + stream { + #... + } + ``` - ### Caveats -Some modules are not available for certain OS versions because of OS limitations. For details, see the [NGINX Plus Technical Specifications]({{< ref "nginx/technical-specs.md" >}}). +Certain dynamic modules may be unavailable on specific operating system versions due to platform limitations. For detailed compatibility information, see the [NGINX Plus Technical Specifications]({{< ref "nginx/technical-specs.md#dynamic-modules" >}}). - ## Compiling Your Own Dynamic Modules -To compile your own dynamic modules, please see our [blog](https://www.f5.com/company/blog/nginx/compiling-dynamic-modules-nginx-plus). +To compile your own dynamic modules, see the [Compiling Third-Party Dynamic Modules for NGINX Plus](https://www.f5.com/company/blog/nginx/compiling-dynamic-modules-nginx-plus) blogpost. - ## Uninstalling a Dynamic Module -To uninstall a dynamic module, please follow the [Uninstalling a dynamic module]({{< ref "uninstall.md" >}}) article. +To uninstall a dynamic module, see the [Uninstalling a dynamic module]({{< ref "uninstall.md" >}}) article. ## See Also @@ -126,4 +195,6 @@ To uninstall a dynamic module, please follow the [Uninstalling a dynamic module] - [NGINX Plus Technical Specifications]({{< ref "nginx/technical-specs.md" >}}) +- [Compiling Third-Party Dynamic Modules blogpost](https://www.f5.com/company/blog/nginx/compiling-dynamic-modules-nginx-plus) + - [Uninstalling a Dynamic Module]({{< ref "uninstall.md" >}}) diff --git a/content/nginx/admin-guide/dynamic-modules/nginx-waf.md b/content/nginx/admin-guide/dynamic-modules/nginx-waf.md index 2eef16e7..b47873cd 100644 --- a/content/nginx/admin-guide/dynamic-modules/nginx-waf.md +++ b/content/nginx/admin-guide/dynamic-modules/nginx-waf.md @@ -9,90 +9,11 @@ type: - how-to --- -The F5 NGINX ModSecurity web application firewall (WAF) is built on ModSecurity 3.0. +{{< note >}} The `nginx-plus-module-modsecurity` package is no longer available.{{< /note >}} - {{< note >}} The ModSecurity WAF module was deprecated since NGINX Plus [Release 29]({{< ref "nginx/releases.md#r29" >}}), and is no longer available since NGINX Plus [Release 32]({{< ref "nginx/releases.md#r32" >}}) {{< /note >}} +The ModSecurity WAF module was deprecated since [NGINX Plus Release 29]({{< ref "nginx/releases.md#r29" >}}), and is no longer available since [NGINX Plus Release 32]({{< ref "nginx/releases.md#r32" >}}). -## Installation - -1. Check the [Technical Specifications]({{< ref "nginx/technical-specs.md" >}}) page to verify that the module is supported by your operating system. - -2. Install the NGINX ModSecurity WAF module package `nginx-plus-module-modsecurity`. - - For Amazon Linux 2, CentOS, Oracle Linux, and RHEL: - - ```shell - sudo yum update && \ - sudo yum install nginx-plus-module-modsecurity - ``` - - {{< note >}} ppc64le is currently not supported for Amazon Linux, CentOS, Oracle Linux, and RHEL. {{< /note >}} - - For Amazon Linux 2023: - - ```shell - sudo dnf update && \ - sudo dnf install nginx-plus-module-modsecurity - ``` - - For Debian and Ubuntu: - - ```shell - sudo apt update && \ - sudo apt install nginx-plus-module-modsecurity - ``` - - {{< note >}} aarch64 and ppc64le is currently not supported for Ubuntu.{{< /note >}} - - For SLES: - - ```shell - sudo zypper refresh && \ - sudo zypper install nginx-plus-module-modsecurity - ``` - - For Alpine: - - ```shell - apk add nginx-plus-module-modsecurity - ``` - -## Configuration - -After installation you will need to enable and configure the module in NGINX Plus configuration file `nginx.conf`. - -1. Enable dynamic loading of the module with the [`load_module`](https://nginx.org/en/docs/ngx_core_module.html#load_module) directive specified in the top-level (“`main`”) context: - - ```nginx - load_module modules/ngx_http_modsecurity_module.so; - - http { - # ... - } - ``` - -2. Perform additional configuration as required by the [module](https://github.com/SpiderLabs/ModSecurity/wiki/Reference-Manual). - -3. Test the NGINX Plus configuration. In a terminal, type-in the command: - - ```shell - nginx -t - ``` - - Expected output of the command: - - ```shell - nginx: the configuration file /etc/nginx/nginx.conf syntax is ok - nginx: configuration file /etc/nginx/nginx.conf is successful - ``` - -4. Reload the NGINX Plus configuration to enable the module: - - ```shell - nginx -s reload - ``` - -5. [Configure](https://docs.nginx.com/nginx-waf/admin-guide/nginx-plus-modsecurity-waf-installation-logging/) the module. +To remove the module, follow the [Uninstalling a Dynamic Module]({{< ref "uninstall.md" >}}) instructions. ## More Info diff --git a/content/nginx/admin-guide/dynamic-modules/opentelemetry.md b/content/nginx/admin-guide/dynamic-modules/opentelemetry.md index ef9b4f0d..0e3d6c3f 100644 --- a/content/nginx/admin-guide/dynamic-modules/opentelemetry.md +++ b/content/nginx/admin-guide/dynamic-modules/opentelemetry.md @@ -13,7 +13,7 @@ type: [OpenTelemetry](https://opentelemetry.io/) (OTel) is an observability framework for monitoring, tracing, troubleshooting, and optimizing applications. OTel enables the collection of telemetry data from a deployed application stack. -The `nginx-plus-module-otel` module is an NGINX-authored dynamic module that enables NGINX Plus to send telemetry data to an OTel collector. The module supports [W3C](https://w3c.github.io/trace-context/) trace context propagation, OpenTelemetry Protocol (OTLP)/gRPC trace exports, and offers several advantages over existing OTel modules including: +The `nginx-plus-module-otel` module is an [NGINX-authored]({{< ref "nginx/admin-guide/installing-nginx/installing-nginx-plus.md#nginx-authored-dynamic-modules" >}}) dynamic module that enables NGINX Plus to send telemetry data to an OTel collector. The module supports [W3C](https://w3c.github.io/trace-context/) trace context propagation, OpenTelemetry Protocol (OTLP)/gRPC trace exports, and offers several advantages over existing OTel modules including: - Enhanced performance: with the module enabled, request processing overhead is limited to 10-15%, compared to other OpenTelemetry implementations, which can introduce performance degradation of up to 50%. @@ -30,7 +30,7 @@ The OpenTelemetry module supersedes the deprecated [OpenTracing]({{< ref "opentr ## Installation -The installation process closely follows the [NGINX Plus installation procedure]({{< ref "/nginx/admin-guide/installing-nginx/installing-nginx-plus.md" >}}). Prebuilt packages of the module for various Linux distributions can can be installed directly from the official repository. Prior to installation, you need to add the NGINX Plus package repository for your distribution and update the repository metadata. +The installation process closely follows the [NGINX Plus installation procedure]({{< ref "/nginx/admin-guide/installing-nginx/installing-nginx-plus.md" >}}). The module is available as the prebuilt `nginx-plus-module-otel` package for various Linux distributions and can be installed directly from the official NGINX Plus repository. Prior to installation, you need to add the NGINX Plus package repository for your distribution and update the repository metadata. 1. Check the [Technical Specifications]({{< ref "nginx/technical-specs.md" >}}) page to verify that the module is supported by your operating system. @@ -131,7 +131,7 @@ The installation process closely follows the [NGINX Plus installation procedure] 6. Ensure that your package management system is configured to pull packages from the NGINX Plus repository. See [Installing NGINX Plus]({{< ref "/nginx/admin-guide/installing-nginx/installing-nginx-plus.md" >}}) for details. -7. Update the repository information and install the package. In a terminal, run the appropriate command for your operating system. +7. Update the repository information and install the `nginx-plus-module-otel` package. In a terminal, run the appropriate command for your operating system. For CentOS, Oracle Linux, and RHEL: @@ -170,9 +170,9 @@ The installation process closely follows the [NGINX Plus installation procedure] The resulting `ngx_otel_module.so` dynamic module will be written to the following directory, depending on your operating system: - - `/usr/local/nginx/modules` for most Linux Distributions - - `/usr/lib/nginx/modules` for Ubuntu - - `/usr/local/etc/nginx/modules` for FreeBSD + - `/usr/lib64/nginx/modules/` for most Linux distributions + - `/usr/lib/nginx/modules` for Debian, Ubuntu, Alpine + - `/usr/local/etc/nginx/modules` for FreeBSD 8. Enable dynamic loading of the module. @@ -211,7 +211,9 @@ The installation process closely follows the [NGINX Plus installation procedure] ## Configuration - In a text editor, open the NGINX Plus configuration file (`/etc/nginx/nginx.conf` for Linux or `/usr/local/etc/nginx/nginx.conf` for FreeBSD). + In a text editor, open the NGINX Plus configuration file: + - `/etc/nginx/nginx.conf` for Linux + - `/usr/local/etc/nginx/nginx.conf` for FreeBSD For a complete list of directives, embedded variables, default span attributes, refer to the `ngx_otel_module` official documentation. diff --git a/content/nginx/admin-guide/dynamic-modules/opentracing.md b/content/nginx/admin-guide/dynamic-modules/opentracing.md index 935cbdde..81c64329 100644 --- a/content/nginx/admin-guide/dynamic-modules/opentracing.md +++ b/content/nginx/admin-guide/dynamic-modules/opentracing.md @@ -12,101 +12,13 @@ type: - how-to --- -{{< note >}} The module no longer available since F5 NGINX Plus [Release 34]({{< ref "nginx/releases.md#r34" >}}). The [OpenTelemetry]({{< ref "nginx/admin-guide/dynamic-modules/opentelemetry.md" >}}) module is available since NGINX Plus [Release 29]({{< ref "nginx/releases.md#r29" >}}) that incorporates the features of the OpenTracing module.{{< /note >}} +{{< note >}} The `nginx-plus-module-opentracing` package is no longer available.{{< /note >}} +The module was deprecated in [NGINX Plus Release 31]({{< ref "nginx/releases.md#r31" >}}) and removed in [NGINX Plus Release 34]({{< ref "nginx/releases.md#r34" >}}). Its functionality has been replaced with the [OpenTelemetry]({{< ref "nginx/admin-guide/dynamic-modules/opentelemetry.md" >}}) module. - -## Installation +To remove the module, follow the [Uninstalling a Dynamic Module]({{< ref "uninstall.md" >}}) instructions. -1. Check the [Technical Specifications]({{< ref "nginx/technical-specs.md" >}}) page to verify that the module is supported by your operating system. -2. Install the OpenTracing module package `nginx-plus-module-opentracing`. - - For Amazon Linux 2, CentOS, Oracle Linux, and RHEL: - - ```shell - sudo yum update && \ - sudo yum install nginx-plus-module-opentracing - ``` - - {{< note >}}the OpenTracing module cannot be installed on CentOS 6, Oracle Linux 6, and RHEL 6. {{< /note >}} - - For Amazon Linux 2023, AlmaLinux, Rocky Linux: - - ```shell - sudo dnf update && \ - sudo dnf install nginx-plus-module-opentracing - ``` - - For Debian and Ubuntu: - - ```shell - sudo apt update && \ - sudo apt install nginx-plus-module-opentracing - ``` - - For SLES: - - ```shell - sudo zypper refresh && \ - sudo zypper install nginx-plus-module-opentracing - ``` - - {{< note >}} the OpenTracing module cannot be installed on SLES 12. {{< /note >}} - - For Alpine: - - ```shell - apk add nginx-plus-module-opentracing - ``` - - For FreeBSD: - - ```shell - sudo pkg update && \ - sudo pkg install nginx-plus-module-opentracing - ``` - - - - -## Configuration - -After installation you will need to enable and configure the module in NGINX Plus configuration file `nginx.conf`. - -1. Enable dynamic loading of the module with the [`load_module`](https://nginx.org/en/docs/ngx_core_module.html#load_module) directive specified in the top-level (“`main`”) context: - - ```nginx - load_module modules/ngx_http_opentracing_module.so; - - http { - # ... - } - ``` - -2. Perform additional configuration as required by the [module](https://github.com/opentracing-contrib/nginx-opentracing). You will also need to [install a tracer](https://github.com/opentracing-contrib/nginx-opentracing#building-from-source) (“portable binary plugin”) for your selected service. - -3. Test the NGINX Plus configuration. In a terminal, type-in the command: - - ```shell - nginx -t - ``` - - Expected output of the command: - - ```shell - nginx: the configuration file /etc/nginx/nginx.conf syntax is ok - nginx: configuration file /etc/nginx/nginx.conf is successful - ``` - -4. Reload the NGINX Plus configuration to enable the module: - - ```shell - nginx -s reload - ``` - - - ## More Info - [NGINX plugin for OpenTracing Reference](https://github.com/opentracing-contrib/nginx-opentracing) diff --git a/content/nginx/admin-guide/dynamic-modules/uninstall.md b/content/nginx/admin-guide/dynamic-modules/uninstall.md index ec5874a7..ee504ae9 100644 --- a/content/nginx/admin-guide/dynamic-modules/uninstall.md +++ b/content/nginx/admin-guide/dynamic-modules/uninstall.md @@ -7,50 +7,69 @@ weight: 100 type: - how-to --- +You may need to uninstall a dynamic module in NGINX Plus in several scenarios: + +- The module is being replaced with a newer or alternative version. For example, the [OpenTracing]({{< ref "opentracing.md" >}}) module has been replaced by the [OpenTelemetry]({{< ref "opentelemetry.md" >}}) module. The [Cookie-Flag]({{< ref "cookie-flag.md" >}}) dynamic module has been superseded by natively supported [`proxy_cookie_flags`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cookie_flags) directive. + +- The module is no longer supported, for example, the [NGINX ModSecurity WAF]({{< ref "nginx-waf.md" >}}) module. + +- The operating system is not supported by the module. See the the [Dynamic Modules]({{< ref "nginx/technical-specs.md#dynamic-modules" >}}) section of the [NGINX Plus Technical Specifications]({{< ref "nginx/technical-specs.md#dynamic-modules" >}}). + +- The module it is no longer required, uninstalling it helps optimize resource usage and reduce maintenance overhead. + +- The module is causing runtime errors or configuration conflicts that affect stability or performance. + +- Security or compliance policies require removal, particularly in regulated environments where only approved or certified modules are allowed. ## Instructions -1. To uninstall a dynamic module: +To uninstall a dynamic module, run the appropriate command for your operating system in a terminal, replacing `` with the actual package name, for example, `nginx-plus-module-cookie-flag`. - For Amazon Linux 2, CentOS, Oracle Linux, and RHEL: +- For Amazon Linux 2, CentOS, Oracle Linux, and RHEL: ```shell - sudo yum remove + sudo yum remove ``` - For Amazon Linux 2023, AlmaLinux, Rocky Linux: +- For Amazon Linux 2023, AlmaLinux, Rocky Linux: ```shell - sudo dnf remove + sudo dnf remove ``` - For Debian and Ubuntu: +- For Debian and Ubuntu: ```shell - sudo apt remove + sudo apt remove ``` - For SLES: +- For SLES: ```shell - sudo zypper remove + sudo zypper remove ``` - For FreeBSD: +- For FreeBSD: ```shell - sudo pkg delete + sudo pkg delete ``` ## Configuration -After uninstalling the package, you will need to disable the module in F5 NGINX Plus configuration file `nginx.conf`. +After uninstalling the package, you will need to disable the module in the NGINX configuration file. -1. Disable dynamic loading of the module by removing the corrsponding [`load_module`](https://nginx.org/en/docs/ngx_core_module.html#load_module) directive. +1. In a text editor, open the NGINX Plus configuration file: + - `/etc/nginx/nginx.conf` for Linux + - `/usr/local/etc/nginx/nginx.conf` for FreeBSD -2. In NGINX Plus configuration file, remove all directives related to the dynamic module. +2. Disable dynamic loading of the module by removing the corresponding [`load_module`](https://nginx.org/en/docs/ngx_core_module.html#load_module) directive. -3. Test the NGINX Plus configuration. In a terminal, type-in the command: +3. Remove all directives related to the dynamic module. + +4. Save the configuration. + +5. Test the NGINX Plus configuration. In a terminal, type-in the command: ```shell nginx -t @@ -63,7 +82,7 @@ After uninstalling the package, you will need to disable the module in F5 NGINX nginx: configuration file /etc/nginx/nginx.conf is successful ``` -4. Reload the NGINX Plus configuration to enable the module: +5. Reload the NGINX Plus configuration: ```shell nginx -s reload @@ -76,6 +95,3 @@ After uninstalling the package, you will need to disable the module in F5 NGINX - [NGINX Dynamic Modules]({{< ref "dynamic-modules.md" >}}) - [NGINX Plus Technical Specifications]({{< ref "nginx/technical-specs.md" >}}) - -- [NGINX Plus Technical Specifications]({{< ref "nginx/technical-specs.md" >}}) - diff --git a/content/nginx/admin-guide/installing-nginx/installing-nginx-plus.md b/content/nginx/admin-guide/installing-nginx/installing-nginx-plus.md index 13c64f54..3ca6da52 100644 --- a/content/nginx/admin-guide/installing-nginx/installing-nginx-plus.md +++ b/content/nginx/admin-guide/installing-nginx/installing-nginx-plus.md @@ -391,91 +391,214 @@ NGINX Plus can be installed on the following versions of Debian or Ubuntu: ## Install Dynamically Loadable Modules {#install_modules} -NGINX Plus functionality can be extended with dynamically loadable modules that are not included in the prebuilt packages: - -- NGINX-authored dynamic modules – Modules developed and maintained by F5 NGINX. These modules can be installed directly from the official repository: - - [GeoIP]({{< ref "nginx/admin-guide/dynamic-modules/geoip.md" >}}) - - [Image-Filter]({{< ref "nginx/admin-guide/dynamic-modules/image-filter.md" >}}) - - [njs Scripting Language]({{< ref "nginx/admin-guide/dynamic-modules/nginscript.md" >}}) - - [OTel]({{< ref "nginx/admin-guide/dynamic-modules/opentelemetry.md" >}}) - - [Perl]({{< ref "nginx/admin-guide/dynamic-modules/perl.md" >}}) - - [XSLT]({{< ref "nginx/admin-guide/dynamic-modules/xslt.md" >}}) - -- NGINX-certified community dynamic modules – Popular third‑party modules tested and distributed by F5 NGINX, with installation and basic configuration support provided. These modules are also available directly from the official repository: - - [Brotli]({{< ref "nginx/admin-guide/dynamic-modules/brotli.md" >}}) - - [Encrypted-Session]({{< ref "nginx/admin-guide/dynamic-modules/encrypted-session.md" >}}) - - [FIPS Status Check]({{< ref "nginx/admin-guide/dynamic-modules/fips.md" >}}) - - [GeoIP2]({{< ref "nginx/admin-guide/dynamic-modules/geoip2.md" >}}) - - [Headers-More]({{< ref "nginx/admin-guide/dynamic-modules/headers-more.md" >}}) - - [HTTP Substitutions Filter]({{< ref "nginx/admin-guide/dynamic-modules/http-substitutions-filter.md" >}}) - - [Lua]({{< ref "nginx/admin-guide/dynamic-modules/lua.md" >}}) - - [NGINX Developer Kit]({{< ref "nginx/admin-guide/dynamic-modules/ndk.md" >}}) - - [OpenTelemetry]({{< ref "nginx/admin-guide/dynamic-modules/opentelemetry.md" >}}) - - [OpenTracing]({{< ref "nginx/admin-guide/dynamic-modules/opentracing.md" >}}) - - [Phusion Passenger]({{< ref "nginx/admin-guide/dynamic-modules/passenger-open-source.md" >}}) - - [Prometheus-njs]({{< ref "nginx/admin-guide/dynamic-modules/prometheus-njs.md" >}}) - - [RTMP]({{< ref "nginx/admin-guide/dynamic-modules/rtmp.md" >}}) - - [Set-Misc]({{< ref "nginx/admin-guide/dynamic-modules/set-misc.md" >}}) - - [SPNEGO]({{< ref "nginx/admin-guide/dynamic-modules/spnego.md" >}}) - -- Community dynamic modules – Modules written and distributed by third‑party members of the NGINX community. To use these modules, download the source code from the author's repository and [compile it against the NGINX Open Source version](#install_modules_oss) corresponding to your NGINX Plus version. These modules are not available in the official repository but can be found in different community resources such as [awesome-nginx GitHub project](https://github.com/agile6v/awesome-nginx#third-party-modules). - -### Install Dynamic Modules from Official Repository {#install_modules_plus} - -NGINX‑authored and NGINX‑certified dynamic modules can be installed directly from the modules repository. To install the modules: +NGINX Plus functionality can be extended with dynamically loadable modules. They can be added or updated independently of the core binary, enabling powerful capabilities such as advanced security, traffic shaping, telemetry, embedded scripting, geolocation, and many more. + +Dynamic modules are shared object files (`.so`) that can be loaded at runtime using the [`load_module`](https://nginx.org/en/docs/ngx_core_module.html#load_module) directive in the NGINX configuration. + + ### Types of dynamic modules + +{{< bootstrap-table "table table-striped table-bordered" >}} +| Type | Description | Distribution Method | F5 NGINX Support| +|-------------------------|--------------------|-----------------------|-----------------| +| [NGINX-authored](#nginx-authored-dynamic-modules) | Developed and distributed by NGINX | Packaged binaries from `nginx-plus` official repo | Full support | +| [NGINX-certified Community](#nginx-certified-community-dynamic-modules) | Tested and distributed by NGINX | Packaged binaries from `nginx-plus` official repo | Installation and basic configuration support | +| [NGINX Certified Partner](#nginx-certified-partner-dynamic-modules) | Partner-built modules verified through [NGINX’s certification](https://www.f5.com/go/partner/nginx-certified-module-program-documentation) | Provided by partners | Provided by partners | +| [Community](#community-dynamic-modules) | Developed and distributed by third‑party contributors | [Self-compiled](#install_modules_oss) | No support| +{{< /bootstrap-table >}} + + ### NGINX-authored dynamic modules + +NGINX-authored dynamic modules are developed and officially maintained by the F5 NGINX team. These modules are available as packaged binaries for various operating systems and can be installed [from the `nginx-plus` repository](#install-from-official-repository). + +{{< bootstrap-table "table table-striped table-bordered" >}} +| Name | Description | Package name | +|---------------------------------|-----------------------------------|--------------------| +| [GeoIP](https://nginx.org/en/docs/http/ngx_http_geoip_module.html) | Enables IP-based geolocation using the precompiled MaxMind databases. | [`nginx-plus-module-geoip`]({{< ref "nginx/admin-guide/dynamic-modules/geoip.md" >}}) | +| [Image-Filter](https://nginx.org/en/docs/http/ngx_http_image_filter_module.html) | Adds on-the-fly support for JPEG, GIF, PNG, and WebP image resizing and cropping. | [`nginx-plus-module-image-filter`]({{< ref "nginx/admin-guide/dynamic-modules/image-filter.md" >}}) | +| [njs Scripting Language](https://nginx.org/en/docs/njs/) | Adds JavaScript-like scripting for advanced server-side logic in NGINX configuration file. | [`nginx-plus-module-njs`]({{< ref "nginx/admin-guide/dynamic-modules/nginscript.md" >}}) | +| [OpenTelemetry](https://github.com/nginxinc/nginx-otel) | Adds distributed tracing support via OpenTelemetry. | [`nginx-plus-module-otel`]({{< ref "nginx/admin-guide/dynamic-modules/opentelemetry.md" >}}) | +| [Perl](https://nginx.org/en/docs/http/ngx_http_perl_module.html)| Integrates Perl scripting for advanced customization. | [`nginx-plus-module-perl`]({{< ref "nginx/admin-guide/dynamic-modules/perl.md" >}}) | +| [XSLT](https://nginx.org/en/docs/http/ngx_http_xslt_module.html) | Applies XSLT transformations to XML responses. | [`nginx-plus-module-xslt`]({{< ref "nginx/admin-guide/dynamic-modules/xslt.md" >}}) | +{{< /bootstrap-table >}} + + ### NGINX-certified community dynamic modules + +NGINX-certified community dynamic modules are popular third‑party modules tested and distributed by F5 NGINX, with installation and basic configuration support provided. They are also distributed as precompiled packages for various operating systems and can be installed [from the `nginx-plus` repository](#install-from-official-repository). + +{{< bootstrap-table "table table-striped table-bordered" >}} +| Name | Description | Package name | +|---------------------------------|-----------------------------------|--------------------| +| [Brotli](https://github.com/google/ngx_brotli) | Brotli compression support with modules for dynamic compression and for serving pre-compressed `.br` files. | [`nginx-plus-module-brotli`]({{< ref "nginx/admin-guide/dynamic-modules/brotli.md" >}}) | +| [Encrypted-Session](https://github.com/openresty/encrypted-session-nginx-module) | AES-256 based encryption/decryption of NGINX variables. | [`nginx-plus-module-encrypted-session`]({{< ref "nginx/admin-guide/dynamic-modules/encrypted-session.md" >}}) | +| [FIPS Status Check](https://github.com/ogarrett/nginx-fips-check-module) | Verifies if OpenSSL is operating in FIPS mode. | [`nginx-plus-module-fips-check`]({{< ref "nginx/admin-guide/dynamic-modules/fips.md" >}})| +| [GeoIP2](https://github.com/leev/ngx_http_geoip2_module) | Uses MaxMind GeoIP2 for enhanced geolocation. | [`nginx-plus-module-geoip2`]({{< ref "nginx/admin-guide/dynamic-modules/geoip2.md" >}})| +| [Headers-More](https://github.com/openresty/headers-more-nginx-module) | Extends the NGINX [Headers](https://nginx.org/en/docs/http/ngx_http_headers_module.html) module to modify request and response headers. | [`nginx-plus-module-headers-more`]({{< ref "nginx/admin-guide/dynamic-modules/headers-more.md" >}}) | +| [HTTP Substitutions Filter](https://github.com/yaoweibin/ngx_http_substitutions_filter_module) | Enables regex and string-based substitutions in response bodies. | [`nginx-plus-module-subs-filter`]({{< ref "nginx/admin-guide/dynamic-modules/http-substitutions-filter.md" >}}) | +| [Lua](https://github.com/openresty/lua-nginx-module) | Embeds Lua programming language. | [`nginx-plus-module-lua`]({{< ref "nginx/admin-guide/dynamic-modules/lua.md" >}})| +| [NGINX Developer Kit](https://github.com/vision5/ngx_devel_kit) | Provides helper macros for module development. | [`nginx-plus-module-ndk`]({{< ref "nginx/admin-guide/dynamic-modules/ndk.md" >}}) | +| [Phusion Passenger](https://www.phusionpassenger.com/library/install/nginx/) | Application server for Node.js, Python, Ruby. | [`nginx-plus-module-passenger`]({{< ref "nginx/admin-guide/dynamic-modules/passenger-open-source.md" >}}) | +| [Prometheus-njs](https://github.com/nginx/nginx-prometheus-exporter) | Converts [NGINX Plus metrics](https://demo.nginx.com/swagger-ui/) into Prometheus format. | [`nginx-plus-module-prometheus`]({{< ref "nginx/admin-guide/dynamic-modules/prometheus-njs.md" >}}) | +| [RTMP](https://github.com/arut/nginx-rtmp-module) | Adds streaming capabilities (RTMP, HLS, MPEG-DASH, FFmpeg support).| [`nginx-plus-module-rtmp`]({{< ref "nginx/admin-guide/dynamic-modules/rtmp.md" >}}) | +| [Set-Misc](https://github.com/openresty/set-misc-nginx-module) | Adds `set_*` directives for scripting (extend NGINX [Rewrite](https://nginx.org/en/docs/http/ngx_http_rewrite_module.html) module). | [`nginx-plus-module-set-misc`]({{< ref "nginx/admin-guide/dynamic-modules/set-misc.md" >}}) | +| [SPNEGO for Kerberos](https://github.com/stnoonan/spnego-http-auth-nginx-module) | Adds support for [GSS‑API based](https://www.rfc-editor.org/rfc/rfc2743) SPNEGO/Kerberos authentication. | [`nginx-plus-module-auth-spnego`]({{< ref "nginx/admin-guide/dynamic-modules/spnego.md" >}}) | +{{< /bootstrap-table >}} + +### Install from official repository +[NGINX‑authored](#nginx-authored-dynamic-modules) and [NGINX‑certified community](#nginx-certified-community-dynamic-modules) dynamic modules can be installed as packaged binaries directly from the official `nginx-plus` repository. + +To install a binary package, run the command in a terminal that corresponds to your operating system, replacing `` with the actual binary package name, for example, `nginx-plus-module-njs`. - For RHEL, Amazon Linux 2, CentOS, Oracle Linux: ```shell - yum update - yum install + sudo yum update && \ + sudo yum install ``` + The resulting `.so` file will be installed to: `/usr/lib64/nginx/modules/` - For Amazon Linux 2023, AlmaLinux and Rocky Linux: ```shell - dnf update - dnf install + sudo dnf update && \ + sudo dnf install ``` + The resulting `.so` file will be installed to: `/usr/lib64/nginx/modules/` - For Debian and Ubuntu: ```shell - apt update - apt install + sudo apt update && \ + sudo apt install ``` + The resulting `.so` file will be installed to: `/usr/lib/nginx/modules` - For FreeBSD: ```shell - pkg update - pkg install + sudo pkg update && \ + sudo pkg install ``` + The resulting `.so` file will be installed to: `/usr/local/etc/nginx/modules` -- For SLES: +- For SUSE Linux Enterprise: ```shell - zypper refresh - zypper install + sudo zypper refresh && \ + sudo zypper install ``` + The resulting `.so` file will be installed to: `/usr/lib64/nginx/modules/` - For Alpine Linux: ```shell - sudo apk update + sudo apk update && \ sudo apk add ``` + The resulting `.so` file will be installed to: `/usr/lib/nginx/modules` -See [NGINX Plus Dynamic Modules]({{< ref "nginx/admin-guide/dynamic-modules/dynamic-modules.md" >}}) for detailed installation instructions for each dynamic module. +For detailed description and installation steps for each dynamic module, see [NGINX Plus Dynamic Modules]({{< ref "nginx/admin-guide/dynamic-modules/dynamic-modules.md" >}}). -Note that some modules may not be available for certain OS versions because of operating system limitations. For details and descriptions of the modules, see the [NGINX Plus Technical Specifications]({{< ref "nginx/technical-specs.md" >}}). +Some modules may not be available on specific operating systems due to platform-level limitations. For detailed modules compatibility, see the [Dynamic Modules]({{< ref "nginx/technical-specs.md#dynamic-modules" >}}) section of the [NGINX Plus Technical Specifications]({{< ref "nginx/technical-specs.md" >}}). -After installing the module, you need to enable it in the NGINX Plus configuration file. For more information, see [Enabling Dynamic Modules](#enable_dynamic). +After installing the module, you will need to: + +- enable it with the [`load_module`](https://nginx.org/en/docs/ngx_core_module.html#load_module) directive +- configure it according to the module's documentation + +### Enabling Dynamic Modules {#enable_dynamic} + +To enable a dynamic module: + +1. In a text editor, open the NGINX Plus configuration file: + - `/etc/nginx/nginx.conf` for Linux + - `/usr/local/etc/nginx/nginx.conf` for FreeBSD + +1. On the top-level (or the “`main`” context, before any `http` or `stream` blocks), specify the path to the `.so` file with the [`load_module`](https://nginx.org/en/docs/ngx_core_module.html#load_module) directive. By default, the files are expected to be in the `/modules` directory. The path to the directory depends on your operating system: + + - `/usr/lib64/nginx/modules/` for most Linux operating systems + - `/usr/lib/nginx/modules` for Debian, Ubuntu, Alpine + - `/usr/local/etc/nginx/modules` for FreeBSD + + If there are several dynamic modules, specify each module with a separate `load_module` directive: + + ```nginx + load_module modules/.so; + load_module modules/.so; + + http { + #... + } + + stream { + #... + } + ``` + +1. Save the changes. + +1. Check the new configuration for syntactic validity: + + ```shell + nginx -t + ``` + +1. Reload the NGINX Plus configuration: + + ```shell + nginx -s reload + ``` + + After installing the module, you will need to configure the module in the NGINX Plus configuration file. Follow the usage and setup instructions provided in the module’s official documentation. + + ### NGINX Certified Partner dynamic modules -### Install NGINX Community Modules {#install_modules_oss} +NGINX Certified Partner dynamic modules are partner-built extensions that enhance NGINX Plus with advanced features such as security, identity and access management, device detection, application delivery, and many more. These modules are verified through [NGINX’s certification process](https://www.f5.com/go/partner/nginx-certified-module-program-documentation). Installation packages, documentation, and support are provided directly by the partners. + +{{< bootstrap-table "table table-striped table-bordered" >}} +| Name | Description | Commercial Support | +|---------------------------------|-----------------------------------|--------------------| +| [CQ botDefence](https://www.cequence.ai/contact-us/) | Simplify traffic analysis to prevent fraud and theft that may result from automated bot attacks against your public-facing web, mobile, and API-based applications. | [Support](https://www.cequence.ai/demo/) provided by [Cequence](https://www.cequence.ai) | +| [Curity Identity Server](https://developer.curity.io/) | Powerful OAuth and OpenID Connect server, used for logging in and securing millions of users, access to API and mobile apps over APIs and microservices. | [Support](https://curity.io/support/professional-services/) and docs [[1]](https://curity.io/resources/learn/nginx-phantom-token-module/), [[2]](https://curity.io/resources/learn/nginx-oauth-proxy/) provided by [Curity](https://curity.io/support/professional-services/) | +| [DeviceAtlas ](https://deviceatlas.com/deviceatlas-nginx-module) | Detect what devices users are using, including smartphones, laptops, and weareable devices, and use this data to deliver customized experiences. | [Support](https://deviceatlas.com/resources/support) and [docs](https://docs.deviceatlas.com/apis/enterprise/c/3.1.3/README.Nginx.html) provided by [DeviceAtlas](https://deviceatlas.com/resources/support) | +| [ForgeRock Policy Agent](https://backstage.forgerock.com/downloads/browse/am/featured/web-agents) | In conjunction with ForgeRock Access Management, allows you to authenticate your application and API access. | [Support](https://support.pingidentity.com/s/) and [docs](https://backstage.forgerock.com/docs/openam-web-policy-agents/2023.9/installation-guide/install-nginx.html) provided by [PingIdentity](https://www.pingidentity.com) | +| [HUMAN Security for F5 NGINX](https://www.humansecurity.com/contact-us/) | Provides the required enforcement layer to protect websites and apps from modern automated security threats. | Support provided by [HUMAN Security](https://www.humansecurity.com/) | +| [IDFConnect SSO/Rest](http://www.idfconnect.com/about/contact/) | Integrates your web access management platform's full capabilities with NIGNX Plus. | [Support](http://www.idfconnect.com/about/contact/) and [docs](https://www.idfconnect.com/nginx-ssorest-plugin/) provided by [IDFConnect](http://www.idfconnect.com) | +| [OPSWAT](https://www.f5.com/go/product/nginx-modules/opswat) | Scalable solutions to protect your networks and applications from malware and unknown (zero-day) malicious file content. | [Support](https://www.opswat.com/support) and [docs](https://www.opswat.com/docs/mdicap/integrations/nginx-integration-module) provided by [OPSWAT](https://www.opswat.com/) | +| [Passenger Enterprise](https://www.phusionpassenger.com/features) | An application server with support for Meteor, Node.js, Python, and Ruby apps. | [Support](https://www.phusionpassenger.com/support) and [docs](https://www.phusionpassenger.com/docs/advanced_guides/install_and_upgrade/nginx/install_as_nginx_module.html) provided by [Phusion](https://www.phusionpassenger.com/) | +| [Ping Access](https://support.pingidentity.com/s/marketplace-integration/a7i1W0000004ICRQA2/pingaccess-agent-for-nginx-plus) | Centralized management of access security with advanced contextual policies to secure your mobile and web properties in any domain. | [Support](https://support.pingidentity.com/s/) and [docs](https://docs.pingidentity.com/pingaccess/latest/agents_and_integrations/pa_agent_for_nginx.html) provided by [PingIdentity](https://www.pingidentity.com) | +| [PingIntelligence](https://hub.pingidentity.com/datasheets/3742-pingintelligence-apis) | A complete solution to secure an organization's API across on-premises, public and private clouds, and hybrid IT environments. | [Support](https://support.pingidentity.com/s/) and [docs](https://docs.pingidentity.com/pingintelligence/5.1/pingintelligence_integrations/pingintelligence_nginx_plus_integration.html) provided by [PingIdentity](https://www.pingidentity.com) | +| [Seer Box by Plurbius One](https://seerbox.it/en/) | Cloud-native web application security manager which provides thorough monitoring and protection capabilities. | Support provided by [Seer Box](https://support.seerbox.it/) | +| [Signal Sciences](https://docs.fastly.com/en/ngwaf/about-the-nginx-module) | Intelligently detects malicious requests and blocks them without false positives, while the patented fail-open architecture allows legitimate requests through. | [Support](https://support.fastly.com/s/) and [docs](https://docs.fastly.com/en/ngwaf/installing-the-nginx-dynamic-module) provided by [Fastly](https://www.fastly.com/)| +| [Wallarm](https://docs.wallarm.com/updating-migrating/nginx-modules/) | The Wallarm WAF provides enterprise-grade protection against advanced Layer 7 application attacks. | [Support](https://www.wallarm.com/support) and [docs](https://docs.wallarm.com/installation/nginx/all-in-one/) provided by [Wallarm](https://wallarm.com/) | +| [WURFL InFuse](https://www.scientiamobile.com/secondary-products/wurfl-infuze-module-for-nginx-plus/) | Give developers the most advanced, accurate, and high-performance device detection in the industry. | [Support](https://www.scientiamobile.com/support/) and [docs](https://docs.scientiamobile.com/documentation/infuze/infuze-nginx-plus-module-user-guide) provided by [Scientiamobile](https://www.scientiamobile.com/) | +| [51Degrees Device Detection](https://github.com/51Degrees/device-detection-nginx) | Improve speed of response and accuracy, delivering an optimal user experience and high-fidelity analysis. | [Support](https://51degrees.com/pricing/index) and [docs](https://github.com/51Degrees/device-detection-nginx/blob/main/README.md) provided by [51Degrees](https://51degrees.com/about-us) | +{{< /bootstrap-table >}} + +The complete list of Certified Partner Modules can be found on the [F5.com Dynamic Modules](https://www.f5.com/go/product/nginx-modules?filter=module-author%3Anginx-certified-partner) page. + + ### Community dynamic modules + +Community dynamic modules are open source extensions developed and distributed by third‑party contributors of the NGINX community. + +These modules are not available in the official NGINX repository. To use them, you must download the source code from the module's repository and [compile it against the NGINX Open Source version](#install_modules_oss) that matches your NGINX Plus version. + +The lists of community modules can be found across different community-driven resources, for example, [Awesome NGINX GitHub project](https://github.com/agile6v/awesome-nginx#third-party-modules). + +### Installing a community dynamic module {#install_modules_oss} For a community dynamic module to work with NGINX Plus, it must be compiled alongside the corresponding version of NGINX Open Source. +1. Find out the NGINX Open Source version that matches your NGINX Plus version. In a terminal, run the command: + + ```shell + nginx -v + ``` + Expected output of the command: + + ```shell + nginx version: nginx/1.27.4 (nginx-plus-r34) + ``` + 1. Prepare the build environment. We strongly recommend compiling dynamic modules on a separate system, referred to as the “build environment”. This approach minimizes the risk and complexity for the system where NGINX Plus will be upgraded, referred to as the “production environment”. The build environment should meet the following requirements: @@ -491,14 +614,14 @@ For a community dynamic module to work with NGINX Plus, it must be compiled alo - For Debian and Ubuntu: ```shell - sudo apt update + sudo apt update && \ sudo apt install gcc make libpcre3-dev zlib1g-dev ``` - For CentOS, Oracle Linux, and RHEL: ```shell - sudo yum update + sudo yum update && \ sudo yum install gcc make pcre-devel zlib-devel ``` @@ -522,45 +645,45 @@ For a community dynamic module to work with NGINX Plus, it must be compiled alo 1. Compile the dynamic module. - First establish binary compatibility by running the `configure` script with the `‑‑with‑compat` option. Then compile the module with `make modules`. + First, establish binary compatibility by running the `configure` script with the `‑‑with‑compat` option. Then compile the module with `make modules`. ```shell - cd nginx-1.27.4/ - ./configure --with-compat --add-dynamic-module=../ + cd nginx-1.27.4/ && \ + ./configure --with-compat --add-dynamic-module=../ && \ make modules ``` - The **.so** file generated by the build process is placed in the **objs** subdirectory + The **.so** file generated by the build process is placed in the **objs** subdirectory: ```shell ls objs/*.so - objs/ngx_http_hello_world.so ``` -1. Make a copy of the module file and include the NGINX Open Source version in the filename. This makes it simpler to manage multiple versions of a dynamic module in the production environment. - + Expected command output: ```shell - cp objs/ngx_http_hello_world.so ./ngx_http_hello_world_1.27.4.so + objs/ngx_http_hello_world_module.so ``` -### Enabling Dynamic Modules {#enable_dynamic} - -Dynamic modules are located in the **/etc/nginx/modules** directory, which is created automatically at NGINX Plus installation. +1. Make a copy of the module file and include the NGINX Open Source version in the filename. This makes it simpler to manage multiple versions of a dynamic module in the production environment. -To enable a dynamic module: + ```shell + cp objs/ngx_http_hello_world_module.so ./ngx_http_hello_world_module_1.27.4.so + ``` -1. In the `main` (top-level) context in **/etc/nginx/nginx.conf**, add a [load_module](https://nginx.org/en/docs/ngx_core_module.html#load_module) directive for each dynamically loadable module you installed. +1. Transfer the resulting `.so` file from your build environment to the production environment. - ```nginx - load_module modules/.so; - ``` +1. In your production environment, copy the resulting `.so` file to the dynamic modules directory. The path to the directory depends on your operating system: -1. Check the new configuration for syntactic validity and reload NGINX Plus. + - `/usr/lib64/nginx/modules/` for most Linux operating systems + - `/usr/lib/nginx/modules` for Debian, Ubuntu, Alpine + - `/usr/local/etc/nginx/modules` for FreeBSD ```shell - nginx -t && nginx -s reload + sudo cp ngx_http_hello_world_module_1.27.4.so /usr/local/nginx/modules/ngx_http_hello_world_module_1.27.4.so ``` +After installing the module, you need to enable it in the NGINX Plus configuration file. For more information, see [Enabling Dynamic Modules](#enable_dynamic). + ## NGINX Plus Unprivileged Installation {#unpriv_install} In some environments, access to the root account is restricted for security reasons. On Linux systems, this limitation prevents the use of package managers to install NGINX Plus without root privileges. @@ -853,11 +976,11 @@ To upgrade your NGINX Plus installation to the newest version: The upgrade procedure depends on how the module was supplied and installed. -- NGINX‑authored and NGINX‑certified community dynamic modules are updated automatically together with NGINX Plus. +- [NGINX‑authored](#nginx-authored-dynamic-modules) and [NGINX‑certified community](#nginx-certified-community-dynamic-modules) dynamic modules are updated automatically together with NGINX Plus. {{< note >}} For FreeBSD, each NGINX‑authored and NGINX‑certified module must be updated separately using FreeBSD package management tool. {{< /note >}} -- Community dynamic modules must be recompiled against the corresponding NGINX Open Source version. See [Installing NGINX Community Modules](#install_modules_oss). +- [Community](#community-dynamic-modules) dynamic modules must be recompiled against the corresponding NGINX Open Source version. See [Installing NGINX Community Modules](#install_modules_oss). ## Explore Related Topics