为 NGINX 和 NGINX Plus 编译第三方动态模块

为 NGINX 和 NGINX Plus 编译第三方动态模块

编辑器 - 宣布动态模块支持的原始版本（在 NGINX 开源 1.9.11 中，2016 年 2 月）的博客文章重定向到这里。该帖子中描述的构建过程已被弃用。

这篇文章是关于在 NGINX Open Source 和 NGINX Plus 中使用第三方动态模块的两部分系列文章的一部分。

• 这篇文章提供了编译第三方动态模块的分步说明，这些模块可以在运行时由 NGINX Open Source 或 NGINX Plus 加载。
• 第二篇文章提供了为生产环境自动构建第三方动态模块的指导和工具。它解释了如何为包括版本依赖性检查的第三方动态模块创建可安装包。

NGINX Open Source 1.11.5 和NGINX Plus Release R11引入了动态模块的二进制兼容性。本文解释了如何编译第三方模块以在开发环境中与 NGINX Open Source 和 NGINX Plus 一起使用。有关在生产环境中构建、部署和升级第三方动态模块的说明，请参阅为动态模块创建可安装包。

为简洁起见，本文的其余部分仅指 NGINX Plus，除非它与 NGINX 开源之间的差异相关。除非另有说明，所有关于 NGINX Plus 的声明也适用于 NGINX 开源。

动态模块概述

可以加载到 NGINX Plus 中的模块是用 C 编写的，并且符合NGINX Wiki 上扩展 NGINX中描述的 API 。有一个庞大的第三方模块生态系统，从语言解释器到安全解决方案，其中一些包含并支持在 NGINX Plus 中。

其他第三方模块，以及您自己创建的模块，需要独立编译并在运行时动态加载到 NGINX Plus 中。您可以通过针对 NGINX 开源构建这些模块来编译这些模块以与 NGINX Plus 一起使用，如下面的两个示例所示：

1. 获取匹配的 NGINX 开源版本
2. 获取模块源并根据需要更改模块的配置文件
3. 使用命令的--with-compat参数构建针对 NGINX 开源版本的动态模块configure
4. 将生成的动态模块（.so文件）加载到 NGINX Plus 中并像使用内置模块一样使用它

示例：一个简单的“Hello World”模块

此示例使用一个简单的Hello World 模块来展示如何更新模块的源代码并将其加载到 NGINX Plus 中。“Hello World”模块实现了一个简单的指令 ( hello_world)，它用简单的消息响应请求。

第一步：获取 NGINX 开源版本

1. 确定与您的 NGINX Plus 安装相对应的 NGINX 开源版本。在这个例子中，它是 NGINX 1.11.5。

   $ 

   nginx -v

   
   nginx version: nginx/1.11.5 (nginx-plus-r11)

2. 在nginx.org/download下载相应的 NGINX 开源包：

   $ 

   wget https://nginx.org/download/nginx-1.11.5.tar.gz

   
   $ 

   tar -xzvf nginx-1.11.5.tar.gz

第二步：获取模块源

1. 从GitHub获取“Hello World”NGINX 模块的源代码：

   $ 

   git clone https://github.com/perusio/nginx-hello-world-module.git

2. 模块的配置shell 文件定义了它的构建方式，动态模块的格式不同于静态构建到 NGINX 开源二进制文件中的模块。

   修改文件nginx-hello-world-module/config以包含以下内容：

   ngx_addon_name=ngx_http_hello_world_module
   
   if test -n "$ngx_module_link"; then
       ngx_module_type=HTTP
       ngx_module_name=ngx_http_hello_world_module
       ngx_module_srcs="$ngx_addon_dir/ngx_http_hello_world_module.c"
   
       . auto/module
   else
       HTTP_MODULES="$HTTP_MODULES ngx_http_hello_world_module"
       NGX_ADDON_SRCS="$NGX_ADDON_SRCS $ngx_addon_dir/ngx_http_hello_world_module.c"
   fi

有关编译动态模块的详细信息，包括从旧格式更新模块配置文件的说明，请参阅NGINX Wiki。

第三步：编译动态模块

1. configure通过首先运行带有参数的脚本来 编译模块--with-compat，这将创建一个 NGINX Open Source 和 NGINX Plus 都支持的标准构建环境。然后运行make modules构建模块：

   $ 

   cd nginx-1.11.5/

   
   $ 

   ./configure --with-compat --add-dynamic-module=../nginx-hello-world-module

   
   $ 

   make modules

2. 将模块库（.so文件）复制到/etc/nginx/modules：

   $ 

   sudo cp objs/ngx_http_hello_world_module.so /etc/nginx/modules/

第 4 步：加载和使用模块

1. 要将模块加载到 NGINX Plus 中，请在nginx.confload_module配置文件的顶级（主）上下文中添加指令（不在or上下文中）：httpstream

   load_module modules/ngx_http_hello_world_module.so;

2. 在http上下文中，使用 Hello World 模块提供的指令添加一个location块。hello_world对位置的请求返回响应hello world。

   server {
       listen 80;
   
       location / {
            hello_world;
       }
   }

3. 重新加载您的 NGINX Plus 配置并通过一个简单的请求对其进行测试：

   $ 

   nginx -s reload

   
   $ 

   curl http://localhost/

   
   hello world

