mirror of https://github.com/openssl/openssl.git
249 lines
7.4 KiB
Plaintext
249 lines
7.4 KiB
Plaintext
=pod
|
|
|
|
=head1 NAME
|
|
|
|
openssl-qlog - OpenSSL qlog tracing functionality
|
|
|
|
=head1 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 B<qvis>.
|
|
|
|
B<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 B<will> change in
|
|
incompatible ways in future versions of OpenSSL. See B<FORMAT STABILITY> below
|
|
for details.
|
|
|
|
=head1 USAGE
|
|
|
|
When OpenSSL is built with qlog support, qlog is enabled at run time by setting
|
|
the standard B<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 I<.sqlog> format based on JSON-SEQ (RFC 7464).
|
|
|
|
The filenames of generated log files under the specified B<QLOGDIR> use the
|
|
following structure:
|
|
|
|
{connection_odcid}_{vantage_point_type}.sqlog
|
|
|
|
where B<{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 B<{vantage_point_type}> is either C<client> or
|
|
C<server>, reflecting the perspective of the endpoint producing the qlog output.
|
|
|
|
The qlog functionality can be disabled at OpenSSL build time using the
|
|
I<no-unstable-qlog> configure flag.
|
|
|
|
=head1 SUPPORTED EVENT TYPES
|
|
|
|
The following event types are currently supported:
|
|
|
|
=over 4
|
|
|
|
=item B<connectivity:connection_started>
|
|
|
|
=item B<connectivity:connection_state_updated>
|
|
|
|
=item B<connectivity:connection_closed>
|
|
|
|
=item B<transport:parameters_set>
|
|
|
|
=item B<transport:packet_sent>
|
|
|
|
=item B<transport:packet_received>
|
|
|
|
=item B<recovery:packet_lost>
|
|
|
|
=back
|
|
|
|
=head1 FILTERS
|
|
|
|
By default, all supported event types are logged. The B<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.
|
|
|
|
=head2 Examples
|
|
|
|
Here are some example filter specifications:
|
|
|
|
=over 4
|
|
|
|
=item C<*> (or C<+*>)
|
|
|
|
Enable all supported qlog event types.
|
|
|
|
=item C<-*>
|
|
|
|
Disable all qlog event types.
|
|
|
|
=item C<* -transport:packet_received>
|
|
|
|
Enable all qlog event types, but disable the B<transport:packet_received> event
|
|
type.
|
|
|
|
=item C<-* transport:packet_sent>
|
|
|
|
Disable all qlog event types, except for the B<transport:packet_sent> event type.
|
|
|
|
=item C<-* connectivity:* transport:parameters_set>
|
|
|
|
Disable all qlog event types, except for B<transport:parameters_set> and all
|
|
supported event types in the B<connectivity> category.
|
|
|
|
=back
|
|
|
|
=head2 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:
|
|
|
|
=over 4
|
|
|
|
=item C<+*> (or C<*>)
|
|
|
|
Enables all event types.
|
|
|
|
=item C<-*>
|
|
|
|
Disables all event types.
|
|
|
|
=item C<+foo:*> (or C<foo:*>)
|
|
|
|
Enables all event types in the B<foo> category.
|
|
|
|
=item C<-foo:*>
|
|
|
|
Disables all event types in the B<foo> category.
|
|
|
|
=item C<+foo:bar> (or C<foo:bar>)
|
|
|
|
Enables a specific event type B<foo:bar>.
|
|
|
|
=item C<-foo:bar>
|
|
|
|
Disables a specific event type B<foo:bar>.
|
|
|
|
=back
|
|
|
|
Partial wildcard matches are not supported at this time.
|
|
|
|
=head2 Default Configuration
|
|
|
|
If the B<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 C<*>). Note that the B<QLOGDIR> environment variable must also be
|
|
set to enable qlog.
|
|
|
|
=head1 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 B<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.
|
|
|
|
=head2 Aims
|
|
|
|
The OpenSSL draft qlog functionality is primarily intended for use in
|
|
conjunction with the qvis tool L<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 B<draft-ietf-quic-qlog-main-schema-05> and
|
|
B<draft-ietf-quic-qlog-quic-events-04>. These revisions are intentionally used
|
|
instead of more recent revisions due to their qvis compatibility.
|
|
|
|
=head1 LIMITATIONS
|
|
|
|
The OpenSSL implementation of qlog currently has the following limitations:
|
|
|
|
=over 4
|
|
|
|
=item
|
|
|
|
Not all event types defined by the draft specification are implemented.
|
|
|
|
=item
|
|
|
|
Only the JSON-SEQ (B<.sqlog>) output format is supported.
|
|
|
|
=item
|
|
|
|
Only the B<QLOGDIR> environment variable is supported for configuring the qlog
|
|
output directory. The standard B<QLOGFILE> environment variable is not
|
|
supported.
|
|
|
|
=item
|
|
|
|
There is no API for programmatically enabling or controlling the qlog
|
|
functionality.
|
|
|
|
=back
|
|
|
|
=head1 SEE ALSO
|
|
|
|
L<openssl-quic(7)>, L<openssl-env(7)>
|
|
|
|
=head1 HISTORY
|
|
|
|
This functionality was added in OpenSSL 3.3.
|
|
|
|
=head1 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
|
|
L<https://www.openssl.org/source/license.html>.
|
|
|
|
=cut
|