Skip to content

Commit

Permalink
Updates to README
Browse files Browse the repository at this point in the history
  • Loading branch information
@larseggert
larseggert committed Mar 26, 2024
1 parent a00bcb5 commit 0c64e26
Showing 1 changed file with 73 additions and 41 deletions.
114 changes: 73 additions & 41 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,82 +1,102 @@
# Neqo, an Implementation of QUIC written in Rust
# Neqo, an Implementation of QUIC in Rust

![neqo logo](https://github.com/mozilla/neqo/raw/main/neqo.png "neqo logo")

To run test HTTP/3 programs (neqo-client and neqo-server):
To build Neqo:

* `cargo build`
* `./target/debug/neqo-server '[::]:12345' --db ./test-fixture/db`
* `./target/debug/neqo-client http://127.0.0.1:12345/`

If a "Failure to load dynamic library" error happens at runtime, do
```shell
export LD_LIBRARY_PATH="$(dirname "$(find . -name libssl3.so -print | head -1)")"
cargo build
```

On a macOS, do
This will use a system-installed [NSS][NSS] 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` and `neqo-server`):

```shell
export DYLD_LIBRARY_PATH="$(dirname "$(find . -name libssl3.dylib -print | head -1)")"
./target/debug/neqo-server '[::]:12345'
./target/debug/neqo-client 'https://[::]:12345/'
```

## Faster Builds with Separate NSS/NSPR
## Build with separate NSS/NSPR

You can clone NSS (https://hg.mozilla.org/projects/nss) and NSPR
(https://hg.mozilla.org/projects/nspr) into the same directory and export an
You can clone [NSS][NSS] and [NSPR][NSPR] into the same directory and export an
environment variable called `NSS_DIR` pointing to NSS. This causes the build to
use the existing NSS checkout. However, in order to run anything that depends
on NSS, you need to set `$\[DY]LD\_LIBRARY\_PATH` to point to
`$NSS_DIR/../dist/Debug/lib`.
on NSS, you need to set an environment as follows:

### Linux

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

### macOS

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

Note: If you did not compile NSS separately, you need to have mercurial (hg), installed.
NSS builds require gyp, and ninja (or ninja-build) to be present also.
Note: If you did not already compile NSS separately, you need to have
[Mercurial (hg)][HG], installed. NSS builds require [GYP][GYP] and
[Ninja][NINJA] to be installed.

## Debugging Neqo

### QUIC Logging
### QUIC logging

Enable [QLOG](https://datatracker.ietf.org/doc/draft-ietf-quic-qlog-main-schema/) with:
Enable generation of [QLOG][QLOG] logs with:

```
$ mkdir "$logdir"
$ ./target/debug/neqo-server '[::]:12345' --db ./test-fixture/db --qlog-dir "$logdir"
$ ./target/debug/neqo-client 'https://[::]:12345/' --qlog-dir "$logdir"
```shell
target/debug/neqo-server '[::]:12345' --qlog-dir .
target/debug/neqo-client 'https://[::]:12345/' --qlog-dir .
```

You may use https://qvis.quictools.info/ by uploading the QLOG files and visualize the flows.
You can of course specify a different directory for the QLOG files.
You can upload QLOG files to [qvis][QVIS] to visualize the flows.

### Using SSLKEYLOGFILE to decrypt Wireshark logs
### Using `SSLKEYLOGFILE` to decrypt Wireshark logs

[Info here](https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS/Key_Log_Format)

TODO: What is the minimum Wireshark version needed?
TODO: Above link may be incorrect, protocol now called TLS instead of SSL?
You can export TLS keys by setting the `SSLKEYLOGFILE` environment variable
to a filename to instruct NSS to dump keys in the
[standard format](https://datatracker.ietf.org/doc/draft-ietf-tls-keylogfile/)
to enable decryption by [Wireshark](https://wiki.wireshark.org/TLS) and other tools.

### Using RUST_LOG effectively

As documented in the [env_logger documentation](https://docs.rs/env_logger/),
the `RUST_LOG` environment variable can be used to selectively enable log messages
from Rust code. This works for Neqo's cmdline tools, as well as for when Neqo is
from Rust code. This works for Neqo's command line tools, as well as for when Neqo is
incorporated into Gecko, although [Gecko needs to be built in debug mode](https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide/Build_Instructions/Configuring_Build_Options).

Some examples:
1. `RUST_LOG=neqo_transport::dump ./mach run` lists sent and received QUIC
packets and their frames' contents only.
1. `RUST_LOG=neqo_transport=debug,neqo_http3=trace,info ./mach run` sets a
'debug' log level for transport, 'trace' level for http3, and 'info' log

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

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

1. ```shell
RUST_LOG=neqo_transport=debug,neqo_http3=trace,info ./mach run
```

sets a `debug` log level for `transport`, `trace` level for `http3`, and `info` log
level for all other Rust crates, both Neqo and others used by Gecko.
1. `RUST_LOG=neqo=trace,error ./mach run` sets `trace` level for all modules
starting with "neqo", and sets `error` as minimum log level for other
unrelated Rust log messages.

1. ```shell
RUST_LOG=neqo=trace,error ./mach run
```

sets `trace` level for all modules starting with `neqo`, and sets `error` as minimum log level for other unrelated Rust log messages.

### Trying In-development Neqo code in Gecko
### Trying in-development Neqo code in Gecko

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

```
```toml
[patch."https://github.com/mozilla/neqo"]
neqo-http3 = { path = "/home/alice/git/neqo/neqo-http3" }
neqo-transport = { path = "/home/alice/git/neqo/neqo-transport" }
Expand All @@ -87,11 +107,23 @@ neqo-crypto = { path = "/home/alice/git/neqo/neqo-crypto" }

Then run the following:

```
```shell
./mach vendor rust
```

Compile Gecko as usual with `./mach build`.
Compile Gecko as usual with

```shell
./mach build
```

Note: Using newer Neqo code with Gecko may also require changes (likely to `neqo_glue`) if
something has changed.

[NSS]: https://hg.mozilla.org/projects/nss
[NSPR]: https://hg.mozilla.org/projects/nspr
[GYP]: https://github.com/nodejs/gyp-next
[HG]: https://www.mercurial-scm.org/
[NINJA]: https://ninja-build.org/
[QLOG]: https://datatracker.ietf.org/doc/draft-ietf-quic-qlog-main-schema/
[QVIS]: https://qvis.quictools.info/

0 comments on commit 0c64e26

Please sign in to comment.