示例：NAXSI Web 应用程序防火墙

NAXSI是一个易于使用的高性能 Web 应用程序防火墙 (WAF)，它使用启发式算法和评分系统来识别可疑请求，例如 XSS 和 SQL 注入攻击。

NAXSI 源代码已更新以符合配置shell 文件的新格式，因此为 NGINX Plus 构建动态模块非常简单。该过程基于NAXSI 安装说明：

$ 

git clone https://github.com/nbs-system/naxsi.git

$ 

cd nginx-1.11.5/

$ 

./configure --with-compat --add-dynamic-module=../naxsi/naxsi_src

$ 

make modules

$ 

sudo cp objs/ngx_http_naxsi_module.so /etc/nginx/modules

通过将指令添加到nginx.conf文件load_module的主上下文中，将模块加载到 NGINX Plus 核心中：

load_module modules/ngx_http_naxsi_module.so;

NAXSI 配置在项目文档中有详细描述。以下 NGINX 配置说明了该模块的运行情况：

# Edit this 'include' directive to point to your naxsi_core.rules file
include /home/owen/src/naxsi/naxsi_config/naxsi_core.rules;

server {
    listen 80;

    location / {
        root /usr/share/nginx/html;

        # Enable NAXSI
        SecRulesEnabled;

        # Define where blocked requests go
        DeniedUrl "/50x.html";

        # CheckRules, determining when NAXSI needs to take action
        CheckRule "$SQL >= 8" BLOCK;
        CheckRule "$RFI >= 8" BLOCK;
        CheckRule "$TRAVERSAL >= 4" BLOCK;
        CheckRule "$EVADE >= 4" BLOCK;
        CheckRule "$XSS >= 8" BLOCK;

        # Don’t forget the error_log, where blocked requests are logged
        error_log /tmp/naxsi.log;
    }

    error_page   500 502 503 504  /50x.html;
}

您可以通过一对简单的 HTTP 请求来验证 NAXSI 的正确操作：

• curl http://localhost/返回存储在/usr/share/nginx/html中的标准 NGINX Plus 索引页面。
• curl "http://localhost/?a=<>"触发 NAXSI 的 XSS 检测并阻止请求，从/usr/share/nginx/html返回标准的50x.html错误页面。它还会将消息记录到.error_log

对于生产部署，您还可以在https://github.com/nbs-system/naxsi/tags下载签名的 NAXSI 版本，并以类似的方式编译它们。

我们如何在 NGINX Plus 中支持动态模块

注意：本节中的信息仅适用于 NGINX Plus。预构建的 NGINX 开源包附带的动态模块集可能与 NGINX Plus 附带的动态模块不同。与 NGINX 开源代码一起使用的动态模块的支持方式与 NGINX 源代码和预构建的二进制文件相同。

NGINX Plus 附带了许多动态模块，您也可以直接从我们的模块存储库中下载这些模块。有关列表，请参阅动态模块页面。这些模块有两种类型：

• NGINX Plus 模块由 NGINX 工程团队编写和/或维护。出于技术原因（例如，它们有额外的依赖项）或因为它们处于预览状态，我们不会将它们包含在 NGINX Plus 中。预览模块正在积极开发中，应谨慎部署。否则，NGINX 完全支持 NGINX Plus 模块。如需列表，请在Dynamic Modules页面上按作者NGINX进行筛选。
• NGINX Plus 认证的社区模块是 NGINX 测试和分发的流行第三方模块，我们为其提供安装和基本配置支持。我们保证这些模块不会干扰 NGINX Plus 的正确运行，并且我们会在每个 NGINX Plus 版本或有安全版本时根据需要更新它们。对于列表，请在动态模块页面上按作者社区进行筛选。

此外，NGINX 还对参与我们NGINX Plus 认证模块计划的商业供应商的模块进行认证。这些模块由其供应商分发和支持。如需列表，请在动态模块页面上按作者认证合作伙伴进行筛选。

NGINX 不测试或支持您自己编译的模块（其他社区模块、第三方供应商提供的不属于 NGINX Plus 认证模块计划的模块，以及自定义模块）。如果您因问题寻求技术支持，NGINX 支持团队可能会要求您移除不支持的模块并在我们的技术支持过程中重现故障，以便他们验证故障是否由不支持的模块引起。

NGINX Plus 的动态模块构建过程允许您利用 NGINX 开源模块的广泛生态系统，在丰富且完全受支持的 NGINX Plus 内核上运行它们。

如果您当前正在使用带有第三方扩展的 NGINX 开源，这些扩展很可能会被编译并加载到 NGINX Plus 中。

如果您开发商业或社区模块，新的构建过程意味着您的用户可以使用 NGINX Plus 部署您的模块。要了解如何认证商业模块，请参阅NGINX Plus Certified Modules。

如果您在开发模块或更新其配置shell 文件方面需要帮助，请查看以下资源：

• Evan Miller的 NGINX 模块开发指南
• NGINX 开发人员 Ruslan Ermilov 的动态模块开发
• 在 NGINX Wiki 上扩展 NGINX
• NGINX Wiki 上的将静态模块转换为动态模块
• NGINX 教程： Aaron Bedra开发模块
• 在我们的博客上为动态模块创建可安装包