mirror/openssl
2
0
Fork 0
mirror of https://github.com/openssl/openssl.git synced 2025-01-18 13:44:20 +08:00
Code Issues Packages Projects Releases Wiki Activity

QLOG: Add manpage openssl-qlog(7)

Browse Source 
Reviewed-by: Matt Caswell <matt@openssl.org>
Reviewed-by: Neil Horman <nhorman@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/22037)
This commit is contained in:
Hugo Landau 2024-01-23 14:06:47 +00:00
parent d8b405a27c
commit 82973bcf87
3 changed files with 262 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
doc/build.info
View File

@ -4765,6 +4765,10 @@ DEPEND[html/man7/openssl-glossary.html]=man7/openssl-glossary.pod
GENERATE[html/man7/openssl-glossary.html]=man7/openssl-glossary.pod
DEPEND[man/man7/openssl-glossary.7]=man7/openssl-glossary.pod
GENERATE[man/man7/openssl-glossary.7]=man7/openssl-glossary.pod
DEPEND[html/man7/openssl-qlog.html]=man7/openssl-qlog.pod
GENERATE[html/man7/openssl-qlog.html]=man7/openssl-qlog.pod
DEPEND[man/man7/openssl-qlog.7]=man7/openssl-qlog.pod
GENERATE[man/man7/openssl-qlog.7]=man7/openssl-qlog.pod
DEPEND[html/man7/openssl-quic.html]=man7/openssl-quic.pod
GENERATE[html/man7/openssl-quic.html]=man7/openssl-quic.pod
DEPEND[man/man7/openssl-quic.7]=man7/openssl-quic.pod
@ -5026,6 +5030,7 @@ html/man7/openssl-core_dispatch.h.html \
html/man7/openssl-core_names.h.html \
html/man7/openssl-env.html \
html/man7/openssl-glossary.html \
html/man7/openssl-qlog.html \
html/man7/openssl-quic.html \
html/man7/openssl-threads.html \
html/man7/openssl_user_macros.html \
@ -5168,6 +5173,7 @@ man/man7/openssl-core_dispatch.h.7 \
man/man7/openssl-core_names.h.7 \
man/man7/openssl-env.7 \
man/man7/openssl-glossary.7 \
man/man7/openssl-qlog.7 \
man/man7/openssl-quic.7 \
man/man7/openssl-threads.7 \
man/man7/openssl_user_macros.7 \

8
doc/man7/openssl-env.pod
View File

@ -87,6 +87,14 @@ See L<OPENSSL_ia32cap(3)>, L<OPENSSL_s390xcap(3)>.
Specify a proxy hostname.
See L<OSSL_HTTP_parse_url(3)>.
=item B<QLOGDIR>
Specifies a QUIC QLOG output directory. See L<openssl-qlog(7)>.
=item B<OSSL_QFILTER>
Used to set a QUIC QLOG filter specification. See L<openssl-qlog(7)>.
=back
=head1 COPYRIGHT

248
doc/man7/openssl-qlog.pod Normal file
View File

@ -0,0 +1,248 @@
=pod
=head1 NAME
openssl-qlog - OpenSSL qlog tracing functionality
=head1 DESCRIPTION
OpenSSL 3.3 and later feature 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
The qlog functionality must be explicitly enabled at build time using the
I<enable-unstable-qlog> configure flag.
When 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.
=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 events (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.
As such, the qlog functionality is currently guarded behind the build-time
configuration flag B<enable-unstable-qlog>, which is not enabled by default, to
ensure that users are aware of this instability. 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 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