搜索 F5 所有的网站

推荐搜索

博客 | NGINX

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

欧文·加勒特

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 开源。

动态模块概述

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

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

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

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

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

步骤 1：获取 NGINX 开源版本

确定与您的 NGINX Plus 安装相对应的 NGINX 开源版本。在此示例中，它是 NGINX 1.11.5。
```
$ nginx -v nginx 版本：nginx/1.11.5 (nginx-plus-r11)
```

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

$ 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

模块的配置shell 文件定义了如何构建模块，并且动态模块的格式与静态构建到 NGINX 开源二进制文件中的模块的格式不同。

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

ngx_addon_name=ngx_http_hello_world_module

如果 test -n "$ngx_module_link"; 那么
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
否则
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：编译动态模块

首先运行带有--with-compat参数的configure脚本来编译模块，这将创建 NGINX Open Source 和 NGINX Plus 支持的标准构建环境。然后运行make modules来构建模块：
```
$ cd nginx-1.11.5/ $ ./configure --with-compat --add-dynamic-module=../nginx-hello-world-module $ make 模块
```

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

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

步骤4：加载并使用模块

要将模块加载到 NGINX Plus，请在nginx.conf配置文件的顶级（主）上下文中添加load_module指令（不在http或stream上下文中）：
```
load_module模块/ngx_http_hello_world_module.so；
```
在http上下文中，使用 Hello World 模块提供的hello_world指令添加位置块。对该位置的请求返回响应hello world 。
```
服务器 {
listen 80;

位置 / {
hello_world;
}
}
```
重新加载您的 NGINX Plus 配置并使用一个简单的请求进行测试：
```
$ nginx -s 重新加载$ curl http://localhost/你好，世界
```

例子： NAXSI Webapplication防火墙

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 $制作模块$ sudo cp objs/ngx_http_naxsi_module.so /etc/nginx/modules

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

load_module模块/ngx_http_naxsi_module.so；

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

# 编辑此“include”指令以指向您的 naxsi_core.rules 文件
include /home/owen/src/naxsi/naxsi_config/naxsi_core.rules;

server {
listen 80;

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

# 启用 NAXSI
SecRulesEnabled;

# 定义被阻止的请求去往何处
DeniedUrl "/50x.html";

# CheckRules，确定 NAXSI 何时需要采取行动
CheckRule "$SQL >= 8" BLOCK;
CheckRule "$RFI >= 8" BLOCK;
CheckRule "$TRAVERSAL >= 4" BLOCK;
CheckRule "$EVADE >= 4" BLOCK;
CheckRule "$XSS >= 8" BLOCK;

# 不要忘记 error_log，被阻止的请求会记录在这里
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 Open Source 使用的动态模块的支持方式与 NGINX源代码和预构建二进制文件的支持方式相同。

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

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

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

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

概括

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

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

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

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

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

NGINX 开发人员邮件列表是社区帮助的首选之地，我们的专业服务团队也很乐意提供帮助。

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

阅读有关 F5 NGINX 的更多博客文章 ›

“这篇博文可能引用了不再可用和/或不再支持的产品。有关 F5 NGINX 产品和解决方案的最新信息，请探索我们的NGINX 产品系列。 NGINX 现在是 F5 的一部分。所有之前的 NGINX.com 链接都将重定向至 F5.com 上的类似 NGINX 内容。”

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

动态模块概述

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

步骤 1： 获取 NGINX 开源版本

第 2 步： 获取模块源

步骤3： 编译动态模块

步骤4： 加载并使用模块