From: Hugo Landau Date: Tue, 23 Jan 2024 14:13:49 +0000 (+0000) Subject: QLOG: Editorial fixes (QLOG is spelled 'qlog') X-Git-Tag: openssl-3.3.0-alpha1~197 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=de60b122b2f1082d5346f3f51fb7641c47391d71;p=thirdparty%2Fopenssl.git QLOG: Editorial fixes (QLOG is spelled 'qlog') Reviewed-by: Matt Caswell Reviewed-by: Neil Horman (Merged from https://github.com/openssl/openssl/pull/22037) --- diff --git a/CHANGES.md b/CHANGES.md index 13c859c9f3b..b61a00aaf81 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -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 diff --git a/Configure b/Configure index 1b4428a5601..934b0d09c07 100755 --- a/Configure +++ b/Configure @@ -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 diff --git a/INSTALL.md b/INSTALL.md index 52add7c15b9..ec65f6ba79a 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -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. diff --git a/doc/designs/quic-design/debugging.md b/doc/designs/quic-design/debugging.md index c44ddf2f899..7cb412eac8b 100644 --- a/doc/designs/quic-design/debugging.md +++ b/doc/designs/quic-design/debugging.md @@ -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 ---------- diff --git a/doc/designs/quic-design/json-encoder.md b/doc/designs/quic-design/json-encoder.md index 9ca568feabe..6e4c6e3126d 100644 --- a/doc/designs/quic-design/json-encoder.md +++ b/doc/designs/quic-design/json-encoder.md @@ -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 --------------- diff --git a/doc/designs/quic-design/qlog.md b/doc/designs/quic-design/qlog.md index 33d21913212..77e05843b42 100644 --- a/doc/designs/quic-design/qlog.md +++ b/doc/designs/quic-design/qlog.md @@ -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. diff --git a/doc/man7/openssl-env.pod b/doc/man7/openssl-env.pod index 0d1b05a1e32..53f15698978 100644 --- a/doc/man7/openssl-env.pod +++ b/doc/man7/openssl-env.pod @@ -89,11 +89,11 @@ See L. =item B -Specifies a QUIC QLOG output directory. See L. +Specifies a QUIC qlog output directory. See L. =item B -Used to set a QUIC QLOG filter specification. See L. +Used to set a QUIC qlog filter specification. See L. =back diff --git a/include/internal/json_enc.h b/include/internal/json_enc.h index 96ea920641b..3b4672aee19 100644 --- a/include/internal/json_enc.h +++ b/include/internal/json_enc.h @@ -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. */ diff --git a/include/internal/quic_channel.h b/include/internal/quic_channel.h index aafdeca3d2a..2f3d91d5c76 100644 --- a/include/internal/quic_channel.h +++ b/include/internal/quic_channel.h @@ -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; diff --git a/include/internal/quic_ssl.h b/include/internal/quic_ssl.h index 7a53af7f650..47e856cd79f 100644 --- a/include/internal/quic_ssl.h +++ b/include/internal/quic_ssl.h @@ -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 diff --git a/ssl/quic/quic_channel_local.h b/ssl/quic/quic_channel_local.h index 564b789f9c2..c4ecbc64093 100644 --- a/ssl/quic/quic_channel_local.h +++ b/ssl/quic/quic_channel_local.h @@ -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; }; diff --git a/ssl/ssl_local.h b/ssl/ssl_local.h index 1db5df46dfa..cae0c1202b2 100644 --- a/ssl/ssl_local.h +++ b/ssl/ssl_local.h @@ -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 }; diff --git a/test/quic_multistream_test.c b/test/quic_multistream_test.c index 88edfffc863..01b039b7ad7 100644 --- a/test/quic_multistream_test.c +++ b/test/quic_multistream_test.c @@ -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;