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

本文是关于使用NGINX和NGINX Plus的第三方动态模块的两部分系列的一部分。

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

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

为简洁起见，本文的其余部分仅涉及NGINX Plus，除非它与开源NGINX软件之间的差异是相关的。除非另有说明，否则所有关于NGINX Plus的陈述也适用于NGINX。

动态模块概述

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

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

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

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

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

第1步：获取开源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 http://nginx.org/download/nginx-1.11.5.tar.gz
   $ tar -xzvf nginx-1.11.5.tar.gz

第2步：获取模块源

3. 从 GitHub 获取’Hello World’NGINX模块的源代码：

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

4. 模块的 配置  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 。

第3步：编译动态模块

5. 首先 configure 使用 --with-compat 参数运行脚本来 编译模块，这将创建开源NGINX和NGINX Plus支持的标准构建环境。然后运行 make   modules 以构建模块：

   $ cd nginx-1.11.5/
   $ ./configure --with-compat --add-dynamic-module=../nginx-hello-world-module
   $ make modules

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

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

第4步：加载并使用模块

7. 要将模块加载到NGINX Plus， load_module 请在 nginx.conf 配置文件的顶级（主）上下文中添加该指令（不在 http 或 stream 上下文中）：

   load_module modules/ngx_http_hello_world_module.so;

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

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

9. 重新加载您的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

通过将 load_module 指令添加到 nginx.conf 文件中的主上下文，将模块加载到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，Inc。工程团队编写和/或维护。由于技术原因（例如，它们具有其他依赖性）或因为它们处于预览状态，我们不会将它们包含在NGINX Plus中。预览模块处于活动开发阶段，只应谨慎部署。否则，NGINX，Inc。完全支持NGINX Plus模块。有关列表，请在 动态模块 页面上按作者 NGINX，Inc。 进行过滤。
• NGINX Plus认证社区模块 是NGINX测试和分发的流行第三方模块，我们为其提供安装和基本配置支持。我们保证这些模块不会干扰NGINX Plus的正确操作，并且我们会在每个NGINX Plus版本或有安全版本时根据需要更新它们。对于列表，请在“  动态模块” 页面上按作者 社区 进行筛选。

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

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

摘要

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

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

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

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

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

NGINX开发者邮件列表 是社区援助的 首选 ，我们的 专业服务团队 也很乐意为您提供帮助。

要自行尝试使用NGINX Plus的动态模块，请立即开始 30天免费试用 或 与我们联系 。

via https://www.nginx.com/blog/compiling-dynamic-modules-nginx-plus/