--- /dev/null
+=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
projects / openssl.git / commitdiff