README.md revision 758aff32
15392f7a3SLiteSpeed Tech[![Build Status](https://travis-ci.org/litespeedtech/lsquic.svg?branch=master)](https://travis-ci.org/litespeedtech/lsquic) 25392f7a3SLiteSpeed Tech[![Build Status](https://api.cirrus-ci.com/github/litespeedtech/lsquic.svg)](https://cirrus-ci.com/github/litespeedtech/lsquic) 3f50b9148SDmitri Tikhonov[![Build status](https://ci.appveyor.com/api/projects/status/ij4n3vy343pkgm1j?svg=true)](https://ci.appveyor.com/project/litespeedtech/lsquic) 41fc8f998SDmitri Tikhonov 55392f7a3SLiteSpeed TechLiteSpeed QUIC (LSQUIC) Library README 650aadb33SDmitri Tikhonov============================================= 750aadb33SDmitri Tikhonov 850aadb33SDmitri TikhonovDescription 950aadb33SDmitri Tikhonov----------- 1050aadb33SDmitri Tikhonov 115392f7a3SLiteSpeed TechLiteSpeed QUIC (LSQUIC) Library is an open-source implementation of QUIC 12f87fb49cSDmitri Tikhonovand HTTP/3 functionality for servers and clients. Most of the code in this 13f87fb49cSDmitri Tikhonovdistribution is used in our own products: LiteSpeed Web Server, LiteSpeed ADC, 14758aff32SDmitri Tikhonovand OpenLiteSpeed. 1550aadb33SDmitri Tikhonov 16b1a7c3f9SDmitri TikhonovCurrently supported QUIC versions are Q043, Q046, Q050, ID-27, ID-28, ID-29, 17758aff32SDmitri TikhonovID-30, and ID-31. Support for newer versions is added soon after they 18b62ec17fSDmitri Tikhonovare released. 1950aadb33SDmitri Tikhonov 2050aadb33SDmitri TikhonovDocumentation 2150aadb33SDmitri Tikhonov------------- 2250aadb33SDmitri Tikhonov 23a5fa05f9SDmitri TikhonovDocumentation is available at https://lsquic.readthedocs.io/en/latest/. 24a5fa05f9SDmitri Tikhonov 25a5fa05f9SDmitri TikhonovIn addition, see example programs for API usage and EXAMPLES.txt for 26a5fa05f9SDmitri Tikhonovsome compilation and run-time options. 2750aadb33SDmitri Tikhonov 28e0197994SDmitri TikhonovRequirements 29e0197994SDmitri Tikhonov------------ 3050aadb33SDmitri Tikhonov 31e0197994SDmitri TikhonovTo build LSQUIC, you need CMake, zlib, and BoringSSL. The example program 32e0197994SDmitri Tikhonovuses libevent to provide the event loop. 3350aadb33SDmitri Tikhonov 34e0197994SDmitri TikhonovBuilding BoringSSL 35e0197994SDmitri Tikhonov------------------ 36e0197994SDmitri Tikhonov 37e0197994SDmitri TikhonovBoringSSL is not packaged; you have to build it yourself. The process is 38e0197994SDmitri Tikhonovstraightforward. You will need `go` installed. 39e0197994SDmitri Tikhonov 40e0197994SDmitri Tikhonov1. Clone BoringSSL by issuing the following command: 41e0197994SDmitri Tikhonov 42e0197994SDmitri Tikhonov``` 43e0197994SDmitri Tikhonovgit clone https://boringssl.googlesource.com/boringssl 44e0197994SDmitri Tikhonovcd boringssl 45e0197994SDmitri Tikhonov``` 46e0197994SDmitri Tikhonov 475392f7a3SLiteSpeed TechYou may need to install pre-requisites like zlib and libevent. 48e0197994SDmitri Tikhonov 49c38e7df7SDmitri Tikhonov2. Use specific BoringSSL version 50c38e7df7SDmitri Tikhonov 51c38e7df7SDmitri Tikhonov``` 52e55a4502SDmitri Tikhonovgit checkout b117a3a0b7bd11fe6ebd503ec6b45d6b910b41a1 53c38e7df7SDmitri Tikhonov``` 54c38e7df7SDmitri Tikhonov 554947ba95SDmitri Tikhonov3. Compile the library 56e0197994SDmitri Tikhonov 57e0197994SDmitri Tikhonov``` 58e0197994SDmitri Tikhonovcmake . && make 59e0197994SDmitri Tikhonov``` 60e0197994SDmitri Tikhonov 61199c01abSLiteSpeed TechRemember where BoringSSL sources are: 62e0197994SDmitri Tikhonov``` 63199c01abSLiteSpeed TechBORINGSSL=$PWD 64e0197994SDmitri Tikhonov``` 65e0197994SDmitri Tikhonov 66199c01abSLiteSpeed TechIf you want to turn on optimizations, do 67e0197994SDmitri Tikhonov 68e0197994SDmitri Tikhonov``` 69199c01abSLiteSpeed Techcmake -DCMAKE_BUILD_TYPE=Release . && make 70e0197994SDmitri Tikhonov``` 71e0197994SDmitri Tikhonov 72038a9441SAaron FranceIf you want to build as a library, (necessary to build lsquic itself 73038a9441SAaron Franceas as shared library) do: 74038a9441SAaron France 75038a9441SAaron France``` 76038a9441SAaron Francecmake -DBUILD_SHARED_LIBS=1 . && make 77038a9441SAaron France``` 78038a9441SAaron France 795392f7a3SLiteSpeed TechBuilding LSQUIC Library 805392f7a3SLiteSpeed Tech----------------------- 81e0197994SDmitri Tikhonov 825392f7a3SLiteSpeed TechLSQUIC's `http_client`, `http_server`, and the tests link BoringSSL 835392f7a3SLiteSpeed Techlibraries statically. Following previous section, you can build LSQUIC 845392f7a3SLiteSpeed Techas follows: 85e0197994SDmitri Tikhonov 8667b0dc15SDmitri Tikhonov1. Get the source code 8767b0dc15SDmitri Tikhonov 8867b0dc15SDmitri Tikhonov``` 895392f7a3SLiteSpeed Techgit clone https://github.com/litespeedtech/lsquic.git 905392f7a3SLiteSpeed Techcd lsquic 915392f7a3SLiteSpeed Techgit submodule init 925392f7a3SLiteSpeed Techgit submodule update 9367b0dc15SDmitri Tikhonov``` 9467b0dc15SDmitri Tikhonov 9567b0dc15SDmitri Tikhonov2. Compile the library 9667b0dc15SDmitri Tikhonov 97038a9441SAaron FranceStatically: 98038a9441SAaron France 9967b0dc15SDmitri Tikhonov 100e0197994SDmitri Tikhonov``` 101199c01abSLiteSpeed Tech# $BORINGSSL is the top-level BoringSSL directory from the previous step 102199c01abSLiteSpeed Techcmake -DBORINGSSL_DIR=$BORINGSSL . 103e0197994SDmitri Tikhonovmake 104e0197994SDmitri Tikhonov``` 105e0197994SDmitri Tikhonov 106038a9441SAaron FranceAs a dynamic library: 107038a9441SAaron France 108038a9441SAaron France``` 1092e1429b4SDmitri Tikhonovcmake -DLSQUIC_SHARED_LIB=1 -DBORINGSSL_DIR=$BORINGSSL . 110038a9441SAaron Francemake 111038a9441SAaron France``` 112038a9441SAaron France 113038a9441SAaron France 11467b0dc15SDmitri Tikhonov3. Run tests 115e0197994SDmitri Tikhonov 116e0197994SDmitri Tikhonov``` 117e0197994SDmitri Tikhonovmake test 118e0197994SDmitri Tikhonov``` 119e0197994SDmitri Tikhonov 120306ecefeSBrian ProdoehlBuilding with Docker 121306ecefeSBrian Prodoehl--------- 12227187418SLiteSpeed TechThe library and the example client and server can be built with Docker. 12327187418SLiteSpeed Tech 12427187418SLiteSpeed TechInitialize Git submodules: 12527187418SLiteSpeed Tech``` 12627187418SLiteSpeed Techcd lsquic 12727187418SLiteSpeed Techgit submodule init 12827187418SLiteSpeed Techgit submodule update 12927187418SLiteSpeed Tech``` 13027187418SLiteSpeed Tech 13127187418SLiteSpeed TechBuild the Docker image: 132306ecefeSBrian Prodoehl``` 1335392f7a3SLiteSpeed Techdocker build -t lsquic . 134306ecefeSBrian Prodoehl``` 135306ecefeSBrian Prodoehl 13627187418SLiteSpeed TechThen you can use the examples from the command line. For example: 137306ecefeSBrian Prodoehl``` 13827187418SLiteSpeed Techsudo docker run -it --rm lsquic http_client -s www.google.com -p / -o version=Q046 13927187418SLiteSpeed Techsudo 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 140306ecefeSBrian Prodoehl``` 141306ecefeSBrian Prodoehl 142e0197994SDmitri TikhonovPlatforms 143e0197994SDmitri Tikhonov--------- 144e0197994SDmitri Tikhonov 1455392f7a3SLiteSpeed TechThe library has been tested on the following platforms: 146e0197994SDmitri Tikhonov- Linux 147aff2a1d8SDmitri Tikhonov - i386 148e0197994SDmitri Tikhonov - x86_64 149e0197994SDmitri Tikhonov - ARM (Raspberry Pi 3) 150e0197994SDmitri Tikhonov- FreeBSD 151e0197994SDmitri Tikhonov - i386 152e0197994SDmitri Tikhonov- MacOS 153e0197994SDmitri Tikhonov - x86_64 1549a690580SDmitri Tikhonov- Android 1559a690580SDmitri Tikhonov - ARM 156fb3e20e0SDmitri Tikhonov- Windows 1575392f7a3SLiteSpeed Tech - x86_64 15850aadb33SDmitri Tikhonov 159758aff32SDmitri TikhonovGet Involved 160758aff32SDmitri Tikhonov------------ 161758aff32SDmitri Tikhonov 162758aff32SDmitri TikhonovDo not hesitate to report bugs back to us. Even better, send us fixes 163758aff32SDmitri Tikhonovand improvements! 164758aff32SDmitri Tikhonov 16550aadb33SDmitri TikhonovHave fun, 16650aadb33SDmitri Tikhonov 16750aadb33SDmitri TikhonovLiteSpeed QUIC Team. 16850aadb33SDmitri Tikhonov 169740e26dcSJoshua ReynoldsCopyright (c) 2017 - 2020 LiteSpeed Technologies Inc 170