1QUIC: Debugging and Tracing 2=========================== 3 4When debugging the QUIC stack it is extremely useful to have protocol traces 5available. There are two approaches you can use to obtain this data: 6 7- qlog 8- Packet capture 9 10Neither of these approaches is strictly superior to the other and both have pros 11and cons: 12 13- In general, qlog is aimed at storing only information relevant to the 14 QUIC protocol itself without storing bulk data. This includes both transmitted 15 and received packets but also information about the internal state of a QUIC 16 implementation which is not directly observable from the network. 17 18- By comparison, packet capture stores all packets in their entirety. 19 Packet captures are thus larger, but they also provide more complete 20 information in general and do not have information removed. On the other hand, 21 because they work from a network viewpoint, they cannot provide direct 22 information on the internal state of a QUIC implementation. For example, 23 packet capture cannot directly tell you when an implementation deems a packet 24 lost. 25 26Both of these approaches have good GUI visualisation tools available for viewing 27the logged data. 28 29To summarise: 30 31- qlog: 32 - Pro: Smaller files 33 - Con: May leave out data assumed to be irrelevant 34 - Pro: Information on internal states and decisions made by a QUIC 35 implementation 36 - Pro: No need to obtain a keylog 37- PCAP: 38 - Pro: Complete capture 39 - Con: No direct information on internal states of a QUIC implementation 40 - Con: Need to obtain a keylog 41 42Using qlog 43---------- 44 45To enable qlog you must: 46 47- build using the `enable-unstable-qlog` build-time configuration option; 48 49- set the environment variable `QLOGDIR` to a directory where qlog log files 50 are to be written; 51 52- set the environment variable `OSSL_QFILTER` to a filter specifying the events 53 you want to be written (set `OSSL_QFILTER='*'` for all events). 54 55Any process using the libssl QUIC implementation will then automatically write 56qlog files in the JSON-SEQ format to the specified directory. The files have the 57naming convention recommended by the specification: `{ODCID}_{ROLE}.sqlog`, 58where `{ODCID}` is the initial (original) DCID of a connection and `{ROLE}` is 59`client` or `server`. 60 61The log files can be loaded into [qvis](https://qvis.quictools.info/). The [qvis 62website](https://qvis.quictools.info/) also has some sample qlog files which you 63can load at the click of a button, which enables you to see what kind of 64information qvis can offer you. 65 66Note that since the qlog specification is not finalised and still evolving, 67the format of the output may change, as may the method of configuring this 68logging support. 69 70Currently this implementation tracks qvis's qlog support, as that is the 71main target use case at this time. 72 73Note that since qlog emphasises logging only data which is relevant to a QUIC 74protocol implementation, for the purposes of reducing the volume of logging 75data, application data is generally not logged. (However, this is not a 76guarantee and must not be relied upon from a privacy perspective.) 77 78[See here for more details on the design of the qlog facility.](qlog.md) 79 80Using PCAP 81---------- 82 83To use PCAP you can use any standard packet capture tool, such as Wireshark or 84tcpdump (e.g. `tcpdump -U -i "$IFACE" -w "$FILE" 'udp port 1234'`). 85 86**Using Wireshark.** Once you have obtained a packet capture as a standard 87`pcap` or `pcapng` file, you can load it into Wireshark, which has excellent 88QUIC protocol decoding support. 89 90**Activating the decoder.** If you are using QUIC on a port not known to be 91commonly used for QUIC, you may need to tell Wireshark to try and decode a flow 92as QUIC. To do this, right click on the Protocol column and select “Decode 93As...”. Click on “(none)” under the Current column and select QUIC. 94 95**Keylogs.** Since QUIC is an encrypted protocol, Wireshark cannot provide much 96information without access to the encryption keys used for the connection 97(though it is able to decrypt Initial packets). 98 99In order to provide this information you need to provide Wireshark with a keylog 100file. This is a log file containing encryption keys for the connection which is 101written directly by a QUIC implementation for debugging purposes. The purpose of 102such a file is to enable a TLS or QUIC session to be decrypted for development 103purposes in a lab environment. It should go without saying that the export of a 104keylog file should never be used in a production environment. 105 106For the OpenSSL QUIC implementation, OpenSSL must be instructed to save a keylog 107file using the SSL_CTX_set_keylog_callback(3) API call. If the application you 108are using does not provide a way to enable this functionality, this requires 109recompiling the application you are using as OpenSSL does not provide a way 110to enable this functionality directly. 111 112If you are using OpenSSL QUIC to talk to another QUIC implementation, you also 113may be able to obtain a keylog from that other implementation. (It does not 114matter from which side of the connection you obtain the keylog.) 115 116Once you have a keylog file you can configure Wireshark to use it. 117There are two ways to do this: 118 119- **Manual configuration.** Select Edit → 120 Preferences and navigate to Protocols → TLS. Enter the path to the keylog file 121 under “(Pre)-Master-Secret log filename". You can have key information being 122 appended to this log continuously if desired. Press OK and Wireshark should 123 now be able to decrypt any TLS or QUIC session described by the log file. 124 125- **Embedding.** Alternatively, you can embed a keylog file into a `.pcapng` 126 file directly, so that Wireshark can decrypt the packets automatically when 127 the packet capture file is opened. This avoids the need to have a centralised 128 key log file and ensures that the key log for a specific packet capture is 129 kept together with the captured packets. It is also highly useful if you want 130 to distribute a packet capture file publicly, for example for educational 131 purposes. 132 133 To embed a keylog, you can use the `editcap` command provided by Wireshark 134 after taking a packet capture (note that `tls` should be specified below 135 regardless of whether TLS or QUIC is being used): 136 137 ```bash 138 $ editcap --inject-secrets tls,$PATH_TO_KEYLOG_FILE \ 139 "$INPUT_FILENAME" "$OUTPUT_FILENAME" 140 ``` 141 142 This tool accepts `.pcap` or `.pcapng` input and will generate a `.pcapng` 143 output file. 144