pktvisor

简介  •   开始使用  •   文档  •   构建  •   贡献  •   联系我们

pktvisor是什么？

pktvisor（发音为"packet visor"）是一个可观测性代理，用于分析高容量、信息密集的网络数据流，并直接从边缘提取可操作的洞察，同时紧密集成现代可观测性堆栈。

它资源高效，从头开始设计为模块化，并可通过API和YAML策略实时动态控制。输入和分析器模块可在运行时动态加载。指标输出可通过命令行UI在节点上使用和可视化（用于本地化、超实时操作），也可集中收集到行业标准的可观测性堆栈中，如Prometheus和Grafana。

输入流系统旨在_采集_数据流。目前支持数据包捕获、dnstap、sFlow和Netflow/IPFIX，不久将支持其他采集方式，如envoy taps和eBPF。

流分析系统包括完整的应用层分析，并高效地汇总为：

• 计数器
• 直方图和分位数
• 计时器和速率
• 重点项/频繁项/Top N
• 集合基数
• GeoIP/ASN

请查看当前指标列表或示例指标输出。

pktvisor起源于对关键互联网基础设施的可观测性支持，用于DDoS保护、流量工程和持续运营。

这些截图展示了命令行和集中式视图的网络和DNS流处理器，以及提供的摘要信息类型：

开始使用

Docker

开始使用pktvisor的最简单方法之一是使用公共docker镜像。该镜像包含收集器代理（pktvisord）、命令行UI（pktvisor-cli）和pcap和dnstap文件分析器（pktvisor-reader）。运行容器时，您需要指定要运行的工具。

1. 拉取容器

docker pull orbcommunity/pktvisor

或使用orbcommunity/pktvisor:latest-develop获取最新的开发版本。

2. 启动收集器代理

这将在后台启动并保持运行。注意最后两个参数选择pktvisord代理和eth0以太网接口进行数据包捕获。您可以将eth0替换为设备上任何已知的接口。 _注意，此步骤需要docker主机网络_以观察容器外的流量，并且目前只有Linux支持主机网络：

docker run --net=host -d orbcommunity/pktvisor pktvisord eth0

如果容器无法保持运行，请检查docker logs输出。

3. 运行命令行UI

代理运行后，您可以使用包含的命令行UI在本地观察结果。此命令将在前台运行UI（pktvisor-cli），按Ctrl-C时退出。它使用内置的REST API在本地连接到运行中的代理。

docker run -it --rm --net=host orbcommunity/pktvisor pktvisor-cli

Linux 静态二进制文件 (AppImage, x86_64)

您也可以使用 Linux 的一体化二进制文件，它是用 AppImage 构建的，可以在发布页面下载。它设计用于在所有现代 Linux 发行版上运行，无需安装或任何其他依赖项。

curl -L http://pktvisor.com/download -o pktvisor-x86_64.AppImage
chmod +x pktvisor-x86_64.AppImage
./pktvisor-x86_64.AppImage pktvisord -h

例如，要在以太网接口 eth0 上运行代理：

./pktvisor-x86_64.AppImage pktvisord eth0

AppImage 包含收集器代理 (pktvisord)、命令行 UI (pktvisor-cli) 和 pcap 和 dnstap 文件分析器 (pktvisor-reader)。您可以通过将其作为第一个参数传递来指定要运行的工具：

例如，要使用 pktvisor 命令行 UI 可视化上面启动的运行代理：

./pktvisor-x86_64.AppImage pktvisor-cli

注意，当运行 AppImage 版本的代理时，您可能需要使用 -d 参数来守护进程（在后台运行），并使用 --log-file 或 --syslog 参数来记录日志。

另请参阅高级代理示例。

Linux 静态二进制文件（独立版，x86_64）

最后，pktvisor 还为每个单独的 pktvisor 工具（pktvisord、pktvisor-cli 和 pktvisor-reader）提供静态链接的、无依赖的 Linux 二进制文件。这些是最小、最紧凑的二进制版本。

pktvisord:

curl -L http://pktvisor.com/download/pktvisord -o pktvisord-x86_64
chmod +x pktvisord-x86_64
./pktvisord-x86_64 -h

pktvisor-cli:

curl -L http://pktvisor.com/download/cli -o pktvisor-cli-x86_64
chmod +x pktvisor-cli-x86_64
./pktvisor-cli-x86_64 -h

