Debian Codegraph @

upstream/debian-unstable/man7/openssl-qlog.7ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "OPENSSL-QLOG 7SSL"
58 .TH OPENSSL-QLOG 7SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 openssl\-qlog \- OpenSSL qlog tracing functionality
65 .SH DESCRIPTION
66 .IX Header "DESCRIPTION"
67 OpenSSL has unstable support for generating logs in the qlog logging format,
68 which can be used to obtain diagnostic data for QUIC connections. The data
69 generated includes information on packets sent and received and the frames
70 contained within them, as well as loss detection and other events.
71 .PP
72 The qlog output generated by OpenSSL can be used to obtain diagnostic
73 visualisations of a given QUIC connection using tools such as \fBqvis\fR.
74 .PP
75 \&\fBWARNING:\fR The output of OpenSSL's qlog functionality uses an unstable format
76 based on a draft specification. qlog output is not subject to any format
77 stability or compatibility guarantees at this time, and \fBwill\fR change in
78 incompatible ways in future versions of OpenSSL. See \fBFORMAT STABILITY\fR below
79 for details.
80 .SH USAGE
81 .IX Header "USAGE"
82 When OpenSSL is built with qlog support, qlog is enabled at run time by setting
83 the standard \fBQLOGDIR\fR environment variable to point to a directory where qlog
84 files should be written. Once set, any QUIC connection established by OpenSSL
85 will have a qlog file written automatically to the specified directory.
86 .PP
87 Log files are generated in the \fI.sqlog\fR format based on JSON-SEQ (RFC 7464).
88 .PP
89 The filenames of generated log files under the specified \fBQLOGDIR\fR use the
90 following structure:
91 .PP
92 .Vb 1
93 \& {connection_odcid}_{vantage_point_type}.sqlog
94 .Ve
95 .PP
96 where \fB{connection_odcid}\fR is the lowercase hexadecimal encoding of a QUIC
97 connection's Original Destination Connection ID, which is the Destination
98 Connection ID used in the header of the first Initial packet sent as part of the
99 connection process, and \fB{vantage_point_type}\fR is either \f(CW\*(C`client\*(C'\fR or
100 \&\f(CW\*(C`server\*(C'\fR, reflecting the perspective of the endpoint producing the qlog output.
101 .PP
102 The qlog functionality can be disabled at OpenSSL build time using the
103 \&\fIno-unstable-qlog\fR configure flag.
104 .SH "SUPPORTED EVENT TYPES"
105 .IX Header "SUPPORTED EVENT TYPES"
106 The following event types are currently supported:
107 .IP \fBconnectivity:connection_started\fR 4
108 .IX Item "connectivity:connection_started"
109 .PD 0
110 .IP \fBconnectivity:connection_state_updated\fR 4
111 .IX Item "connectivity:connection_state_updated"
112 .IP \fBconnectivity:connection_closed\fR 4
113 .IX Item "connectivity:connection_closed"
114 .IP \fBtransport:parameters_set\fR 4
115 .IX Item "transport:parameters_set"
116 .IP \fBtransport:packet_sent\fR 4
117 .IX Item "transport:packet_sent"
118 .IP \fBtransport:packet_received\fR 4
119 .IX Item "transport:packet_received"
120 .IP \fBrecovery:packet_lost\fR 4
121 .IX Item "recovery:packet_lost"
122 .PD
123 .SH FILTERS
124 .IX Header "FILTERS"
125 By default, all supported event types are logged. The \fBOSSL_QFILTER\fR
126 environment variable can be used to configure a filter specification which
127 determines which event types are to be logged. Each event type can be turned on
128 and off individually. The filter specification is a space-separated list of
129 terms listing event types to enable or disable. The terms are applied in order,
130 thus the effects of later terms override the effects of earlier terms.
131 .SS Examples
132 .IX Subsection "Examples"
133 Here are some example filter specifications:
134 .ie n .IP """*"" (or ""+*"")" 4
135 .el .IP "\f(CW*\fR (or \f(CW+*\fR)" 4
136 .IX Item "* (or +*)"
137 Enable all supported qlog event types.
138 .ie n .IP """\-*""" 4
139 .el .IP \f(CW\-*\fR 4
140 .IX Item "-*"
141 Disable all qlog event types.
142 .ie n .IP """* \-transport:packet_received""" 4
143 .el .IP "\f(CW* \-transport:packet_received\fR" 4
144 .IX Item "* -transport:packet_received"
145 Enable all qlog event types, but disable the \fBtransport:packet_received\fR event
146 type.
147 .ie n .IP """\-* transport:packet_sent""" 4
148 .el .IP "\f(CW\-* transport:packet_sent\fR" 4
149 .IX Item "-* transport:packet_sent"
150 Disable all qlog event types, except for the \fBtransport:packet_sent\fR event type.
151 .ie n .IP """\-* connectivity:* transport:parameters_set""" 4
152 .el .IP "\f(CW\-* connectivity:* transport:parameters_set\fR" 4
153 .IX Item "-* connectivity:* transport:parameters_set"
154 Disable all qlog event types, except for \fBtransport:parameters_set\fR and all
155 supported event types in the \fBconnectivity\fR category.
156 .SS "Filter Syntax Specification"
157 .IX Subsection "Filter Syntax Specification"
158 Formally, the format of the filter specification in ABNF is as follows:
159 .PP
160 .Vb 1
161 \& filter = *filter\-term
162 \&
163 \& filter\-term = add\-sub\-term
164 \&
165 \& add\-sub\-term = ["\-" / "+"] specifier
166 \&
167 \& specifier = global\-specifier / qualified\-specifier
168 \&
169 \& global\-specifier = wildcard
170 \&
171 \& qualified\-specifier = component\-specifier ":" component\-specifier
172 \&
173 \& component\-specifier = name / wildcard
174 \&
175 \& wildcard = "*"
176 \&
177 \& name = 1*(ALPHA / DIGIT / "_" / "\-")
178 .Ve
179 .PP
180 Filter terms are interpreted as follows:
181 .ie n .IP """+*"" (or ""*"")" 4
182 .el .IP "\f(CW+*\fR (or \f(CW*\fR)" 4
183 .IX Item "+* (or *)"
184 Enables all event types.
185 .ie n .IP """\-*""" 4
186 .el .IP \f(CW\-*\fR 4
187 .IX Item "-*"
188 Disables all event types.
189 .ie n .IP """+foo:*"" (or ""foo:*"")" 4
190 .el .IP "\f(CW+foo:*\fR (or \f(CWfoo:*\fR)" 4
191 .IX Item "+foo:* (or foo:*)"
192 Enables all event types in the \fBfoo\fR category.
193 .ie n .IP """\-foo:*""" 4
194 .el .IP \f(CW\-foo:*\fR 4
195 .IX Item "-foo:*"
196 Disables all event types in the \fBfoo\fR category.
197 .ie n .IP """+foo:bar"" (or ""foo:bar"")" 4
198 .el .IP "\f(CW+foo:bar\fR (or \f(CWfoo:bar\fR)" 4
199 .IX Item "+foo:bar (or foo:bar)"
200 Enables a specific event type \fBfoo:bar\fR.
201 .ie n .IP """\-foo:bar""" 4
202 .el .IP \f(CW\-foo:bar\fR 4
203 .IX Item "-foo:bar"
204 Disables a specific event type \fBfoo:bar\fR.
205 .PP
206 Partial wildcard matches are not supported at this time.
207 .SS "Default Configuration"
208 .IX Subsection "Default Configuration"
209 If the \fBOSSL_QFILTER\fR environment variable is not set or set to the empty
210 string, this is equivalent to enabling all event types (i.e., it is equivalent
211 to a filter of \f(CW\*(C`*\*(C'\fR). Note that the \fBQLOGDIR\fR environment variable must also be
212 set to enable qlog.
213 .SH "FORMAT STABILITY"
214 .IX Header "FORMAT STABILITY"
215 The OpenSSL qlog functionality currently implements a draft version of the qlog
216 specification. Future revisions to the qlog specification in advance of formal
217 standardisation are expected to introduce incompatible and breaking changes to
218 the qlog format. The OpenSSL qlog functionality will transition to producing
219 output in this format in the future once standardisation is complete.
220 .PP
221 Because of this, the qlog output of OpenSSL \fBwill\fR change in incompatible and
222 breaking ways in the future, including in non-major releases of OpenSSL. The
223 qlog output of OpenSSL is considered unstable and not subject to any format
224 stability or compatibility guarantees at this time.
225 .PP
226 Users of the OpenSSL qlog functionality must be aware that the output may change
227 arbitrarily between releases and that the preservation of compatibility with any
228 given tool between releases is not guaranteed.
229 .SS Aims
230 .IX Subsection "Aims"
231 The OpenSSL draft qlog functionality is primarily intended for use in
232 conjunction with the qvis tool <https://qvis.quictools.info/>. In terms of
233 format compatibility, the output format of the OpenSSL qlog functionality is
234 expected to track what is supported by qvis. As such, future changes to the
235 output of the OpenSSL qlog functionality are expected to track changes in qvis
236 as they occur, and reflect the versions of qlog currently supported by qvis.
237 .PP
238 This means that prior to the finalisation of the qlog standard, in the event of
239 a disparity between the current draft and what qvis supports, the OpenSSL qlog
240 functionality will generally aim for qvis compatibility over compliance with the
241 latest draft.
242 .PP
243 As such, OpenSSL's qlog functionality currently implements qlog version 0.3 as
244 defined in \fBdraft\-ietf\-quic\-qlog\-main\-schema\-05\fR and
245 \&\fBdraft\-ietf\-quic\-qlog\-quic\-events\-04\fR. These revisions are intentionally used
246 instead of more recent revisions due to their qvis compatibility.
247 .SH LIMITATIONS
248 .IX Header "LIMITATIONS"
249 The OpenSSL implementation of qlog currently has the following limitations:
250 .IP \(bu 4
251 Not all event types defined by the draft specification are implemented.
252 .IP \(bu 4
253 Only the JSON-SEQ (\fB.sqlog\fR) output format is supported.
254 .IP \(bu 4
255 Only the \fBQLOGDIR\fR environment variable is supported for configuring the qlog
256 output directory. The standard \fBQLOGFILE\fR environment variable is not
257 supported.
258 .IP \(bu 4
259 There is no API for programmatically enabling or controlling the qlog
260 functionality.
261 .SH "SEE ALSO"
262 .IX Header "SEE ALSO"
263 \&\fBopenssl\-quic\fR\|(7), \fBopenssl\-env\fR\|(7)
264 .SH HISTORY
265 .IX Header "HISTORY"
266 This functionality was added in OpenSSL 3.3.
267 .SH COPYRIGHT
268 .IX Header "COPYRIGHT"
269 Copyright 2024 The OpenSSL Project Authors. All Rights Reserved.
270 .PP
271 Licensed under the Apache License 2.0 (the "License"). You may not use
272 this file except in compliance with the License. You can obtain a copy
273 in the file LICENSE in the source distribution or at
274 <https://www.openssl.org/source/license.html>.