教程：配置NGINX使用情况报告

NGINX | 2024年5月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 的 management 块中指定客户端证书和私钥文件的路径。

		
   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解析器，请在mgmt{}block中使用resolver指令指定解析器地址。


   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的server块中添加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选项卡。

观看此视频教程，了解分步操作说明：

&amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;nbsp;

错误日志消息

如果无法在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证书或证书已过期。

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 Plus实例上报至NGINX Instance Manager。为此，可在环境中安装NGINX Agent。安装完成后，即可连接到NGINX Instance Manager并开始传输使用情况数据。要安装NGINX Agent，请按照此链接中的说明操作。

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

观看此视频教程，了解分步操作说明：

&amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;nbsp;

为 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;

    # REQUIRED: Update NMS_FQDN with NGINX Management Suite IP Address or hostname.
    # If configuring with hostname, please ensure to uncomment the resolver
    # directive below and define a DNS server that can resolve the hostname.
    server NMS_FQDN:443;

    # OPTIONAL: Update DNS_UP with DNS server IP address that can resolve
    # the hostname defined above.
    #resolver DNS_IP;
   }  

map CERT $repo_crt {
    # OPTIONAL: Location of client certificate
      default /home/ubuntu/agent.crt;
   }  

map KEY $repo_key {
    # OPTIONAL: Location of client certificate private key
      default /home/ubuntu/agent.key; 
   }


 server {
    location @ngx_usage_https {
        # OPTIONAL: Configure scheme (http|https) here
        proxy_pass https://receiver;

        # REQUIRED: If using NGINX APP PROTECT (NAP) on this instance, set nap=active on the following line:
proxy_set_header Nginx-Usage "Version=$nginx_version;Hostname=$hostname;uuid=$nginx_uuid;nap=active";	 

        health_check uri=/api/nginx-usage interval=1800s;       # DO NOT MODIFY
        proxy_ssl_certificate     $repo_crt;                    # DO NOT MODIFY
        proxy_ssl_certificate_key $repo_key;                    # DO NOT MODIFY
    }

    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;
 }