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

NGINX | 2016年10月25日

编者：最初发布动态模块支持（NGINX Open Source 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 Open Source之间的差异时才会同时提及。除非另有说明，所有关于NGINX Plus的陈述也适用于NGINX Open Source。

动态模块概述

可加载到NGINX Plus中的模块使用C语言编写，并符合NGINX Wiki上扩展NGINX所述的API。NGINX拥有一个庞大的第三方模块生态系统，涵盖从语言解释器到安全解决方案的各种模块，其中一些模块已纳入NGINX Plus并获得支持。

其他第三方模块以及自行创建的模块需要单独编译，并在运行时动态加载到NGINX Plus中。您可以按照以下两个示例，基于NGINX Open Source构建这些模块，将其编译为可用于NGINX Plus的模块：

获取匹配的NGINX Open Source版本
获取模块源代码，并根据需要修改模块的“config”文件
构建动态模块，使其与NGINX Open Source版本兼容，并在--with-compat命令行参数中使用configure命令
加载生成的动态模块（即 .so文件）到NGINX Plus中，并像使用内置模块一样使用该模块

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

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

第1步：获取NGINX Open Source版本

确定与所安装的NGINX Plus对应的NGINX Open Source版本。在本例中，该版本为NGINX 1.11.5。

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

从以下地址下载相应的NGINX Open Source软件包：nginx.org/download:

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

第 2 步：获取模块源代码

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

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

模块的config shell文件定义了模块的构建方式。动态模块的格式与静态构建到NGINX Open Source二进制文件中的模块不同。修改文件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

有关编译动态模块的详细信息，包括如何将模块的config文件从旧格式更新为新格式，请参阅NGINX Wiki。

第3步：编译动态模块

编译模块时，首先运行带有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

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

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

第4步：加载并使用模块

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

load_module modules/ngx_http_hello_world_module.so;

在http上下文中，添加一个location块，并在其中使用Hello World模块提供的hello_world指令。向该位置发送请求时，将返回响应hello world。

server {
    listen 80;

    location / {
         hello_world;
    }
}

重新加载NGINX Plus配置，并使用一个简单请求进行测试：

$ nginx -s reload$ curl http://localhost/
hello world

示例：NAXSI Web应用防火墙

NAXSI是一款易于使用的高性能Web应用防火墙（WAF），通过启发式方法和评分系统识别可疑请求，例如XSS和SQL注入攻击。

NAXSI源代码已更新，以符合config 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 Plus核心，请在load_module文件的主上下文中添加nginx.conf指令：

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检测并阻止该请求，同时返回位于50x.html的标准错误页面：/usr/share/nginx/html。此外，还会向error_log写入一条消息。

对于生产环境部署，还可以从下载经过签名的NAXSI版本 https://github.com/nbs-system/naxsi/tags，并以类似方式进行编译。

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

注意：本节信息仅适用于NGINX Plus。随预构建NGINX Open Source软件包提供的动态模块集可能与NGINX Plus随附的模块集不同。用于NGINX Open Source的动态模块与NGINX源代码和预构建二进制文件一样，均可获得支持。

NGINX Plus随附多个动态模块，也可直接从我们的模块存储库下载。有关模块列表，请参阅“动态模块”页面。这些模块分为两类：

NGINX Plus模块由NGINX工程团队编写和/或维护。出于技术原因（例如存在额外依赖项），或由于这些模块处于预览状态，我们未将其纳入NGINX Plus。预览模块仍在积极开发中，部署时应格外谨慎。除此之外，NGINX Plus模块均由NGINX提供全面支持。如需查看列表，请在NGINX页面按作者动态模块进行筛选。
NGINX Plus认证社区模块是由NGINX测试和分发的热门第三方模块，我们为其安装和基本配置提供支持。我们保证这些模块不会影响NGINX Plus正常运行，并会在每次发布NGINX Plus版本或安全版本时根据需要更新这些模块。如需查看列表，请按作者筛选：Community。筛选操作可在“动态模块”页面上进行。

此外，NGINX还会对参与其NGINX Plus Certified Modules计划的商业供应商所提供的模块进行认证。这些模块由相应供应商分发并提供支持。要查看模块列表，请在Certified Partner作者筛选条件下进行筛选，筛选操作位于Dynamic Modules页面。

NGINX不会测试或支持您自行编译的模块（其他社区模块、未加入NGINX Plus Certified Modules计划的第三方供应商所提供的模块，以及自定义模块）。如果您就某个问题寻求技术支持，NGINX支持团队可能会要求您移除不受支持的模块并重现故障，以便在技术支持过程中确认该故障是否由不受支持的模块引起。