Table of contents

...

QUIC Connection/Stream - ATS Client Session/Transaction mapping (Obsolete: Not too inaccurate, but not worth referencing)

I/O between HttpSM and QUICNetVC (Jan/24/2023: Updated, but QUICFrames are handled by Quiche now)

Image Added

Packetization (Jan/24/2023: Updated, we just don't do QUIC packetization by ourselves)

Image Added

ToDo

https://github.com/apache/trafficserver/projects/8

Please label issues and pull-requests with "QUIC".

Branching Rules

Branches

Please use 10-Dev or master. Feature branch was merged and removed.

• quic-latest : latest branch
• master: draft-23 29 (currently)

Development Rules

Pull-Requests

Please send Pull-Requests to "quic-latest" branch until it merged into master branch

TDD

Use Catch as Unit Test Framework. The header file is under tests/include.

How to build

(Last update: Jan/24/2023)

You have two ways to enable QUIC on ATS:

• Use Quiche library
  • This uses Quiche's QUIC implementation
• Use an SSL library that supports QUIC (i.e. BoringSSL, or OpenSSL from quictls)
  • This uses ATS's QUIC implementation

We keep ATS's native QUIC implementation for future improvement in case we need more flexibility, but our focus is currently on using Quiche.

Build Quiche (if you want to use Quiche's QUIC implementation)

Currently ATS is compatible with Quiche 0.16.0.

Please refer to the official documents for the build step. You need to enable ffi feature at minimum. qlog is also available.

https://github.com/cloudflare/quiche

Build an SSL library (if you want to use ATS's QUIC implementation)

ATS now supports 4 variation of SSL libraries. Pick one from below and build it. 

BoringSSL

Official BoringSSL works without patches.

https://boringssl.googlesource.com/boringssl

This commit These commits below workswork, and recent commits would probably work tooas well.

cbae965ca03825d517efe98cf7b8812584cab4a0

OpenSSL (akamai/master-quic-support)

...

(BoringSSL API version 9)

88024df12147e56b6abd66b743ff441a0aaa09a8 (BoringSSL API version 10)

Please note that the support for BoringSSL API version 9 may be removed without notice in the future.

OpenSSL (quictls/openssl) [RECOMMENDED]

https://github.com/akamaiquictls/openssl/tree/master-quic-supportOpenSSL_1_1_1j+quic

They also have branches based on OpenSSL 3.0 but we haven't fully supported it.

$ git clone --depth 1 --branch master-quic-supportOpenSSL_1_1_1j+quic https://github.com/akamaiquictls/openssl
$ cd openssl
$ ./config --prefix=/PATH/TO/THE/OPENSSL
$ make
$ make install

OpenSSL (tatsuhiro-t/OpenSSL_1_1_

...

1g-quic-draft-

...

32) [

...

OBSOLETE]

This is ngtcp2 developer's customized version.

https://github.com/tatsuhiro-t/openssl/tree/OpenSSL_1_1_1d1g-quic-draft-2532

OpenSSL (

...

akamai/master-

...

quic-

...

support) [

...

INCOMPATIBLE]

This is ngtcp2 developer's customized version too but with different APIsused to work, but it's incompatible now because it's based on OpenSSL master branch.

This is the branch used for https://github.com/openssl/openssl/pull/8797 .

https://github.com/tatsuhiro-takamai/openssl/tree/openssl-quic-draft-22

Build ATS (quic-latest branch)

master-quic-support

Build ATS (10-Dev branch)

Quiche support is only available on quiche branch at the moment.

$ git clone --depth 1 --branch 10-Dev https://github.com/apache/trafficserver
$ cd trafficserver
$ autoreconf -if
$ ./configure --prefix=/PATH/TO/ATS --with-quiche=/PATH/TO/QUICHE --enable-debug
$ make
$ make install

Build ATS (master branch)

The master branch only supports ATS's native implementation at the moment. There is no additional requirement except that you need the SSL library you just built The requirements are the same as master branch : Installing From Source Code

$ git clone --depth 1 --branch quic-latest https://github.com/apache/trafficserver
$ cd trafficserver
$ autoreconf -if
$ ./configure --prefix=/PATH/TO/ATS --with-openssl=/PATH/TO/SSL_LIBRARY --enable-debug
$ make
$ make install

...

Configuration files are located in the /PATH/TO/THE/ATS/etc/trafficserver/.

The detail is documented here, but below is the essential settings and only these 4 settings are available if you use Quiche.

• records.config

# run 1 UDP thread at least
CONFIG proxy.config.udp.threads INT 1
 
# open server port for quic
CONFIG proxy.config.http.server_ports STRING 4433:quic
  
# enable debug log if you want
CONFIG proxy.config.diags.debug.enabled INT 1
CONFIG proxy.config.diags.debug.tags STRING quic

...

CONFIG proxy.config.quic.no_activity_timeout_in INT 30

   Specifies how long Traffic Server keeps QUIC connections to clients open if a transaction stalls.

How to test

Third-party tools

There is a script that builds third-party tools in the repo. It builds h2load and curl with HTTP/3 support. An HTTP/3 client under ngtcp2/example is also useful when you want to check details.

https://github.com/apache/trafficserver/blob/10-Dev/tools/build_h3_tools.sh

traffic_quic

The quic-latest branch has We have client implementation called "traffic_quic" for test. Not actively maintained, and compatibility with Quiche implementation is not confirmed.

// draft-17

$ traffic_quic -h
Usage: traffic_quic [--SWITCH [ARG]]
  switch__________________type__default___description
  -a, --addr              str   127.0.0.1 Address
  -o, --output            str             Write to FILE instead of stdout
  -p, --port              str   4433      Port
  -P, --path              str   /         Path
  -T, --debug             str   quic|vv.. Vertical-bar-separated Debug Tags
  -c, --close             on    false     Enable connection close excercise
  -h, --help                              Print usage information
  -V, --version                           Print version string
      --run-root                          using TS_RUNROOT as sandbox

...