From: Hugo Landau Date: Tue, 23 Jan 2024 14:06:47 +0000 (+0000) Subject: QLOG: Add manpage openssl-qlog(7) X-Git-Tag: openssl-3.3.0-alpha1~198 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=82973bcf8704fb53596297678276685f98e96d45;p=thirdparty%2Fopenssl.git QLOG: Add manpage openssl-qlog(7) Reviewed-by: Matt Caswell Reviewed-by: Neil Horman (Merged from https://github.com/openssl/openssl/pull/22037) --- diff --git a/doc/build.info b/doc/build.info index c88399a1380..76fe803f410 100644 --- a/doc/build.info +++ b/doc/build.info @@ -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 \ diff --git a/doc/man7/openssl-env.pod b/doc/man7/openssl-env.pod index 922d3c1476c..0d1b05a1e32 100644 --- a/doc/man7/openssl-env.pod +++ b/doc/man7/openssl-env.pod @@ -87,6 +87,14 @@ See L, L. Specify a proxy hostname. See L. +=item B + +Specifies a QUIC QLOG output directory. See L. + +=item B + +Used to set a QUIC QLOG filter specification. See L. + =back =head1 COPYRIGHT diff --git a/doc/man7/openssl-qlog.pod b/doc/man7/openssl-qlog.pod new file mode 100644 index 00000000000..3888a3654bd --- /dev/null +++ b/doc/man7/openssl-qlog.pod @@ -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. + +B 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 change in +incompatible ways in future versions of OpenSSL. See B below +for details. + +=head1 USAGE + +The qlog functionality must be explicitly enabled at build time using the +I configure flag. + +When built with qlog support, qlog is enabled at run time by setting the +standard B 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 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 or +C, 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 + +=item B + +=item B + +=item B + +=item B + +=item B + +=item B + +=back + +=head1 FILTERS + +By default, all supported event types are logged. The B +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 event +type. + +=item C<-* transport:packet_sent> + +Disable all qlog event types, except for the B event type. + +=item C<-* connectivity:* transport:parameters_set> + +Disable all qlog event types, except for B and all +supported event types in the B 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) + +Enables all event types in the B category. + +=item C<-foo:*> + +Disables all event types in the B category. + +=item C<+foo:bar> (or C) + +Enables a specific event type B. + +=item C<-foo:bar> + +Disables a specific event type B. + +=back + +Partial wildcard matches are not supported at this time. + +=head2 Default Configuration + +If the B 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 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 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, 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. 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 and +B. 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 environment variable is supported for configuring the qlog +output directory. The standard B environment variable is not +supported. + +=item + +There is no API for programmatically enabling or controlling the qlog +functionality. + +=back + +=head1 SEE ALSO + +L, L + +=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. + +=cut