2019-09-11 15:27:58 +00:00
|
|
|
[![Build Status](https://travis-ci.org/litespeedtech/lsquic.svg?branch=master)](https://travis-ci.org/litespeedtech/lsquic)
|
|
|
|
[![Build Status](https://api.cirrus-ci.com/github/litespeedtech/lsquic.svg)](https://cirrus-ci.com/github/litespeedtech/lsquic)
|
|
|
|
[![Build status](https://ci.appveyor.com/api/projects/status/kei9649t9leoqicr?svg=true)](https://ci.appveyor.com/project/litespeedtech/lsquic)
|
2018-04-23 18:49:50 +00:00
|
|
|
|
2019-09-11 15:27:58 +00:00
|
|
|
LiteSpeed QUIC (LSQUIC) Library README
|
2017-09-22 21:00:03 +00:00
|
|
|
=============================================
|
|
|
|
|
|
|
|
Description
|
|
|
|
-----------
|
|
|
|
|
2019-09-11 15:27:58 +00:00
|
|
|
LiteSpeed QUIC (LSQUIC) Library is an open-source implementation of QUIC
|
2019-09-18 15:39:34 +00:00
|
|
|
and HTTP/3 functionality for servers and clients. Most of the code in this
|
|
|
|
distribution is used in our own products: LiteSpeed Web Server, LiteSpeed ADC,
|
|
|
|
and OpenLiteSpeed. We think it is free of major problems. Nevertheless, do
|
|
|
|
not hesitate to report bugs back to us. Even better, send us fixes and
|
|
|
|
improvements!
|
2017-09-22 21:00:03 +00:00
|
|
|
|
2020-02-24 17:02:57 +00:00
|
|
|
Currently supported QUIC versions are Q043, Q046, Q050, ID-25, and ID-27.
|
2019-11-11 19:05:54 +00:00
|
|
|
Support for newer versions will be added soon after they are released.
|
2017-09-22 21:00:03 +00:00
|
|
|
|
|
|
|
Documentation
|
|
|
|
-------------
|
|
|
|
|
2020-03-12 12:41:53 +00:00
|
|
|
Documentation is available at https://lsquic.readthedocs.io/en/latest/.
|
|
|
|
|
|
|
|
In addition, see example programs for API usage and EXAMPLES.txt for
|
|
|
|
some compilation and run-time options.
|
2017-09-22 21:00:03 +00:00
|
|
|
|
2017-09-26 15:26:05 +00:00
|
|
|
Requirements
|
|
|
|
------------
|
2017-09-22 21:00:03 +00:00
|
|
|
|
2017-09-26 15:26:05 +00:00
|
|
|
To build LSQUIC, you need CMake, zlib, and BoringSSL. The example program
|
|
|
|
uses libevent to provide the event loop.
|
2017-09-22 21:00:03 +00:00
|
|
|
|
2017-09-26 15:26:05 +00:00
|
|
|
Building BoringSSL
|
|
|
|
------------------
|
|
|
|
|
|
|
|
BoringSSL is not packaged; you have to build it yourself. The process is
|
|
|
|
straightforward. You will need `go` installed.
|
|
|
|
|
|
|
|
1. Clone BoringSSL by issuing the following command:
|
|
|
|
|
|
|
|
```
|
|
|
|
git clone https://boringssl.googlesource.com/boringssl
|
|
|
|
cd boringssl
|
|
|
|
```
|
|
|
|
|
2019-09-11 15:27:58 +00:00
|
|
|
You may need to install pre-requisites like zlib and libevent.
|
2017-09-26 15:26:05 +00:00
|
|
|
|
2019-09-16 13:09:08 +00:00
|
|
|
2. Use specific BoringSSL version
|
|
|
|
|
|
|
|
```
|
2020-04-01 18:41:35 +00:00
|
|
|
git checkout bfe527fa35735e8e045cbfb42b012e13ca68f9cf
|
2019-09-16 13:09:08 +00:00
|
|
|
```
|
|
|
|
|
2019-10-08 19:54:01 +00:00
|
|
|
3. Compile the library
|
2017-09-26 15:26:05 +00:00
|
|
|
|
|
|
|
```
|
|
|
|
cmake . && make
|
|
|
|
```
|
|
|
|
|
2019-02-01 07:24:29 +00:00
|
|
|
Remember where BoringSSL sources are:
|
2017-09-26 15:26:05 +00:00
|
|
|
```
|
2019-02-01 07:24:29 +00:00
|
|
|
BORINGSSL=$PWD
|
2017-09-26 15:26:05 +00:00
|
|
|
```
|
|
|
|
|
2019-02-01 07:24:29 +00:00
|
|
|
If you want to turn on optimizations, do
|
2017-09-26 15:26:05 +00:00
|
|
|
|
|
|
|
```
|
2019-02-01 07:24:29 +00:00
|
|
|
cmake -DCMAKE_BUILD_TYPE=Release . && make
|
2017-09-26 15:26:05 +00:00
|
|
|
```
|
|
|
|
|
2019-09-11 15:27:58 +00:00
|
|
|
Building LSQUIC Library
|
|
|
|
-----------------------
|
2017-09-26 15:26:05 +00:00
|
|
|
|
2019-09-11 15:27:58 +00:00
|
|
|
LSQUIC's `http_client`, `http_server`, and the tests link BoringSSL
|
|
|
|
libraries statically. Following previous section, you can build LSQUIC
|
|
|
|
as follows:
|
2017-09-26 15:26:05 +00:00
|
|
|
|
2017-09-29 15:18:32 +00:00
|
|
|
1. Get the source code
|
|
|
|
|
|
|
|
```
|
2019-09-11 15:27:58 +00:00
|
|
|
git clone https://github.com/litespeedtech/lsquic.git
|
|
|
|
cd lsquic
|
|
|
|
git submodule init
|
|
|
|
git submodule update
|
2017-09-29 15:18:32 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
2. Compile the library
|
|
|
|
|
|
|
|
|
2017-09-26 15:26:05 +00:00
|
|
|
```
|
2019-02-01 07:24:29 +00:00
|
|
|
# $BORINGSSL is the top-level BoringSSL directory from the previous step
|
|
|
|
cmake -DBORINGSSL_DIR=$BORINGSSL .
|
2017-09-26 15:26:05 +00:00
|
|
|
make
|
|
|
|
```
|
|
|
|
|
2017-09-29 15:18:32 +00:00
|
|
|
3. Run tests
|
2017-09-26 15:26:05 +00:00
|
|
|
|
|
|
|
```
|
|
|
|
make test
|
|
|
|
```
|
|
|
|
|
2017-10-03 19:37:20 +00:00
|
|
|
Building with Docker
|
|
|
|
---------
|
2019-09-16 14:17:30 +00:00
|
|
|
The library and the example client and server can be built with Docker.
|
|
|
|
|
|
|
|
Initialize Git submodules:
|
|
|
|
```
|
|
|
|
cd lsquic
|
|
|
|
git submodule init
|
|
|
|
git submodule update
|
|
|
|
```
|
|
|
|
|
|
|
|
Build the Docker image:
|
2017-10-03 19:37:20 +00:00
|
|
|
```
|
2019-09-11 15:27:58 +00:00
|
|
|
docker build -t lsquic .
|
2017-10-03 19:37:20 +00:00
|
|
|
```
|
|
|
|
|
2019-09-16 14:17:30 +00:00
|
|
|
Then you can use the examples from the command line. For example:
|
2017-10-03 19:37:20 +00:00
|
|
|
```
|
2019-09-16 14:17:30 +00:00
|
|
|
sudo docker run -it --rm lsquic http_client -s www.google.com -p / -o version=Q046
|
|
|
|
sudo docker run -p 12345:12345/udp -v /path/to/certs:/mnt/certs -it --rm lsquic http_server -c www.example.com,/mnt/certs/chain,/mnt/certs/key
|
2017-10-03 19:37:20 +00:00
|
|
|
```
|
|
|
|
|
2017-09-26 15:26:05 +00:00
|
|
|
Platforms
|
|
|
|
---------
|
|
|
|
|
2019-09-11 15:27:58 +00:00
|
|
|
The library has been tested on the following platforms:
|
2017-09-26 15:26:05 +00:00
|
|
|
- Linux
|
2018-05-04 20:24:56 +00:00
|
|
|
- i386
|
2017-09-26 15:26:05 +00:00
|
|
|
- x86_64
|
|
|
|
- ARM (Raspberry Pi 3)
|
|
|
|
- FreeBSD
|
|
|
|
- i386
|
|
|
|
- MacOS
|
|
|
|
- x86_64
|
2019-09-11 15:27:58 +00:00
|
|
|
- Windows (this needs updating for the server part, now broken)
|
|
|
|
- x86_64
|
2017-09-22 21:00:03 +00:00
|
|
|
|
|
|
|
Have fun,
|
|
|
|
|
|
|
|
LiteSpeed QUIC Team.
|
|
|
|
|
2020-03-03 01:51:40 +00:00
|
|
|
Copyright (c) 2017 - 2020 LiteSpeed Technologies Inc
|