OPENSSL-QLOG(7SSL)

📦
version 4.0.3 · 6 versions
, in ubuntu stonking

💖 NAME 💖

okay so bestie, this is the openssl-qlog manual page, section 7SSL — it's all about OpenSSL's qlog tracing functionality. like, the whole thing. settle in 🫶

✨ DESCRIPTION ✨

ngl this is the fun part: OpenSSL has unstable support for generating logs in the qlog logging format, and you'd use it to get diagnostic data for QUIC connections. the data it spits out includes info on packets sent and received, the frames contained inside them, plus loss detection and other events. it's giving receipts 💅

the qlog output from OpenSSL can be used to get diagnostic visualisations of a given QUIC connection using tools like qvis. obsessed.

⚠️ WARNING: OpenSSL's qlog functionality uses an unstable format based on a draft specification. qlog output is not subject to any format stability or compatibility guarantees right now, and it will change in incompatible ways in future versions of OpenSSL. go read FORMAT STABILITY below, fr fr. 💀

🌸 USAGE 🌸

so when OpenSSL is built with qlog support, you turn qlog on at run time by setting the standard QLOGDIR environment variable to point at a directory where qlog files should be written. once that's set, any QUIC connection established by OpenSSL will automatically have a qlog file written to that directory. no cap, it just happens. ✨

log files are generated in the .sqlog format, which is based on JSON-SEQ (RFC 7464).

the filenames of the generated log files under the specified QLOGDIR follow this structure:

{connection_odcid}_{vantage_point_type}.sqlog

where:

  • {connection_odcid} is the lowercase hexadecimal encoding of a QUIC connection's Original Destination Connection ID — aka the Destination Connection ID used in the header of the first Initial packet sent as part of the connection process 🎀
  • {vantage_point_type} is either "client" or "server", reflecting the perspective of the endpoint producing the qlog output 👑

and if you want qlog gone at build time, there's the no-unstable-qlog configure flag. bye bestie 🦋

🔥 SUPPORTED EVENT TYPES 🔥

here's the roster of event types currently supported — the whole squad:

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

🎀 FILTERS 🎀

by default, all supported event types get logged. but!! there's the OSSL_QFILTER environment variable, and you can use it to configure a filter specification that decides which event types get logged. each event type can be turned on and off individually — main character energy for every single one 💅

the filter specification is a space-separated list of terms listing event types to enable or disable. the terms are applied in order, so the effects of later terms override the effects of earlier terms. periodt. ✨

🌈 Examples 🌈

some example filter specs to snack on:

  • "*" (or "+*") — enable all supported qlog event types. slay.
  • "-*" — disable all qlog event types. rough.
  • "* -transport:packet_received" — enable all qlog event types, but disable the transport:packet_received event type.
  • "-* transport:packet_sent" — disable all qlog event types, except for the transport:packet_sent event type.
  • "-* connectivity:* transport:parameters_set" — disable all qlog event types, except for transport:parameters_set and all supported event types in the connectivity category. iykyk 🧚

🦋 Filter Syntax Specification 🦋

formally bestie, the format of the filter specification in ABNF is exactly this:

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 / "_" / "-")

filter terms are interpreted like this:

  • "+*" (or "*") — enables all event types.
  • "-*" — disables all event types.
  • "+foo:*" (or "foo:*") — enables all event types in the foo category.
  • "-foo:*" — disables all event types in the foo category.
  • "+foo:bar" (or "foo:bar") — enables a specific event type foo:bar.
  • "-foo:bar" — disables a specific event type foo:bar.
🙈 partial wildcard matches are not supported at this time. sorry bestie.

💜 Default Configuration 💜

if the OSSL_QFILTER environment variable is not set, or it's set to the empty string, that's equivalent to enabling all event types — i.e. it's equivalent to a filter of "*". but heads up: the QLOGDIR environment variable must also be set to enable qlog. both of them, together, or nothing. 🫶

💀 FORMAT STABILITY 💀

the OpenSSL qlog functionality currently implements a draft version of the qlog specification. future revisions to the qlog spec, before formal standardisation, are expected to introduce incompatible and breaking changes to the qlog format. once standardisation is complete, the OpenSSL qlog functionality will transition to producing output in this format in the future.

because of that, OpenSSL's qlog output will change in incompatible and breaking ways in the future — including in non-major releases of OpenSSL. OpenSSL's qlog output is considered unstable and is not subject to any format stability or compatibility guarantees at this time.

users of the OpenSSL qlog functionality must be aware that the output may change arbitrarily between releases, and that preservation of compatibility with any given tool between releases is not guaranteed. it's giving chaos, but make it documented. 😭

⭐ Aims ⭐

the OpenSSL draft qlog functionality is primarily intended for use alongside the qvis tool, which lives at https://qvis.quictools.info/. in terms of format compatibility, the output format of the OpenSSL qlog functionality is expected to track what qvis supports. so future changes to OpenSSL's qlog output are expected to track changes in qvis as they occur, and to reflect the versions of qlog currently supported by qvis.

this means that before the qlog standard is finalised, if there's a disparity between the current draft and what qvis supports, OpenSSL's qlog functionality will generally aim for qvis compatibility over compliance with the latest draft. iconic behaviour tbh 🌈

as such, OpenSSL's qlog functionality currently implements qlog version 0.3 as defined in draft-ietf-quic-qlog-main-schema-05 and draft-ietf-quic-qlog-quic-events-04. these revisions are intentionally used instead of more recent revisions — because qvis compatibility said so. 💅

🍓 LIMITATIONS 🍓

the OpenSSL implementation of qlog currently has these limitations, bestie, and we're not gonna pretend otherwise:

  • not all event types defined by the draft specification are implemented.
  • only the JSON-SEQ (.sqlog) output format is supported.
  • only the QLOGDIR environment variable is supported for configuring the qlog output directory. the standard QLOGFILE environment variable is not supported.
  • there is no API for programmatically enabling or controlling the qlog functionality.

👑 SEE ALSO 👑

🌸 HISTORY 🌸

this functionality was added in OpenSSL 3.3. a whole era. ✨

Copyright 2024 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at https://www.openssl.org/source/license.html.

and that's the whole page bestie!! 💖 this one shipped in OpenSSL 4.0.3, dated 2026-09-29, from the OpenSSL project — so go forth, set that QLOGDIR, and vibe check your QUIC connections. mwah 🎀🦋⭐

📦 where this page comes from