pktvisor-reader:

curl -L http://pktvisor.com/download/reader -o pktvisor-reader-x86_64
chmod +x pktvisor-reader-x86_64
./pktvisor-reader-x86_64 -h

其他平台

我们正在努力支持更多操作系统、CPU 架构和打包系统。如果您没有看到可用的二进制文件，请参阅下面的构建部分来构建您自己的版本。

如果您有希望看到支持的首选安装方法，请创建一个问题。

无需 root 执行 Pktvisord 二进制文件

Pktvisord 使用 libpcap 从所需接口捕获 PCAP。为此，它需要系统网络捕获权限。 您可以仅授权一次这些特定要求，然后就能够无需 sudo 运行二进制文件。

sudo setcap cap_net_raw,cap_net_admin=eip /<full_path>/pktvisord-x86_64

文档

代理使用

当前命令行选项可通过以下方式查看：

docker run --rm orbcommunity/pktvisor pktvisord --help

或

./pktvisor-x86_64.AppImage pktvisord --help

    用法：
      pktvisord [选项] [IFACE]
      pktvisord (-h | --help)
      pktvisord --version

    pktvisord 汇总数据流并公开 REST API 控制平面用于配置和指标。

    pktvisord 的操作通过 Taps 和 Collection Policies 进行配置。Taps 抽象了"接入"输入流的过程，
    使用模板化配置，而 Policies 使用 Taps 来实例化和配置输入和流处理程序，以分析和汇总流数据，
    然后通过 REST API 提供这些数据供收集。

    可以通过将适当的 YAML 配置文件传递给 --config 来创建 Taps 和 Collection Policies，
    和/或通过启用带有 --admin-api 的管理 REST API 并使用适当的端点。

    或者，对于简单的用例，您可以指定 IFACE，它可以是网络接口、IP 地址（4 或 6）或 "auto"。
    如果指定了这个，将创建"默认"的 Tap 和 Collection Policies，在指定的接口上有一个 "pcap" 输入流，
    并附加内置的 "net"、"dns" 和 "pcap" 流处理程序模块。如果指定 "auto"，将选择最常用的以太网接口。
    请注意，此功能可能在未来被弃用。

    更多文档，请参见 https://pktvisor.dev

基础选项： -d 守护进程模式；分叉并在后台继续运行 [默认：否] -h --help 显示此帮助屏幕 -v 详细日志输出 --no-track 不发送轻量级匿名使用指标 --version 显示版本

Web服务器选项： -l 主机 在指定主机或IP上运行Web服务器（默认：localhost） -p 端口 在指定端口上运行Web服务器（默认：10853） --tls 在Web服务器上启用TLS --tls-cert 文件 使用指定的TLS证书。如果启用--tls，则必需。 --tls-key 文件 使用指定的TLS私钥。如果启用--tls，则必需。 --admin-api 启用管理REST API，提供完整的控制平面功能 [默认：否] 未指定时，暴露的API仅提供模块状态和指标的只读访问。 指定时，为所有模块启用写入访问。

地理位置选项： --geo-city 文件 用于IP到地理位置映射的GeoLite2城市数据库 --geo-asn 文件 用于IP到ASN映射的GeoLite2 ASN数据库 --geo-cache-size N GeoLite2 LRU缓存大小，0表示禁用。（默认：10000） --default-geo-city 文件 如果未指定其他数据库，将加载的默认GeoLite2城市数据库 --default-geo-asn 文件 如果未指定其他数据库，将加载的默认GeoLite2 ASN数据库

配置： --config 文件 使用指定的YAML配置文件来配置选项、Taps和收集策略 更多信息请参见 https://pktvisor.dev

Crashpad： --cp-disable 禁用crashpad收集器 --cp-token 令牌 用于远程崩溃报告的Crashpad令牌 --cp-url URL Crashpad服务器URL --cp-custom 用户定义 Crashpad可选的用户自定义字段 --cp-path 路径 Crashpad处理程序二进制文件路径

模块： --module-list 列出所有已加载的模块（内置和动态） --module-dir 目录 设置模块加载路径。此目录中的所有模块都将被加载。

日志选项： --log-file 文件 将日志输出到指定文件 --syslog 将日志输出到系统日志

