最新稳定版：v7.2.0

介绍

PerimeterX Nginx Lua 插件是一个 Lua 模块，它强制执行是否允许继续处理请求。当 PerimeterX Enforcer 确定请求来自非人类来源时，请求将被阻止。

升级中

查看所有版本的完整变更日志。

从低于 4.x 的任何版本

从 4.x 版开始，添加了配置生成器。配置构建器将默认值添加到未隐式指定的属性。init_worker_by_lua_block此更改需要用户在andaccess_by_lua_block块中导入配置nginx.conf：

1. 调整init_worker_by_lua_block

    init_worker_by_lua_block {
        local pxconfig = require("px.pxconfig")
        require ("px.utils.pxtimer").application(pxconfig)
    }

1. 调整access_by_lua_block

    access_by_lua_block {
        local config = require('px.pxconfig')
        require("px.pxnginx").application(config)
    }

1. 调整header_filter_by_lua_block

    header_filter_by_lua_block {
        require("px.pxnginx").finalize()
    }

从 4.x 以上的任何版本

要升级到最新的 Enforcer 版本，请根据您的操作系统重新安装Enforcer。

安装

支持的操作系统

• Debian
• Ubuntu 14.04 or Ubuntu 16.04+
• RHEL
• CentOS 7
• Amazon Linux (AMI)

支持的 NGINX 版本：

建议您使用官方 NGINX存储库中的最新版本的 NGINX。

• NGINX 1.7 或更高版本
• NGINX Plus
• OpenResty

注意：在各种操作系统中使用默认提供的默认 NGINX 不支持 LUA NGINX 模块。

使用 Ubuntu 安装

Ubuntu 14.04

1. 升级和更新 Ubuntu 16.04 或更高版本的现有依赖项

sudo apt-get update
sudo apt-get upgrade
2.添加官方NGINX仓库，获取最新版NGINX

sudo add-apt-repository ppa:nginx/stable

如果add-apt-repository: command not found返回错误，请运行：

sudo apt-get -y install software-properties-common

3. 安装 Ubuntu 14.04 的依赖项：

sudo apt-get -y install build-essential
sudo apt-get -y install ca-certificates
sudo apt-get -y install make
sudo apt-get -y install wget
sudo apt-get -y install nginx
sudo apt-get -y install m4
sudo apt-get -y install libnginx-mod-http-lua
sudo apt-get -y install lua-cjson
4.从源代码下载并安装LuaRocks

wget http://luarocks.github.io/luarocks/releases/luarocks-2.4.4.tar.gz
tar -xzf luarocks-2.4.4.tar.gz
cd luarocks-2.4.4
./configure
sudo make clean && sudo make build && sudo make install
cd ~
5. 从源下载并安装 Nettle 3.3

wget https://ftp.gnu.org/gnu/nettle/nettle-3.3.tar.gz
tar -xzf nettle-3.3.tar.gz
cd nettle-3.3
./configure
sudo make clean && sudo make install
cd ~
6.安装剩余的依赖

sudo apt-get -y install lua-sec
sudo luarocks install lua-resty-nettle

7. 安装 PerimeterX NGINX 插件

sudo no_proxy=1 luarocks install perimeterx-nginx-plugin

Ubuntu 16.04 及更高版本

1. 更新 Ubuntu 16.04 或更高版本的现有依赖项

sudo apt-get update
2.添加官方NGINX仓库，获取最新版NGINX

sudo add-apt-repository ppa:nginx/stable

如果add-apt-repository: command not found返回错误，请运行：

sudo apt-get -y install software-properties-common

3.更新和升级现有的 Ubuntu 16.04 或更高版本的依赖项

sudo apt-get update
sudo apt-get upgrade
4. 安装 Ubuntu 16.04 或更高版本的依赖项

sudo apt-get -y install build-essential
sudo apt-get -y install ca-certificates
sudo apt-get -y install nginx
sudo apt-get -y install libnginx-mod-http-lua
sudo apt-get -y install lua-cjson
sudo apt-get -y install libnettle6
sudo apt-get -y install nettle-dev
sudo apt-get -y install luarocks
sudo apt-get -y install luajit
sudo apt-get -y install libluajit-5.1-dev
5. 安装 PerimeterX NGINX 插件

luarocks install perimeterx-nginx-plugin

使用 CentOS 7 安装

NGINX 不通过 RPM 为 CentOS/RHEL 提供 NGINX http lua 模块。这意味着您需要从源代码编译模块。

1.更新并安装依赖

yum -y update
yum install -y epel-release
yum update -y
yum groupinstall -y  "Development Tools"
yum install -y wget rpmdevtools git luajit luajit-devel openssl-devel zlib-devel pcre-devel gcc gcc-c++ make perl-ExtUtils-Embed lua-json lua-devel  ca-certificates
yum remove -y nettle luarocks
2.创建一个tmp目录来工作

