/docs/man3.3/man7/openssl-qlog.html

openssl-qlog

名称

openssl-qlog - OpenSSL qlog跟踪功能

描述

OpenSSL 对生成 qlog 日志格式的日志提供了不稳定的支持，该格式可用于获取 QUIC 连接的诊断数据。生成的数据包括发送和接收的数据包信息以及其中包含的帧，以及丢失检测和其他事件。

OpenSSL 生成的 qlog 输出可用于使用 qvis 等工具获取给定 QUIC 连接的诊断可视化。

警告：OpenSSL 的 qlog 功能的输出使用基于草案规范的不稳定格式。目前，qlog 输出不受任何格式稳定性或兼容性保证的约束，并且将在 OpenSSL 的未来版本中以不兼容的方式发生更改。有关详细信息，请参见下面的 格式稳定性。

用法

当 OpenSSL 构建时包含 qlog 支持时，通过将标准 QLOGDIR 环境变量设置为指向应写入 qlog 文件的目录来在运行时启用 qlog。设置后，OpenSSL 建立的任何 QUIC 连接都会自动将 qlog 文件写入指定的目录。

日志文件以基于 JSON-SEQ（RFC 7464）的 .sqlog 格式生成。

指定 QLOGDIR 下生成的日志文件的名称使用以下结构

{connection_odcid}_{vantage_point_type}.sqlog

其中 {connection_odcid} 是 QUIC 连接的原始目标连接 ID 的小写十六进制编码，它是连接过程中发送的第一个初始数据包的标头中使用的目标连接 ID，而 {vantage_point_type} 则为 client 或 server，反映了生成 qlog 输出的端点的视角。

可以使用 no-unstable-qlog 配置标志在 OpenSSL 构建时禁用 qlog 功能。

支持的事件类型

目前支持以下事件类型

connectivity:connection_started
connectivity:connection_state_updated
connectivity:connection_closed
transport:parameters_set
transport:packet_sent
transport:packet_received
recovery:packet_lost

过滤器

默认情况下，所有支持的事件类型都会记录。OSSL_QFILTER 环境变量可用于配置过滤器规范，该规范确定要记录哪些事件类型。每个事件类型都可以单独启用或禁用。过滤器规范是一个空格分隔的术语列表，列出要启用或禁用的事件类型。这些术语按顺序应用，因此后面术语的效果会覆盖前面术语的效果。

示例

以下是一些示例过滤器规范

* (或 +*): 启用所有支持的 qlog 事件类型。
-*: 禁用所有 qlog 事件类型。
* -transport:packet_received: 启用所有 qlog 事件类型，但禁用 transport:packet_received 事件类型。
-* transport:packet_sent: 禁用所有 qlog 事件类型，除了 transport:packet_sent 事件类型。
-* connectivity:* transport:parameters_set: 禁用所有 qlog 事件类型，除了 transport:parameters_set 和 connectivity 类别中所有支持的事件类型。

过滤器语法规范

正式地，过滤器规范的 ABNF 格式如下

filter              = *filter-term

filter-term         = add-sub-term

add-sub-term        = ["-" / "+"] specifier

specifier           = global-specifier / qualified-specifier

global-specifier    = wildcard

qualified-specifier = component-specifier ":" component-specifier

component-specifier = name / wildcard

wildcard            = "*"

name                = 1*(ALPHA / DIGIT / "_" / "-")

过滤器术语的解释如下

+* (或 *): 启用所有事件类型。
-*: 禁用所有事件类型。
+foo:* (或 foo:*): 启用 foo 类别中的所有事件类型。
-foo:*: 禁用 foo 类别中的所有事件类型。
+foo:bar (或 foo:bar): 启用特定事件类型 foo:bar。
-foo:bar: 禁用特定事件类型 foo:bar。

目前不支持部分通配符匹配。

默认配置

如果 OSSL_QFILTER 环境变量未设置或设置为空字符串，则等效于启用所有事件类型（即，等效于 * 过滤器）。请注意，还必须设置 QLOGDIR 环境变量才能启用 qlog。

格式稳定性

OpenSSL qlog 功能目前实现了 qlog 规范的草案版本。在正式标准化之前，对 qlog 规范的未来修订预计会引入与 qlog 格式不兼容且会破坏兼容性的更改。一旦标准化完成，OpenSSL qlog 功能将在未来过渡到生成此格式的输出。

因此，OpenSSL 的 qlog 输出将在未来以不兼容且会破坏兼容性的方式发生更改，包括在 OpenSSL 的非主要版本中。目前，OpenSSL 的 qlog 输出被认为是不稳定的，不受任何格式稳定性或兼容性保证的约束。

OpenSSL qlog 功能的用户必须意识到输出可能会在版本之间任意更改，并且不保证在版本之间与任何给定工具的兼容性。

目标

OpenSSL qlog 草案功能主要用于与 qvis 工具 https://qvis.quictools.info/ 结合使用。在格式兼容性方面，OpenSSL qlog 功能的输出格式预计将跟踪 qvis 支持的内容。因此，OpenSSL qlog 功能的未来更改预计将跟踪 qvis 中发生的更改，并反映 qvis 目前支持的 qlog 版本。

这意味着在 qlog 标准最终确定之前，如果当前草案与 qvis 支持的内容之间存在差异，OpenSSL qlog 功能通常会优先考虑与 qvis 的兼容性而不是与最新草案的合规性。

因此，OpenSSL 的 qlog 功能目前实现了 draft-ietf-quic-qlog-main-schema-05 和 draft-ietf-quic-qlog-quic-events-04 中定义的 qlog 版本 0.3。出于与 qvis 的兼容性考虑，有意使用这些修订版而不是更新的修订版。

限制

OpenSSL 的 qlog 实现目前存在以下限制

草案规范中定义的并非所有事件类型都已实现。
仅支持 JSON-SEQ（.sqlog）输出格式。
仅支持 QLOGDIR 环境变量来配置 qlog 输出目录。不支持标准 QLOGFILE 环境变量。
没有用于以编程方式启用或控制 qlog 功能的 API。

参见

openssl-quic(7)，openssl-env(7)

历史

此功能在 OpenSSL 3.3 中添加。

版权

根据 Apache 许可证 2.0（“许可证”）许可。除非符合许可证，否则您不得使用此文件。您可以在源代码分发中的 LICENSE 文件或 https://www.openssl.org/source/license.html 中获取副本。