OPENSSL-QLOG(7ossl) OpenSSL OPENSSL-QLOG(7ossl)
NAME
openssl-qlog - OpenSSL qlog tracing functionality
DESCRIPTION
OpenSSL has unstable support for generating logs in the qlog logging
format, which can be used to obtain diagnostic data for QUIC
connections. The data generated includes information on packets sent
and received and the frames contained within them, as well as loss
detection and other events.
The qlog output generated by OpenSSL can be used to obtain diagnostic
visualisations of a given QUIC connection using tools such as qvis.
WARNING: The output of 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 at this time, and will
change in incompatible ways in future versions of OpenSSL. See FORMAT
STABILITY below for details.
USAGE
When OpenSSL is built with qlog support, qlog is enabled at run time by
setting the standard QLOGDIR environment variable to point to a
directory where qlog files should be written. Once set, any QUIC
connection established by OpenSSL will have a qlog file written
automatically to the specified directory.
Log files are generated in the .sqlog format based on JSON-SEQ (RFC
7464).
The filenames of generated log files under the specified QLOGDIR use
the following structure:
{connection_odcid}_{vantage_point_type}.sqlog
where {connection_odcid} is the lowercase hexadecimal encoding of a
QUIC connection's Original Destination Connection ID, which is the
Destination Connection ID used in the header of the first Initial
packet sent as part of the connection process, and {vantage_point_type}
is either "client" or "server", reflecting the perspective of the
endpoint producing the qlog output.
The qlog functionality can be disabled at OpenSSL build time using the
no-unstable-qlog configure flag.
SUPPORTED EVENT TYPES
The following event types are currently supported:
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 are logged. The OSSL_QFILTER
environment variable can be used to configure a filter specification
which determines which event types are to be logged. Each event type
can be turned on and off individually. The filter specification is a
space-separated list of terms listing event types to enable or disable.
The terms are applied in order, thus the effects of later terms
override the effects of earlier terms.
Examples
Here are some example filter specifications:
"*" (or "+*")
Enable all supported qlog event types.
"-*"
Disable all qlog event types.
"* -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.
Filter Syntax Specification
Formally, the format of the filter specification in ABNF is as follows:
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 as follows:
"+*" (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.
Default Configuration
If the OSSL_QFILTER environment variable is not set or set to the empty
string, this is equivalent to enabling all event types (i.e., it is
equivalent to a filter of "*"). Note that the QLOGDIR environment
variable must also be set to enable qlog.
FORMAT STABILITY
The OpenSSL qlog functionality currently implements a draft version of
the qlog specification. Future revisions to the qlog specification in
advance of formal standardisation are expected to introduce
incompatible and breaking changes to the qlog format. The OpenSSL qlog
functionality will transition to producing output in this format in the
future once standardisation is complete.
Because of this, the qlog output of OpenSSL will change in incompatible
and breaking ways in the future, including in non-major releases of
OpenSSL. The qlog output of OpenSSL is considered unstable and 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 the preservation of
compatibility with any given tool between releases is not guaranteed.
Aims
The OpenSSL draft qlog functionality is primarily intended for use in
conjunction with the qvis tool <https://qvis.quictools.info/>. In terms
of format compatibility, the output format of the OpenSSL qlog
functionality is expected to track what is supported by qvis. As such,
future changes to the output of the OpenSSL qlog functionality are
expected to track changes in qvis as they occur, and reflect the
versions of qlog currently supported by qvis.
This means that prior to the finalisation of the qlog standard, in the
event of a disparity between the current draft and what qvis supports,
the OpenSSL qlog functionality will generally aim for qvis
compatibility over compliance with the latest draft.
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 due to their qvis compatibility.
LIMITATIONS
The OpenSSL implementation of qlog currently has the following
limitations:
o Not all event types defined by the draft specification are
implemented.
o Only the JSON-SEQ (.sqlog) output format is supported.
o Only the QLOGDIR environment variable is supported for configuring
the qlog output directory. The standard QLOGFILE environment
variable is not supported.
o There is no API for programmatically enabling or controlling the
qlog functionality.
SEE ALSO
openssl-quic(7), openssl-env(7)
HISTORY
This functionality was added in OpenSSL 3.3.
COPYRIGHT
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>.
3.3.2 2024-09-04 OPENSSL-QLOG(7ossl)
openssl 3.3.2 - Generated Tue Oct 1 16:25:24 CDT 2024