*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
============================== 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
### 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.
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.
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
- 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
----------
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
--------
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
---------------
-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
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.
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.
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`.
- `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.
=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
* 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.
*/
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;
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
/* 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 */
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;
};
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
};
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;
projects / openssl.git / commitdiff