zzy/openssl
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

QLOG: Editorial fixes (QLOG is spelled 'qlog')

Browse Source 
Reviewed-by: Matt Caswell <matt@openssl.org>
Reviewed-by: Neil Horman <nhorman@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/22037)
This commit is contained in:
Hugo Landau 2024-01-23 14:13:49 +00:00
parent 82973bcf87
commit de60b122b2
13 changed files with 46 additions and 41 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
CHANGES.md
View File

@ -94,10 +94,10 @@ OpenSSL 3.3
*Randall S. Becker*
* Support for QLOG for tracing QUIC connections has been added.
* Support for qlog for tracing QUIC connections has been added.
The QLOG output from OpenSSL currently uses a pre-standard draft version of
QLOG. The output from OpenSSL will change in incompatible ways in future
The qlog output from OpenSSL currently uses a pre-standard draft version of
qlog. The output from OpenSSL will change in incompatible ways in future
releases, and is not subject to any format stability or compatibility
guarantees at this time; therefore this functionality must currently be
enabled with the build-time option `enable-unstable-qlog`. See the

4
Configure
View File

@ -2979,8 +2979,8 @@ print <<"EOF" if (!$disabled{qlog});
============================== WARNING ===============================
WARNING: You have enabled QLOG. This functionality is unstable and
implements a draft version of the QLOG specification. The QLOG
WARNING: You have enabled qlog. This functionality is unstable and
implements a draft version of the qlog specification. The qlog
output from OpenSSL *will* change in incompatible ways in future,
and is not subject to any format stability or compatibility
guarantees at this time. See the manpage openssl-qlog(7) for

4
INSTALL.md
View File

@ -1086,8 +1086,8 @@ This is only supported on systems where loading of shared libraries is supported
### enable-unstable-qlog
Enables QLOG output support for the QUIC protocol. This functionality is
unstable and implements a draft version of the QLOG specification. The QLOG
Enables qlog output support for the QUIC protocol. This functionality is
unstable and implements a draft version of the qlog specification. The qlog
output from OpenSSL will change in incompatible ways in future, and is not
subject to any format stability or compatibility guarantees at this time. See
the manpage openssl-qlog(7) for details.

24
doc/designs/quic-design/debugging.md
View File