Prometheus选项： --prometheus 已忽略，Prometheus输出始终启用（保留向后兼容性） --prom-instance ID 可选设置'instance'标签为给定ID

指标丰富选项： --iana-service-port-registry 文件 IANA服务名称和传输协议端口号注册表文件（CSV格式） --default-service-registry 文件 如果未指定其他注册表，将加载的默认IANA服务名称端口号注册表CSV文件

处理程序模块默认值： --max-deep-sample N 深度采样的流不超过N%（0到100之间的整数）（默认：100） --periods P 在内存中保留P个60秒时间段的历史记录（默认：5）

pcap输入模块选项： （仅适用于指定IFACE时的默认策略） -b BPF 使用给定的tcpdump兼容过滤表达式过滤数据包。例如："port 53" -H 主机规范 指定要视为主机的子网（逗号分隔），采用CIDR格式。在实时捕获中， 这可能会从捕获设备自动检测，但对于pcap文件必须指定。 示例："10.0.1.0/24,10.0.2.1/32,2001:db8::/64" 为实时捕获指定此项将追加到任何自动检测结果。

使用配置文件

pktvisord可以通过使用--config选项指定YAML配置文件在启动时进行配置。 配置文件可以配置命令行上可用的所有选项， 还可以定义策略和Taps。所有部分都是可选的。

请注意，策略和Taps也可以通过REST API实时维护。

version: "1.0"

visor:
  # 可选定义全局配置（参见命令行选项）
  config:
    verbose: true
  # 可选定义taps
  taps:
    default_pcap:
      input_type: pcap
      config:
        iface: eth0
      filter:
        bpf: "port 53"          
    unix_dnstap:
      input_type: dnstap
      config:
        socket: "/tmp/dnstap.sock"
    tcp_dnstap:
      input_type: dnstap
      config:
        tcp: "127.0.0.1:53053"
  # 可选定义策略
  policies:
    mysocket:
      kind: collection
      input:
        tap: unix_dnstap
        input_type: dnstap
      handlers:
        modules:
          default_net:
            type: net
          default_dns:
            type: dns
            config:
              only_qname_suffix:
                - ".google.com"
                - ".ns1.com"
    mytcp:
      kind: collection
      input:
        tap: tcp_dnstap
        input_type: dnstap
      handlers:
        modules:
          default_net:
            type: net
          default_dns:
            type: dns

如果在Docker容器中运行，你必须将配置文件挂载到容器中。例如，如果配置文件在主机上的路径为/local/pktvisor/agent.yaml，你可以通过以下命令将其挂载到容器中并使用：

docker run -v /local/pktvisor:/usr/local/pktvisor/ --net=host orbcommunity/pktvisor pktvisord --config /usr/local/pktvisor/agent.yaml --admin-api

命令行UI使用

命令行UI（pktvisor-cli）直接连接到pktvisord代理以可视化实时流摘要，默认为滑动5分钟时间窗口。它还可以连接到远程主机上运行的代理。

docker run --rm orbcommunity/pktvisor pktvisor-cli -h

./pktvisor-x86_64.AppImage pktvisor-cli -h

用法：
  pktvisor-cli [-p 端口] [-H 主机]
  pktvisor-cli -h
  pktvisor-cli --version
选项：
  -p 端口               在指定端口查询pktvisord指标网络服务器 [默认：10853]
  -H 主机               在指定主机查询pktvisord指标网络服务器 [默认：localhost]
  -P 策略               要查询的pktvisor策略 [默认：default]
  --tls                 使用TLS与pktvisord指标网络服务器通信
  --tls-noverify        不验证TLS证书
  -h                    显示此帮助信息
  --version             显示客户端版本

### 文件分析（pcap和dnstap）

`pktvisor-reader`是一个可以静态分析预先录制的数据包捕获和dnstap文件的工具。