sudo mkdir /tmp/nginx
cd /tmp/nginx
3.下载所有需要的源文件

wget http://luarocks.github.io/luarocks/releases/luarocks-3.5.0.tar.gz
wget http://nginx.org/download/nginx-1.18.0.tar.gz
wget -O luajit-2.0.tar.gz https://github.com/LuaJIT/LuaJIT/archive/refs/tags/v2.0.5.tar.gz
wget -O nginx_devel_kit.tar.gz https://github.com/simpl/ngx_devel_kit/archive/v0.3.1.tar.gz
wget -O nginx_lua_module.tar.gz https://github.com/openresty/lua-nginx-module/archive/v0.10.15.tar.gz
wget https://ftp.gnu.org/gnu/nettle/nettle-3.6.tar.gz
4.解压所有源文件

tar -xzf luarocks-3.5.0.tar.gz
tar -xzf nettle-3.6.tar.gz
tar -xvf luajit-2.0.tar.gz
tar -xvf nginx-1.18.0.tar.gz
tar -xvf nginx_devel_kit.tar.gz
tar -xvf nginx_lua_module.tar.gz
5.从源码安装luarocks

cd /tmp/nginx/luarocks-3.5.0
./configure
make
make install
6. 从源码安装 Nettle

cd /tmp/nginx/nettle-3.6
./configure --prefix=/usr --disable-static
make
make check
make install
7.安装LuaJIT

cd /tmp/nginx/LuaJIT-2.0.5
make install

8. 使用所需模块构建和安装 NGINX

cd /tmp/nginx/nginx-1.18.0
LUAJIT_LIB=/usr/local/lib LUAJIT_INC=/usr/local/include/luajit-2.0 \
./configure \
--user=nginx                          \
--group=nginx                         \
--prefix=/etc/nginx                   \
--sbin-path=/usr/sbin/nginx           \
--conf-path=/etc/nginx/nginx.conf     \
--pid-path=/var/run/nginx.pid         \
--lock-path=/var/run/nginx.lock       \
--error-log-path=/var/log/nginx/error.log \
--http-log-path=/var/log/nginx/access.log \
--with-http_gzip_static_module        \
--with-http_stub_status_module        \
--with-debug                          \
--with-http_ssl_module                \
--with-pcre                           \
--with-http_perl_module               \
--with-file-aio                       \
--with-http_realip_module             \
--add-module=/tmp/nginx/ngx_devel_kit-0.3.1 \
--add-module=/tmp/nginx/lua-nginx-module-0.10.15
make install
9. 安装 PerimeterX Nginx 插件和依赖项

luarocks install luasec
luarocks install lustache
luarocks install lua-resty-core
luarocks install lua-resty-nettle
luarocks install luasocket
luarocks install lua-resty-http
luarocks install lua-cjson
luarocks install perimeterx-nginx-plugin
10. 或者，如果您在新环境中进行测试，您可能需要配置以下内容：

• 添加用户“nginx”sudo useradd --system --home /var/cache/nginx --shell /sbin/nologin --comment "nginx user" --user-group nginx
• 为 NGINX 创建系统服务sudo vi /usr/lib/systemd/system/nginx.service
• 将以下内容粘贴到您刚刚创建的文件中：[Unit] Description=nginx - high performance web server Documentation=https://nginx.org/en/docs/ After=network-online.target remote-fs.target nss-lookup.target Wants=network-online.target [Service] Type=forking PIDFile=/var/run/nginx.pid ExecStartPre=/usr/sbin/nginx -t -c /etc/nginx/nginx.conf ExecStart=/usr/sbin/nginx -c /etc/nginx/nginx.conf ExecReload=/bin/kill -s HUP $MAINPID ExecStop=/bin/kill -s TERM $MAINPID [Install] WantedBy=multi-user.target
• 启用并启动 NGINX 服务sudo systemctl is-enabled nginx.service sudo systemctl start nginx.service sudo systemctl enable nginx.service

为 NGINX+ 安装 PerimeterX NGINX 插件

如果您已经在使用 NGINX+，则以下步骤包括安装 NGINX+ Lua 模块和 PermimeterX NGINX 插件。

• RHEL 7.4 及更高版本
• Amazon Linux、CentOS 和 RHEL 7.3 及更低版本
  

配置

所需的 NGINX 配置

需要以下 NGINX 配置来支持 PerimeterX NGINX Lua 插件：