@ -4,13 +4,13 @@ QUIC: Debugging and Tracing
When debugging the QUIC stack it is extremely useful to have protocol traces
available. There are two approaches you can use to obtain this data:
- QLOG
- qlog
- Packet capture
Neither of these approaches is strictly superior to the other and both have pros
and cons:
- In general, QLOG is aimed at storing only information relevant to the
- In general, qlog is aimed at storing only information relevant to the
QUIC protocol itself without storing bulk data. This includes both transmitted
and received packets but also information about the internal state of a QUIC
implementation which is not directly observable from the network.
@ -28,7 +28,7 @@ the logged data.
To summarise:
- QLOG:
- qlog:
- Pro: Smaller files
- Con: May leave out data assumed to be irrelevant
- Pro: Information on internal states and decisions made by a QUIC
@ -39,43 +39,43 @@ To summarise:
- Con: No direct information on internal states of a QUIC implementation
- Con: Need to obtain a keylog
Using QLOG
Using qlog
----------
To enable QLOG you must:
To enable qlog you must:
- build using the `enable-unstable-qlog` build-time configuration option;
- set the environment variable `QLOGDIR` to a directory where QLOG log files
- set the environment variable `QLOGDIR` to a directory where qlog log files
are to be written;
- set the environment variable `OSSL_QFILTER` to a filter specifying the events
you want to be written (set `OSSL_QFILTER='*'` for all events).
Any process using the libssl QUIC implementation will then automatically write
QLOG files in the JSON-SEQ format to the specified directory. The files have the
qlog files in the JSON-SEQ format to the specified directory. The files have the
naming convention recommended by the specification: `{ODCID}_{ROLE}.sqlog`,
where `{ODCID}` is the initial (original) DCID of a connection and `{ROLE}` is
`client` or `server`.
The log files can be loaded into [qvis](https://qvis.quictools.info/). The [qvis
website](https://qvis.quictools.info/) also has some sample QLOG files which you
website](https://qvis.quictools.info/) also has some sample qlog files which you
can load at the click of a button, which enables you to see what kind of
information qvis can offer you.
Note that since the QLOG specification is not finalised and still evolving,
Note that since the qlog specification is not finalised and still evolving,
the format of the output may change, as may the method of configuring this
logging support.
Currently this implementation tracks qvis's QLOG support, as that is the
Currently this implementation tracks qvis's qlog support, as that is the
main target use case at this time.
Note that since QLOG emphasises logging only data which is relevant to a QUIC
Note that since qlog emphasises logging only data which is relevant to a QUIC
protocol implementation, for the purposes of reducing the volume of logging
data, application data is generally not logged. (However, this is not a
guarantee and must not be relied upon from a privacy perspective.)
[See here for more details on the design of the QLOG facility.](qlog.md)
[See here for more details on the design of the qlog facility.](qlog.md)
Using PCAP
----------

4
doc/designs/quic-design/json-encoder.md
View File

@ -4,7 +4,7 @@ JSON Encoder
Approach
--------
The JSON encoder exists to support QLOG implementation. There is no intention to
The JSON encoder exists to support qlog implementation. There is no intention to
implement a decoder at this time. The encoder is intended to support automation
using immediate calls without the use of an intermediate syntax tree
representation and is expected to be zero-allocation in most cases. This enables
@ -66,7 +66,7 @@ JSON-SEQ
--------
The encoder supports JSON-SEQ (RFC 7464), as this is an optimal format for
outputting QLOG for our purposes.
outputting qlog for our purposes.
Number Handling
---------------

25
doc/designs/quic-design/qlog.md
View File

@ -1,15 +1,15 @@
QLOG Support
qlog Support
============
QLOG support is formed of two components:
qlog support is formed of two components:
- A QLOG API and implementation.
- A JSON encoder API and implementation, which is used by the QLOG
- A qlog API and implementation.
- A JSON encoder API and implementation, which is used by the qlog
implementation.
The API for the JSON encoder is detailed in [a separate document](json-encoder.md).
QLOG support will involve instrumenting various functions with QLOG logging
qlog support will involve instrumenting various functions with qlog logging
code. An example call site will look something like this:
```c
@ -29,7 +29,7 @@ code. An example call site will look something like this:
Output Format
-------------
The output format will always be the JSON-SEQ QLOG variant. This has the
The output format will always be the JSON-SEQ qlog variant. This has the
advantage that each event simply involves concatenating another record to an
output log file and does not require nesting of syntactic constructs between
events.
@ -47,7 +47,7 @@ Basic usage is in the form of
This (category name, event name) tuple is known as the event type.
- zero or more macros which log fields inside a QLOG event.
- zero or more macros which log fields inside a qlog event.
- a `QLOG_EVENT_END` macro.
@ -61,11 +61,11 @@ API details can be found in `internal/qlog.h`.
Configuration
-------------
QLOG must currently be enabled at build time using `enable-unstable-qlog`. If
qlog must currently be enabled at build time using `enable-unstable-qlog`. If
not enabled, `OPENSSL_NO_QLOG` is defined.
When built with QLOG support, QLOG can be turned on using the recommended
environment variable `QLOGDIR`. A filter can be defined using `QLOGFILTER`. When
When built with qlog support, qlog can be turned on using the recommended
environment variable `QLOGDIR`. A filter can be defined using `OSSL_QFILTER`. When
enabled, each connection causes a file `{ODCID}_{ROLE}.sqlog` to be created in
the specified directory, where `{ODCID}` is the original initial DCID used for
the connection and `{ROLE}` is `client` or `server`.
@ -131,3 +131,8 @@ Some examples of more normal filters include:
- `quic:version_information quic:packet_sent`: enable some events explicitly
- `* -quic:version_information`: enable all events except certain events
See also
--------
See the manpage openssl-qlog(7) for additional usage guidance.

4
doc/man7/openssl-env.pod
View File

@ -89,11 +89,11 @@ See L<OSSL_HTTP_parse_url(3)>.
=item B<QLOGDIR>
Specifies a QUIC QLOG output directory. See L<openssl-qlog(7)>.
Specifies a QUIC qlog output directory. See L<openssl-qlog(7)>.
=item B<OSSL_QFILTER>
Used to set a QUIC QLOG filter specification. See L<openssl-qlog(7)>.
Used to set a QUIC qlog filter specification. See L<openssl-qlog(7)>.
=back

2
include/internal/json_enc.h
View File

@ -16,7 +16,7 @@
* JSON Encoder
* ============
*
* This JSON encoder is used for QLOG. It supports ordinary JSON (RFC 7159),
* This JSON encoder is used for qlog. It supports ordinary JSON (RFC 7159),
* JSON-SEQ (RFC 7464) and I-JSON (RFC 7493). It supports only basic ASCII.
*/

4
include/internal/quic_channel.h
View File

@ -120,10 +120,10 @@ typedef struct quic_channel_args_st {
int is_server;
SSL *tls;
/* Whether to use QLOG. */
/* Whether to use qlog. */
int use_qlog;
/* Title to use for the QLOG session, or NULL. */
/* Title to use for the qlog session, or NULL. */
const char *qlog_title;
} QUIC_CHANNEL_ARGS;

2
include/internal/quic_ssl.h
View File

@ -130,7 +130,7 @@ int ossl_quic_has_pending(const SSL *s);
int ossl_quic_get_shutdown(const SSL *s);
/*
* Set QLOG diagnostic title. String is copied internally on success and need
* Set qlog diagnostic title. String is copied internally on success and need
* not remain allocated. Only has any effect if logging has not already begun.
* For use by tests only. Setting this on a context affects any QCSO created
* after this is called but does not affect QCSOs already created from a

4
ssl/quic/quic_channel_local.h
View File

@ -428,7 +428,7 @@ struct quic_channel_st {
/* Are we on the QUIC_PORT linked list of channels? */
unsigned int on_port_list : 1;
/* Has QLOG been requested? */
/* Has qlog been requested? */
unsigned int use_qlog : 1;
/* Saved error stack in case permanent error was encountered */
@ -438,7 +438,7 @@ struct quic_channel_st {
OSSL_QUIC_ACK_RANGE *ack_range_scratch;
size_t num_ack_range_scratch;
/* Title for QLOG purposes. We own this copy. */
/* Title for qlog purposes. We own this copy. */
char *qlog_title;
};

2
ssl/ssl_local.h
View File

@ -1191,7 +1191,7 @@ struct ssl_ctx_st {
size_t server_cert_type_len;
# ifndef OPENSSL_NO_QLOG
char *qlog_title; /* Session title for QLOG */
char *qlog_title; /* Session title for qlog */
# endif
};

2
test/quic_multistream_test.c
View File

@ -777,7 +777,7 @@ static int helper_init(struct helper *h, const char *script_name,
if (!TEST_ptr(h->c_ctx = SSL_CTX_new(OSSL_QUIC_client_method())))
goto err;
/* Set title for QLOG purposes. */
/* Set title for qlog purposes. */
snprintf(title, sizeof(title), "quic_multistream_test: %s", script_name);
if (!TEST_true(ossl_quic_set_diag_title(h->c_ctx, title)))
goto err;