diff options
Diffstat (limited to 'upstream/archlinux/man7/openssl-qlog.7ssl')
| -rw-r--r-- | upstream/archlinux/man7/openssl-qlog.7ssl | 274 |
1 files changed, 274 insertions, 0 deletions
diff --git a/upstream/archlinux/man7/openssl-qlog.7ssl b/upstream/archlinux/man7/openssl-qlog.7ssl new file mode 100644 index 00000000..c83686aa --- /dev/null +++ b/upstream/archlinux/man7/openssl-qlog.7ssl @@ -0,0 +1,274 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "OPENSSL-QLOG 7ssl" +.TH OPENSSL-QLOG 7ssl 2024-04-28 3.3.0 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +openssl\-qlog \- OpenSSL qlog tracing functionality +.SH DESCRIPTION +.IX Header "DESCRIPTION" +OpenSSL has 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. +.PP +The qlog output generated by OpenSSL can be used to obtain diagnostic +visualisations of a given QUIC connection using tools such as \fBqvis\fR. +.PP +\&\fBWARNING:\fR 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 \fBwill\fR change in +incompatible ways in future versions of OpenSSL. See \fBFORMAT STABILITY\fR below +for details. +.SH USAGE +.IX Header "USAGE" +When OpenSSL is built with qlog support, qlog is enabled at run time by setting +the standard \fBQLOGDIR\fR 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. +.PP +Log files are generated in the \fI.sqlog\fR format based on JSON-SEQ (RFC 7464). +.PP +The filenames of generated log files under the specified \fBQLOGDIR\fR use the +following structure: +.PP +.Vb 1 +\& {connection_odcid}_{vantage_point_type}.sqlog +.Ve +.PP +where \fB{connection_odcid}\fR 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 \fB{vantage_point_type}\fR is either \f(CW\*(C`client\*(C'\fR or +\&\f(CW\*(C`server\*(C'\fR, reflecting the perspective of the endpoint producing the qlog output. +.PP +The qlog functionality can be disabled at OpenSSL build time using the +\&\fIno-unstable-qlog\fR configure flag. +.SH "SUPPORTED EVENT TYPES" +.IX Header "SUPPORTED EVENT TYPES" +The following event types are currently supported: +.IP \fBconnectivity:connection_started\fR 4 +.IX Item "connectivity:connection_started" +.PD 0 +.IP \fBconnectivity:connection_state_updated\fR 4 +.IX Item "connectivity:connection_state_updated" +.IP \fBconnectivity:connection_closed\fR 4 +.IX Item "connectivity:connection_closed" +.IP \fBtransport:parameters_set\fR 4 +.IX Item "transport:parameters_set" +.IP \fBtransport:packet_sent\fR 4 +.IX Item "transport:packet_sent" +.IP \fBtransport:packet_received\fR 4 +.IX Item "transport:packet_received" +.IP \fBrecovery:packet_lost\fR 4 +.IX Item "recovery:packet_lost" +.PD +.SH FILTERS +.IX Header "FILTERS" +By default, all supported event types are logged. The \fBOSSL_QFILTER\fR +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. +.SS Examples +.IX Subsection "Examples" +Here are some example filter specifications: +.ie n .IP """*"" (or ""+*"")" 4 +.el .IP "\f(CW*\fR (or \f(CW+*\fR)" 4 +.IX Item "* (or +*)" +Enable all supported qlog event types. +.ie n .IP """\-*""" 4 +.el .IP \f(CW\-*\fR 4 +.IX Item "-*" +Disable all qlog event types. +.ie n .IP """* \-transport:packet_received""" 4 +.el .IP "\f(CW* \-transport:packet_received\fR" 4 +.IX Item "* -transport:packet_received" +Enable all qlog event types, but disable the \fBtransport:packet_received\fR event +type. +.ie n .IP """\-* transport:packet_sent""" 4 +.el .IP "\f(CW\-* transport:packet_sent\fR" 4 +.IX Item "-* transport:packet_sent" +Disable all qlog event types, except for the \fBtransport:packet_sent\fR event type. +.ie n .IP """\-* connectivity:* transport:parameters_set""" 4 +.el .IP "\f(CW\-* connectivity:* transport:parameters_set\fR" 4 +.IX Item "-* connectivity:* transport:parameters_set" +Disable all qlog event types, except for \fBtransport:parameters_set\fR and all +supported event types in the \fBconnectivity\fR category. +.SS "Filter Syntax Specification" +.IX Subsection "Filter Syntax Specification" +Formally, the format of the filter specification in ABNF is as follows: +.PP +.Vb 1 +\& 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 / "_" / "\-") +.Ve +.PP +Filter terms are interpreted as follows: +.ie n .IP """+*"" (or ""*"")" 4 +.el .IP "\f(CW+*\fR (or \f(CW*\fR)" 4 +.IX Item "+* (or *)" +Enables all event types. +.ie n .IP """\-*""" 4 +.el .IP \f(CW\-*\fR 4 +.IX Item "-*" +Disables all event types. +.ie n .IP """+foo:*"" (or ""foo:*"")" 4 +.el .IP "\f(CW+foo:*\fR (or \f(CWfoo:*\fR)" 4 +.IX Item "+foo:* (or foo:*)" +Enables all event types in the \fBfoo\fR category. +.ie n .IP """\-foo:*""" 4 +.el .IP \f(CW\-foo:*\fR 4 +.IX Item "-foo:*" +Disables all event types in the \fBfoo\fR category. +.ie n .IP """+foo:bar"" (or ""foo:bar"")" 4 +.el .IP "\f(CW+foo:bar\fR (or \f(CWfoo:bar\fR)" 4 +.IX Item "+foo:bar (or foo:bar)" +Enables a specific event type \fBfoo:bar\fR. +.ie n .IP """\-foo:bar""" 4 +.el .IP \f(CW\-foo:bar\fR 4 +.IX Item "-foo:bar" +Disables a specific event type \fBfoo:bar\fR. +.PP +Partial wildcard matches are not supported at this time. +.SS "Default Configuration" +.IX Subsection "Default Configuration" +If the \fBOSSL_QFILTER\fR environment variable is not set or set to the empty +string, this is equivalent to enabling all event types (i.e., it is equivalent +to a filter of \f(CW\*(C`*\*(C'\fR). Note that the \fBQLOGDIR\fR environment variable must also be +set to enable qlog. +.SH "FORMAT STABILITY" +.IX Header "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. +.PP +Because of this, the qlog output of OpenSSL \fBwill\fR 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. +.PP +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. +.SS Aims +.IX Subsection "Aims" +The OpenSSL draft qlog functionality is primarily intended for use in +conjunction with the qvis tool <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. +.PP +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. +.PP +As such, OpenSSL's qlog functionality currently implements qlog version 0.3 as +defined in \fBdraft\-ietf\-quic\-qlog\-main\-schema\-05\fR and +\&\fBdraft\-ietf\-quic\-qlog\-quic\-events\-04\fR. These revisions are intentionally used +instead of more recent revisions due to their qvis compatibility. +.SH LIMITATIONS +.IX Header "LIMITATIONS" +The OpenSSL implementation of qlog currently has the following limitations: +.IP \(bu 4 +Not all event types defined by the draft specification are implemented. +.IP \(bu 4 +Only the JSON-SEQ (\fB.sqlog\fR) output format is supported. +.IP \(bu 4 +Only the \fBQLOGDIR\fR environment variable is supported for configuring the qlog +output directory. The standard \fBQLOGFILE\fR environment variable is not +supported. +.IP \(bu 4 +There is no API for programmatically enabling or controlling the qlog +functionality. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBopenssl\-quic\fR\|(7), \fBopenssl\-env\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +This functionality was added in OpenSSL 3.3. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +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 +<https://www.openssl.org/source/license.html>. |