Repository files navigation

Neqo is the QUIC implementation used by Mozilla in Firefox and other products.It is written in Rust and provides a library for QUIC transport, HTTP/3, andQPACK. The TLS security backend is the Mozilla NSS library, which is also usedby Firefox.

Neqo is designed to be used in Firefox, but it can also be usedstandalone. We include command line tools for testing and debugging, such asneqo-client andneqo-server, which can be used to test HTTP/3 serversand clients.

Note: The neqo server functionality is experimental, sinceit is not in production use at Mozilla, and it is not as mature as theclient functionality. It is intended to be standards-compliant wheninteroperating with a compliant client, but it may not implement alloptional protocol features, and it may not handle all edge cases.It is also not optimized for performance or resource usage, andwhile it implements many of the necessary features for a server,it does not include configuration of a number of options thatis suited to a live deployment.Do not use the neqo server code in production.

To build Neqo:

cargo build

This will use a system-installedNSS library if it is new enough. (See "Build with Separate NSS/NSPR" below if NSS is not installed or it is deemed too old.)

To run test HTTP/3 programs (neqo-client andneqo-server):

./target/debug/neqo-server'[::]:12345'./target/debug/neqo-client'https://[::]:12345/'

You can cloneNSS andNSPR into the same directory and export anenvironment variable calledNSS_DIR pointing to NSS. This causes the build touse the existing NSS checkout. However, in order to run anything that dependson NSS, you need to set an environment as follows:

export LD_LIBRARY_PATH="$(find. -name libssl3.so -print| head -1| xargs dirname| xargs realpath)"

export DYLD_LIBRARY_PATH="$(find. -name libssl3.dylib -print| head -1| xargs dirname| xargs realpath)"

Note: If you did not already compile NSS separately, you need to haveMercurial (hg), installed. NSS builds requireGYP andNinja to be installed.

Enable generation ofQLOG logs with:

target/debug/neqo-server'[::]:12345' --qlog-dir.target/debug/neqo-client'https://[::]:12345/' --qlog-dir.

You can of course specify a different directory for the QLOG files.You can upload QLOG files toqvis to visualize the flows.

To export QLOG files forNeqo Simulator runs, set theenvironment variableQLOGDIR. For example:

QLOGDIR=/tmp/qlog cargo bench --bench min_bandwidth --features bench

You can export TLS keys by setting theSSLKEYLOGFILE environment variableto a filename to instruct NSS to dump keys in thestandard formatto enable decryption byWireshark and other tools.

As documented in theenv_logger documentation,theRUST_LOG environment variable can be used to selectively enable log messagesfrom Rust code. This works for Neqo's command line tools, as well as for when Neqo isincorporated into Gecko, althoughGecko needs to be built in debug mode.

Some examples:

1. RUST_LOG=neqo_transport::dump ./mach run

   lists sent and received QUIC packets and their frames' contents only.

2. RUST_LOG=neqo_transport=debug,neqo_http3=trace,info ./mach run

   sets adebug log level fortransport,trace level forhttp3, andinfo loglevel for all other Rust crates, both Neqo and others used by Gecko.

3. RUST_LOG=neqo=trace,error ./mach run

   setstrace level for all modules starting withneqo, and setserror as minimum log level for other unrelated Rust log messages.

In a checked-out copy of Gecko source, set[patches.*] values for the fourNeqo crates to local versions in the rootCargo.toml. For example, if Neqowas checked out to/home/alice/git/neqo, add the following lines to the rootCargo.toml.

[patch."https://github.com/mozilla/neqo"]neqo-bin = {path ="/home/alice/git/neqo/neqo-bin" }neqo-common = {path ="/home/alice/git/neqo/neqo-common" }neqo-crypto = {path ="/home/alice/git/neqo/neqo-crypto" }neqo-http3 = {path ="/home/alice/git/neqo/neqo-http3" }neqo-qpack = {path ="/home/alice/git/neqo/neqo-qpack" }neqo-transport = {path ="/home/alice/git/neqo/neqo-transport" }neqo-udp = {path ="/home/alice/git/neqo/neqo-udp" }

Then run the following:

./mach vendor rust

Compile Gecko as usual with

./mach build

Note: Using newer Neqo code with Gecko may also require changes (likely toneqo_glue) ifsomething has changed.

1. Runneqo-server viacargo run --bin neqo-server -- 'localhost:12345' --db ./test-fixture/db.
2. On Firefox, setabout:config preferences:
   • network.http.http3.alt-svc-mapping-for-testing tolocalhost;h3=":12345"
   • network.http.http3.disable_when_third_party_roots_found tofalse
3. Optionally enable logging viaabout:logging or profiling viahttps://profiler.firefox.com/.
4. Navigate tohttps://localhost:12345 and accept self-signed certificate.