教程：配置 NGINX 使用报告

技术营销经理

2024-05-01

NGINX Plus R31 引入了一种更简单、更高效的方式来报告 NGINX Plus 的使用情况。原生集成的使用报告功能无需单独的 NGINX Agent，便于 F5 的灵活使用套餐 (FCP) 客户和按期限订阅的非 FCP 客户无缝、轻松地完成报告流程。

得益于直接内置于 NGINX Plus 的这项功能，实例能够定期向 NGINX Instance Manager 发送必要的使用信息，而不会影响性能。该功能适用于虚拟机和 NGINX Ingress Controller，但本文将重点介绍 NGINX Plus 实例 —— 如欲查看有关向 NGINX Instance Manager 报告 NGINX Ingress Controller 的指南，请点击此处。

我们简化了设置，并提供了定制选项和回退方法，旨在让必要的使用报告流程成为一个高效的自适应性流程，帮助客户实现并保持FCP合规性。对于尚未使用 R31 或不打算升级的客户，可通过安装 NGINX Agent 或配置 HTTP 健康检查来启用使用报告。

注：若要报告 NGINX Plus 使用情况，您必须在专用主机上安装 NGINX Instance Manager。请参阅安装指南，了解不同的安装方法。

您可通过以下三种方式向 F5 报告 NGINX Plus 实例。

NGINX Plus R31 用户 —— 配置原生 NGINX 使用报告
R31 或 R31 之前的用户 —— 安装 NGINX Agent
R31 之前的用户 —— 为 NGINX Plus 配置 HTTP 健康检查

下面我们来逐个了解一下：

配置原生 NGINX 使用报告

安装后，NGINX Plus 通过默认 DNS 解析记录 “nginx-mgmt.local”，与 NGINX Instance Manager 建立自动连接。默认情况下，NGINX Plus 每 30 分钟与 Instance Manager 通信一次，并发送使用信息。

如需更改 Instance Manager DNS 解析记录或默认连接间隔以更好地满足需求，请在 NGINX 配置中添加 mgmt{} 代码块。此外，该代码块还带有其他默认指令，如 UUID 文件、mTLS、DNS 解析器、使用间隔和 usage_report 端点。有关自定义指令的完整列表，请参阅全面的 mgmtmodule 文档。借助ngx_mgmt_module，您可以轻松自定义指令，从而提高灵活性和便利性。

下文将介绍如何为您的环境配置此功能。

配置 NGINX Plus

建议使用 mTLS 来增强系统的安全防护。为此，您可为 NGINX Plus 实例和 NGINX Instance Manager 生成证书、密钥及证书颁发机构 (CA) 密钥证书。如欲详细了解如何生成密钥，请点击此处。

在配置文件 nginx.conf 的管理块中指定客户端证书和私钥文件的路径。

		
   mgmt {
          ssl_protocols TLSv1.2 TLSv1.3;
          ssl_ciphers DEFAULT;
          ssl_certificate          /home/ubuntu/agent.crt;
          ssl_certificate_key      /home/ubuntu/agent.key
       }

为了确保安全可靠的身份验证流程，请指定 CA 链的路径，以验证证书的真实性。


   mgmt {
          ssl_trusted_certificate  /home/ubuntu/ca.pem;
          ssl_verify               on;
          ssl_verify_depth         2;
       }

对于自定义 DNS 解析器，使用 resolver 指令在 mgmt{}block 代码块中指定解析器地址。
```
   mgmt {
          resolver 3.X.X.X;
       }
```
要为 NGINX Instance Manager 配置自定义 FQDN，使用 usage_report 指令指定 FQDN。然后，在本地 DNS 中添加一条 A 记录，将主机名与 NGINX Instance Manager IP 地址相关联。
```
   mgmt {
          resolver 3.X.X.X;
          usage_report endpoint=nms.local interval=15m;
       }
```

NGINX Plus 配置示例：


  mgmt {
         usage_report endpoint=nms.local interval=30m;
         resolver 3.X.X.X;
         ssl_protocols TLSv1.2 TLSv1.3;
         ssl_ciphers DEFAULT;
         ssl_certificate          /home/ubuntu/agent.crt;
         ssl_certificate_key      /home/ubuntu/agent.key;

         ssl_trusted_certificate  /home/ubuntu/ca.pem;
         ssl_verify               on;
         ssl_verify_depth         2;
     }

保存 NGINX 配置并重新加载 NGINX Plus。

sudo nginx -s reload

配置 NGINX Instance Manager

在服务器块的 /etc/nginx/conf.d/nms-HTTP.conf 中添加 SSL 证书。点击此处了解如何在 NGINX Management Suite 服务器中配置 SSL 证书。


