1=pod 2 3=head1 NAME 4 5openssl-qlog - OpenSSL qlog tracing functionality 6 7=head1 DESCRIPTION 8 9OpenSSL has unstable support for generating logs in the qlog logging format, 10which can be used to obtain diagnostic data for QUIC connections. The data 11generated includes information on packets sent and received and the frames 12contained within them, as well as loss detection and other events. 13 14The qlog output generated by OpenSSL can be used to obtain diagnostic 15visualisations of a given QUIC connection using tools such as B<qvis>. 16 17B<WARNING:> The output of OpenSSL's qlog functionality uses an unstable format 18based on a draft specification. qlog output is not subject to any format 19stability or compatibility guarantees at this time, and B<will> change in 20incompatible ways in future versions of OpenSSL. See B<FORMAT STABILITY> below 21for details. 22 23=head1 USAGE 24 25When OpenSSL is built with qlog support, qlog is enabled at run time by setting 26the standard B<QLOGDIR> environment variable to point to a directory where qlog 27files should be written. Once set, any QUIC connection established by OpenSSL 28will have a qlog file written automatically to the specified directory. 29 30Log files are generated in the I<.sqlog> format based on JSON-SEQ (RFC 7464). 31 32The filenames of generated log files under the specified B<QLOGDIR> use the 33following structure: 34 35 {connection_odcid}_{vantage_point_type}.sqlog 36 37where B<{connection_odcid}> is the lowercase hexadecimal encoding of a QUIC 38connection's Original Destination Connection ID, which is the Destination 39Connection ID used in the header of the first Initial packet sent as part of the 40connection process, and B<{vantage_point_type}> is either C<client> or 41C<server>, reflecting the perspective of the endpoint producing the qlog output. 42 43The qlog functionality can be disabled at OpenSSL build time using the 44I<no-unstable-qlog> configure flag. 45 46=head1 SUPPORTED EVENT TYPES 47 48The following event types are currently supported: 49 50=over 4 51 52=item B<connectivity:connection_started> 53 54=item B<connectivity:connection_state_updated> 55 56=item B<connectivity:connection_closed> 57 58=item B<transport:parameters_set> 59 60=item B<transport:packet_sent> 61 62=item B<transport:packet_received> 63 64=item B<recovery:packet_lost> 65 66=back 67 68=head1 FILTERS 69 70By default, all supported event types are logged. The B<OSSL_QFILTER> 71environment variable can be used to configure a filter specification which 72determines which event types are to be logged. Each event type can be turned on 73and off individually. The filter specification is a space-separated list of 74terms listing event types to enable or disable. The terms are applied in order, 75thus the effects of later terms override the effects of earlier terms. 76 77=head2 Examples 78 79Here are some example filter specifications: 80 81=over 4 82 83=item C<*> (or C<+*>) 84 85Enable all supported qlog event types. 86 87=item C<-*> 88 89Disable all qlog event types. 90 91=item C<* -transport:packet_received> 92 93Enable all qlog event types, but disable the B<transport:packet_received> event 94type. 95 96=item C<-* transport:packet_sent> 97 98Disable all qlog event types, except for the B<transport:packet_sent> event type. 99 100=item C<-* connectivity:* transport:parameters_set> 101 102Disable all qlog event types, except for B<transport:parameters_set> and all 103supported event types in the B<connectivity> category. 104 105=back 106 107=head2 Filter Syntax Specification 108 109Formally, the format of the filter specification in ABNF is as follows: 110 111 filter = *filter-term 112 113 filter-term = add-sub-term 114 115 add-sub-term = ["-" / "+"] specifier 116 117 specifier = global-specifier / qualified-specifier 118 119 global-specifier = wildcard 120 121 qualified-specifier = component-specifier ":" component-specifier 122 123 component-specifier = name / wildcard 124 125 wildcard = "*" 126 127 name = 1*(ALPHA / DIGIT / "_" / "-") 128 129Filter terms are interpreted as follows: 130 131=over 4 132 133=item C<+*> (or C<*>) 134 135Enables all event types. 136 137=item C<-*> 138 139Disables all event types. 140 141=item C<+foo:*> (or C<foo:*>) 142 143Enables all event types in the B<foo> category. 144 145=item C<-foo:*> 146 147Disables all event types in the B<foo> category. 148 149=item C<+foo:bar> (or C<foo:bar>) 150 151Enables a specific event type B<foo:bar>. 152 153=item C<-foo:bar> 154 155Disables a specific event type B<foo:bar>. 156 157=back 158 159Partial wildcard matches are not supported at this time. 160 161=head2 Default Configuration 162 163If the B<OSSL_QFILTER> environment variable is not set or set to the empty 164string, this is equivalent to enabling all event types (i.e., it is equivalent 165to a filter of C<*>). Note that the B<QLOGDIR> environment variable must also be 166set to enable qlog. 167 168=head1 FORMAT STABILITY 169 170The OpenSSL qlog functionality currently implements a draft version of the qlog 171specification. Future revisions to the qlog specification in advance of formal 172standardisation are expected to introduce incompatible and breaking changes to 173the qlog format. The OpenSSL qlog functionality will transition to producing 174output in this format in the future once standardisation is complete. 175 176Because of this, the qlog output of OpenSSL B<will> change in incompatible and 177breaking ways in the future, including in non-major releases of OpenSSL. The 178qlog output of OpenSSL is considered unstable and not subject to any format 179stability or compatibility guarantees at this time. 180 181Users of the OpenSSL qlog functionality must be aware that the output may change 182arbitrarily between releases and that the preservation of compatibility with any 183given tool between releases is not guaranteed. 184 185=head2 Aims 186 187The OpenSSL draft qlog functionality is primarily intended for use in 188conjunction with the qvis tool L<https://qvis.quictools.info/>. In terms of 189format compatibility, the output format of the OpenSSL qlog functionality is 190expected to track what is supported by qvis. As such, future changes to the 191output of the OpenSSL qlog functionality are expected to track changes in qvis 192as they occur, and reflect the versions of qlog currently supported by qvis. 193 194This means that prior to the finalisation of the qlog standard, in the event of 195a disparity between the current draft and what qvis supports, the OpenSSL qlog 196functionality will generally aim for qvis compatibility over compliance with the 197latest draft. 198 199As such, OpenSSL's qlog functionality currently implements qlog version 0.3 as 200defined in B<draft-ietf-quic-qlog-main-schema-05> and 201B<draft-ietf-quic-qlog-quic-events-04>. These revisions are intentionally used 202instead of more recent revisions due to their qvis compatibility. 203 204=head1 LIMITATIONS 205 206The OpenSSL implementation of qlog currently has the following limitations: 207 208=over 4 209 210=item 211 212Not all event types defined by the draft specification are implemented. 213 214=item 215 216Only the JSON-SEQ (B<.sqlog>) output format is supported. 217 218=item 219 220Only the B<QLOGDIR> environment variable is supported for configuring the qlog 221output directory. The standard B<QLOGFILE> environment variable is not 222supported. 223 224=item 225 226There is no API for programmatically enabling or controlling the qlog 227functionality. 228 229=back 230 231=head1 SEE ALSO 232 233L<openssl-quic(7)>, L<openssl-env(7)> 234 235=head1 HISTORY 236 237This functionality was added in OpenSSL 3.3. 238 239=head1 COPYRIGHT 240 241Copyright 2024 The OpenSSL Project Authors. All Rights Reserved. 242 243Licensed under the Apache License 2.0 (the "License"). You may not use 244this file except in compliance with the License. You can obtain a copy 245in the file LICENSE in the source distribution or at 246L<https://www.openssl.org/source/license.html>. 247 248=cut 249