pcap文件可以来自多个源，其中最著名的是[tcpdump](https://www.tcpdump.org/)。Dnstap文件可以由支持dnstap日志记录的大多数DNS服务器软件生成，可以直接生成或使用[golang-dnstap](https://github.com/dnstap/golang-dnstap)等工具生成。

两者都采用与`pktvisord`进行实时捕获相同的许多选项，并进行相同的分析。pcap文件可能包含流量捕获数据。

docker run --rm orbcommunity/pktvisor pktvisor-reader --help

```shell
./pktvisor-x86_64.AppImage pktvisor-reader --help

用法：
  pktvisor-reader [选项] 文件
  pktvisor-reader (-h | --help)
  pktvisor-reader --version

总结网络（pcap、dnstap）文件。结果将以JSON格式写入stdout，而控制台日志将打印到stderr。

选项：
  -i 输入              输入类型（pcap|dnstap|sflow|netflow）。如果未设置，默认为pcap输入
  --max-deep-sample N  深度采样的流量不超过N%（0到100之间的整数）[默认：100]
  --periods P          在内存中保留P个60秒时间段的历史记录。使用1来汇总所有数据。[默认：5]
  -h --help            显示此帮助信息
  --version            显示版本
  -v                   详细日志输出
  -b BPF               使用给定的BPF字符串过滤数据包
  --geo-city 文件      用于IP到地理位置映射的GeoLite2 City数据库（如果启用）
  --geo-asn 文件       用于IP到ASN映射的GeoLite2 ASN数据库（如果启用）
  -H 主机规范          指定要视为主机的子网（逗号分隔），采用CIDR形式。在实时捕获中，这可能会从捕获设备自动检测，
                       但对于pcap文件必须指定。示例："10.0.1.0/24,10.0.2.1/32,2001:db8::/64"
                       为实时捕获指定此项将追加到任何自动检测结果。

您可以通过传递引用包含pcap文件的目录的卷来使用Docker容器。标准输出将包含JSON摘要输出，您可以捕获或通过管道传递到其他工具，例如：

$ docker run --rm -v /pktvisor/src/tests/fixtures:/pcaps orbcommunity/pktvisor pktvisor-reader /pcaps/dns_ipv4_udp.pcap | jq .

[2021-03-11 18:45:04.572] [pktvisor] [info] 加载输入插件：PcapInputModulePlugin dev.visor.module.input/1.0
[2021-03-11 18:45:04.573] [pktvisor] [info] 加载处理程序插件：DnsHandler dev.visor.module.handler/1.0
[2021-03-11 18:45:04.573] [pktvisor] [info] 加载处理程序插件：NetHandler dev.visor.module.handler/1.0
...
processed 140 packets
{
  "5m": {
    "dns": {
      "cardinality": {
        "qname": 70
      },
      "period": {
        "length": 6,
        "start_ts": 1567706414
      },
      "top_nxdomain": [],
      "top_qname2": [
        {
          "estimate": 140,
          "name": ".test.com"
        }
      ],
...     

AppImage可以像任何普通二进制文件一样访问本地文件：

$ ./pktvisor-x86_64.AppImage pktvisor-reader /pcaps/dns_ipv4_udp.pcap | jq .

[2021-03-11 18:45:04.572] [pktvisor] [info] 加载输入插件：PcapInputModulePlugin dev.visor.module.input/1.0
[2021-03-11 18:45:04.573] [pktvisor] [info] 加载处理程序插件：DnsHandler dev.visor.module.handler/1.0
[2021-03-11 18:45:04.573] [pktvisor] [info] 加载处理程序插件：NetHandler dev.visor.module.handler/1.0
...
processed 140 packets
{
  "5m": {
    "dns": {
      "cardinality": {
        "qname": 70
      },
      "period": {
        "length": 6,
        "start_ts": 1567706414
      },
      "top_nxdomain": [],
      "top_qname2": [
        {
          "estimate": 140,
          "name": ".test.com"
        }
      ],
...     

指标收集

从REST API获取指标

可以通过REST API以JSON格式从代理获取指标。

对于大多数用例，您需要每分钟收集一次最近的完整1分钟桶：

curl localhost:10853/api/v1/metrics/bucket/1

这可以使用telegraf和标准HTTP插件等工具完成。 default策略的telegraf配置片段示例： [输入] [[inputs.http]] urls = [ "http://127.0.0.1:10853/api/v1/metrics/bucket/1",] interval = "60s" data_format = "json" json_query = "1m" json_time_key = "period_start_ts" json_time_format = "unix" json_string_fields = [ "dns_", "packets_", "dhcp_", "pcap_", ]

[inputs.http.tags] t = "pktvisor" interval = "60"

#### Prometheus 指标

`pktvisord` 原生支持 Prometheus。可以在标准的 `/metrics` 端点收集 `default` 策略指标，或使用 `/api/v1/policies/__all/metrics/prometheus` 收集所有策略的指标。

```shell
$ ./pktvisor-x86_64.AppImage pktvisord -d eth0
$ curl localhost:10853/metrics
# HELP dns_wire_packets_udp 通过 UDP 接收的 DNS 报文总数（入站和出站）
# TYPE dns_wire_packets_udp gauge
dns_wire_packets_udp{instance="node",policy="default"} 28
# HELP dns_rates_total 所有 DNS 报文的速率（入站和出站合计）每秒
# TYPE dns_rates_total summary
dns_rates_total{instance="node",policy="default",quantile="0.5"} 0
dns_rates_total{instance="node",policy="default",quantile="0.9"} 4
dns_rates_total{instance="node",policy="default",quantile="0.95"} 4
...

您可以通过传递 --prom-instance ID 来设置 instance 标签。

如果您对使用远程写入进行集中收集感兴趣，包括写入云提供商，有一个可用的 docker 镜像可以轻松实现。更多信息请参见 centralized_collection/prometheus。

另外，请查看 getorb.io 以了解如何将 pktvisor 代理连接到 Orb 可观测性平台。

REST API

REST API 文档以 OpenAPI 格式提供。

请注意，管理控制平面 API（--admin-api）目前正在进行大量迭代，因此尚未记录。如果您有需要使用管理 API 的用例，请联系我们进行讨论。

高级代理示例

使用 Docker 启动收集器代理，支持 MaxmindDB GeoIP/GeoASN，并使用 Host 选项识别入站和出站流量：

docker run --rm --net=host -d \
    --mount type=bind,source=/opt/geo,target=/geo \
    orbcommunity/pktvisor pktvisord \
    --geo-city /geo/GeoIP2-City.mmdb \
    --geo-asn /geo/GeoIP2-ISP.mmdb \
    -H 192.168.0.54/32,127.0.0.1/32 \
    eth0

使用 AppImage 执行相同的命令并将日志记录到 syslog：

./pktvisor-x86_64.AppImage pktvisord -d --syslog \
    --geo-city /geo/GeoIP2-City.mmdb \
    --geo-asn /geo/GeoIP2-ISP.mmdb \
    -H 192.168.0.54/32,127.0.0.1/32 \
    eth0

更多文档

我们认识到一流文档的价值，正在努力编写更多文档，包括扩展和更新 REST API 文档、面向输入和处理模块开发者的内部文档（以及那些想为 pktvisor 做贡献的人），以及用户手册。

如果您对安装、使用或开发有任何问题，请联系我们。

联系我们

我们非常希望听到您的使用案例、功能请求和其他反馈！

• 提交问题
• 查看现有问题
• 开始讨论
• 加入我们的 Slack
• 发送邮件至 info@pktvisor.dev

构建

主要代码库使用清晰、现代的 C++ 编写。pktvisor-cli 命令行界面使用 Go 编写。构建系统需要 CMake 和 Conan 包管理系统。

pktvisor 遵循语义化版本。

pktvisor 在 Linux 和 OSX 上开发和测试。Windows 版本正在开发中。已知 x86_64 和 ARM 架构均可运行。

依赖项

• Conan 1.X C++ 包管理器
• CMake >= 3.13 (cmake)
• 支持 C++17 的 C++ 编译器

有关 conan 包含的包列表，请参见 conanfile.py

构建

一般构建步骤如下：

# 克隆仓库
git clone https://github.com/orb-community/pktvisor.git
cd pktvisor
mkdir build && cd build

# 配置并处理依赖项
cmake -DCMAKE_BUILD_TYPE=Release ..

# 构建并运行测试
make all test

# 二进制文件将位于 build/bin 目录中
bin/pktvisord --help

由于开发环境可能差异很大，请参考 Dockerfile 和持续集成构建文件。

贡献

感谢您考虑贡献！我们将扩展此部分，提供更详细的信息来指导您完成这个过程。 请将拉取请求提交到 develop 分支。如果您考虑进行较大规模的贡献，请联系我们讨论您的设计方案。

有关更多信息，请参阅 NS1 贡献指南。

许可证

本代码根据 Mozilla 公共许可证 2.0 发布。您可以在 LICENSE 文件中找到相关条款和条件。