server {
    listen 443 ssl http2;
    root /var/www/nms;
    server_name _;
    ssl_protocols       TLSv1.1 TLSv1.2;
    ssl_ciphers         HIGH:!aNULL:!MD5;
    ssl_session_cache   shared:SSL:10m;
    ssl_session_timeout 10m;
    ssl_certificate         /etc/nms/certs/server.crt;
    ssl_certificate_key     /etc/nms/certs/server.key;
    ssl_client_certificate  /etc/nms/certs/ca.pem;
    ssl_verify_client on;
 }

要查看 NGINX Plus 的使用情况，请在浏览器上登录 NGINX Management Suite 并导航到 NGINX Instance Manager 模块。然后，选择位于页面左下角的 NGINX Plus 选项卡。

观看本视频教程，获取分步指导：

错误日志消息

下面是错误消息列表，可帮助您在无法在 NGINX Instance Manager 中查看使用数据时，在 NGINX Plus 实例中排除故障：

以下列举了一些错误信息示例：

动态解析器故障：DNS 解析器解析失败。

2024/04/02 04:02:10 [error] 574079#574079: recv() failed (111: Connection refused) while resolving, resolver: 3.17.128.165:53
2024/04/02 04:02:35 [warn] 574079#574079: usage report: nginx-mgmt.locals could not be resolved (110: Operation timed out)

系统解析器故障：NGINX Instance Manager 主机名解析失败。

2024/04/02 13:20:44 [info] 103888#0: usage report: host not found in resolver "nginx-mgmt.local"

SSL 连接失败：无法验证 SSL 证书或 SSL 证书过期。

2024/04/02 13:13:50 [warn] 103877#0: usage report: peer SSL connection failed

对等通信失败：无法访问 NGINX Instance Manager。

2024/04/02 13:15:25 [warn] 103877#0: usage report: peer connection failed (-1: Unknown error)
2024/04/02 13:23:32 [warn] 103877#0: usage report: failed (server returned: 404 Not Found)
2024/04/02 19:53:45 [warn] 4648#4648: usage report: connection timed out

安装 NGINX Agent

即便尚未迁移到 R31 或不打算近期迁移，您仍可向 NGINX Instance Manager 报告 NGINX Plus 实例。具体方法是，在您的环境中安装 NGINX Agent。安装完成后，您就能够与 Instance Manager 建立连接，开始传输使用数据。要安装 NGINX Agent，请按照此链接中提供的说明进行操作。

要查看 NGINX Plus 的使用情况，请在浏览器上登录 NGINX Management Suite 并导航到 NGINX Instance Manager 模块。然后，选择位于页面左下角的 NGINX Plus 选项卡。

观看本视频教程，获取分步指导：

为 NGINX Plus 配置 HTTP 健康检查

即便不打算安装 NGINX Agent 或升级到 R31，您仍可报告 NGINX Plus 实例。只需通过 NGINX 配置文件配置 HTTP 健康检查即可。不过，您必须手动更新 NGINX Plus 配置文件才能使用此选项。这种方法既耗时又繁琐，尤其是在环境中有多个实例的情况下。因此，在选择此方案之前，最好考虑到这些因素。

配置 NGINX Plus

打开 NGINX Plus 配置，在 http {} 代码块中插入代码：


   keyval_zone zone=uuid:32K state=/var/lib/nginx/state/instance_uuid.json;
   keyval 1 $nginx_uuid zone=uuid;
   upstream receiver {
    zone receiver 64k;

    # 必选项：使用 NGINX Management Suite IP 地址或主机名更新 NMS_FQDN。
    # 如果使用主机名进行配置，请确保取消注释下面 resolver 指令，
    # 并定义可解析主机名的 DNS 服务器。
    server NMS_FQDN:443;

     # 可选项：使用能够解析上述主机名的 DNS 服务器 IP 地址更新 DNS_IP。
    # the hostname defined above.
    #resolver DNS_IP;
   }  

map CERT $repo_crt {
      # 可选项：客户端证书的位置
      default /home/ubuntu/agent.crt;
   }  

map KEY $repo_key {
    # 可选项：客户端证书私钥的位置
      default /home/ubuntu/agent.key; 
   }


 server {
    location @ngx_usage_https {
       # 可选项：此处配置方案 (http|https)
        proxy_pass https://receiver;

         # 必选项：如果在此实例中使用了 NGINX APP PROTECT (NAP)，请在以下代码行设置 nap=active：
proxy_set_header Nginx-Usage "Version=$nginx_version;Hostname=$hostname;uuid=$nginx_uuid;nap=active";	 

        health_check uri=/api/nginx-usage interval=1800s;       # 切勿修改
        proxy_ssl_certificate     $repo_crt;                    # 切勿修改
        proxy_ssl_certificate_key $repo_key;                    # 切勿修改
    }

    location @self {
        health_check uri=/_uuid interval=1d;
        proxy_pass http://self;
    }

    location = /_uuid {
        if ($nginx_uuid !~ .) {
            set $nginx_uuid $request_id;
        }
        return 204;
    }

    listen unix:/tmp/ngx_usage.sock;
  }

 upstream self {
    zone self 64k;
    server unix:/tmp/ngx_usage.sock;
 }