• 解析器Resolver 指令必须在 NGINX 配置的 HTTP 部分进行配置。将解析器设置resolver A.B.C.D;为外部 DNS 解析器，例如 Google ( resolver 8.8.8.8;)，或者将解析器设置resolver A.B.C.D;为您的 DNS 解析器 ( ) 的内部 IP 地址resolver 10.1.1.1;。这是 NGINX 解析 PerimeterX API 所必需的。
• Lua包路径确保配置的 HTTP 部分中的 Lua 包路径位置反映了已安装的 PerimeterX 模块的位置。lua_package_path "/usr/local/lib/lua/?.lua;;";
• Lua CA 证书对于 PerimeterX 服务器的 TLS 支持，将 Lua 配置为指向受信任的证书位置。lua_ssl_trusted_certificate "/etc/ssl/certs/ca-certificates.crt"; lua_ssl_verify_depth 3; 注意：证书位置可能因 Linux 发行版而异。在 CentOS/RHEL 系统中，CA 包位置可能位于/etc/pki/tls/certs/ca-bundle.crt.
• Lua 定时器初始化使用 Lua 脚本添加 init。PerimeterX 使用 init 定期保存和发送指标。init_worker_by_lua_block { local pxconfig = require("px.pxconfig") require ("px.utils.pxtimer").application(pxconfig) }
• 应用 PerimeterX 执法将以下行添加到您的location块中：#----- PerimeterX protect location -----# access_by_lua_block { local pxconfig = require("px.pxconfig") require ("px.pxnginx").application(pxconfig) } header_filter_by_lua_block { require("px.pxnginx").finalize() } #----- PerimeterX Module End -----#
• nginx.conf 示例以下nginx.conf示例包含强制执行到块的必需指令location。worker_processes 1; error_log /var/log/nginx/error.log; events { worker_connections 1024; } http { lua_package_path "/usr/local/lib/lua/?.lua;;"; # -- initializing the perimeterx module -- # init_worker_by_lua_block { local pxconfig = require("px.pxconfig") require ("px.utils.pxtimer").application(pxconfig) } lua_ssl_trusted_certificate "/etc/ssl/certs/ca-certificates.crt"; lua_ssl_verify_depth 3; resolver 8.8.8.8; server { listen 80; location / { #----- PerimeterX protect location -----# access_by_lua_block { local pxconfig = require("px.pxconfig") require("px.pxnginx").application(pxconfig) } header_filter_by_lua_block { require("px.pxnginx").finalize() } #----- PerimeterX Module End -----# root /nginx/www; index index.html; } } }

注意：必须先完成 NGINX 配置要求，然后才能进行下一阶段的安装。

PerimeterX 插件配置

所需配置：

设置如下配置：

/usr/local/lib/lua/px/pxconfig.lua

 -- ## Required Parameters ##
 _M.px_appId = 'PX_APP_ID'
 _M.auth_token = 'PX_AUTH_TOKEN'
 _M.cookie_secret = 'COOKIE_ENCRYPTION_KEY'

• PerimeterX Application ID / AppId和 PerimeterX Token / Auth Token可以在 Portal 的Applications中找到。
• PerimeterX Cookie 加密密钥可以在门户网站的策略中找到。

从中获取Cookie 加密密钥的策略必须与从中获取应用程序 ID/AppId和 PerimeterX令牌/授权令牌的应用程序相对应

第一方配置

第一方模式

第一方模式使模块能够向传感器发送数据/从传感器接收数据，充当客户端请求和传感器活动的反向代理。

第一方模式可能需要对JS 传感器代码段进行其他更改。有关详细信息，请参阅 PerimeterX 门户。

...
_M.first_party_enabled = true

必须为 PerimeterX Lua 模块的第一方模式启用以下路由： - /<PX_APP_ID without PX prefix>/xhr/*-/<PX_APP_ID without PX prefix>/init.js

• 如果在 上启用了 PerimeterX Lua 模块location /，则路由已经打开，无需执行任何操作。
• 如果未在 上启用PerimeterX Lua 模块location /，请为 NGINX 添加到您的服务器块：

server {
    listen 80;

    location /<PX_APP_ID without PX prefix> {
        #----- PerimeterX protect location -----#
        access_by_lua_block {
          local pxconfig = require("px.pxconfig")
          require("px.pxnginx").application(pxconfig)
        }
        header_filter_by_lua_block {
         require("px.pxnginx").finalize()
        }
        #----- PerimeterX Module End  -----#

        root   /nginx/www;
        index  index.html;
    }
}

注意：如果您的 NGINX 版本支持 HTTP v2，请参阅附录的 HTTP v2 部分。

注意：必须先完成 PerimeterX NGINX Lua 插件配置要求，然后才能进行下一阶段的安装。

第一方 JS 代码段

在您的网站上部署 PerimeterX 第一方 JS 代码段之前，请确保配置了PerimeterX NGINX Lua 插件。（可以在此处找到有关部署 PerimeterX 第一方 JS 代码段的详细说明。）

要部署 PerimeterX 第一方 JS 代码段：

1. 生成第一方代码段

• 转到应用程序>>片段。
• 选择第一方。
• 选择使用默认路由。
• 单击复制代码段以生成 JS 代码段。

2. 部署第一方代码段

• 复制 JS 片段并使用标签管理器进行部署，或者将其全局嵌入到您希望 PerimeterX 运行的网站的 Web 模板中。
  

源地址： https://github.com/PerimeterX/perimeterx-nginx-plugin