README.md revision 08927b28
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) 35392f7a3SLiteSpeed Tech[![Build status](https://ci.appveyor.com/api/projects/status/kei9649t9leoqicr?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, 14f87fb49cSDmitri Tikhonovand OpenLiteSpeed. We think it is free of major problems. Nevertheless, do 15f87fb49cSDmitri Tikhonovnot hesitate to report bugs back to us. Even better, send us fixes and 16f87fb49cSDmitri Tikhonovimprovements! 1750aadb33SDmitri Tikhonov 1808927b28SDmitri TikhonovCurrently supported QUIC versions are Q043, Q046, Q050, ID-27, and ID-28. 19767cf611SDmitri TikhonovSupport for newer versions will be added soon after they are released. 2050aadb33SDmitri Tikhonov 2150aadb33SDmitri TikhonovDocumentation 2250aadb33SDmitri Tikhonov------------- 2350aadb33SDmitri Tikhonov 24a5fa05f9SDmitri TikhonovDocumentation is available at https://lsquic.readthedocs.io/en/latest/. 25a5fa05f9SDmitri Tikhonov 26a5fa05f9SDmitri TikhonovIn addition, see example programs for API usage and EXAMPLES.txt for 27a5fa05f9SDmitri Tikhonovsome compilation and run-time options. 2850aadb33SDmitri Tikhonov 29e0197994SDmitri TikhonovRequirements 30e0197994SDmitri Tikhonov------------ 3150aadb33SDmitri Tikhonov 32e0197994SDmitri TikhonovTo build LSQUIC, you need CMake, zlib, and BoringSSL. The example program 33e0197994SDmitri Tikhonovuses libevent to provide the event loop. 3450aadb33SDmitri Tikhonov 35e0197994SDmitri TikhonovBuilding BoringSSL 36e0197994SDmitri Tikhonov------------------ 37e0197994SDmitri Tikhonov 38e0197994SDmitri TikhonovBoringSSL is not packaged; you have to build it yourself. The process is 39e0197994SDmitri Tikhonovstraightforward. You will need `go` installed. 40e0197994SDmitri Tikhonov 41e0197994SDmitri Tikhonov1. Clone BoringSSL by issuing the following command: 42e0197994SDmitri Tikhonov 43e0197994SDmitri Tikhonov``` 44e0197994SDmitri Tikhonovgit clone https://boringssl.googlesource.com/boringssl 45e0197994SDmitri Tikhonovcd boringssl 46e0197994SDmitri Tikhonov``` 47e0197994SDmitri Tikhonov 485392f7a3SLiteSpeed TechYou may need to install pre-requisites like zlib and libevent. 49e0197994SDmitri Tikhonov 50c38e7df7SDmitri Tikhonov2. Use specific BoringSSL version 51c38e7df7SDmitri Tikhonov 52c38e7df7SDmitri Tikhonov``` 537b08963cSDmitri Tikhonovgit checkout bfe527fa35735e8e045cbfb42b012e13ca68f9cf 54c38e7df7SDmitri Tikhonov``` 55c38e7df7SDmitri Tikhonov 564947ba95SDmitri Tikhonov3. Compile the library 57e0197994SDmitri Tikhonov 58e0197994SDmitri Tikhonov``` 59e0197994SDmitri Tikhonovcmake . && make 60e0197994SDmitri Tikhonov``` 61e0197994SDmitri Tikhonov 62199c01abSLiteSpeed TechRemember where BoringSSL sources are: 63e0197994SDmitri Tikhonov``` 64199c01abSLiteSpeed TechBORINGSSL=$PWD 65e0197994SDmitri Tikhonov``` 66e0197994SDmitri Tikhonov 67199c01abSLiteSpeed TechIf you want to turn on optimizations, do 68e0197994SDmitri Tikhonov 69e0197994SDmitri Tikhonov``` 70199c01abSLiteSpeed Techcmake -DCMAKE_BUILD_TYPE=Release . && make 71e0197994SDmitri Tikhonov``` 72e0197994SDmitri Tikhonov 735392f7a3SLiteSpeed TechBuilding LSQUIC Library 745392f7a3SLiteSpeed Tech----------------------- 75e0197994SDmitri Tikhonov 765392f7a3SLiteSpeed TechLSQUIC's `http_client`, `http_server`, and the tests link BoringSSL 775392f7a3SLiteSpeed Techlibraries statically. Following previous section, you can build LSQUIC 785392f7a3SLiteSpeed Techas follows: 79e0197994SDmitri Tikhonov 8067b0dc15SDmitri Tikhonov1. Get the source code 8167b0dc15SDmitri Tikhonov 8267b0dc15SDmitri Tikhonov``` 835392f7a3SLiteSpeed Techgit clone https://github.com/litespeedtech/lsquic.git 845392f7a3SLiteSpeed Techcd lsquic 855392f7a3SLiteSpeed Techgit submodule init 865392f7a3SLiteSpeed Techgit submodule update 8767b0dc15SDmitri Tikhonov``` 8867b0dc15SDmitri Tikhonov 8967b0dc15SDmitri Tikhonov2. Compile the library 9067b0dc15SDmitri Tikhonov 9167b0dc15SDmitri Tikhonov 92e0197994SDmitri Tikhonov``` 93199c01abSLiteSpeed Tech# $BORINGSSL is the top-level BoringSSL directory from the previous step 94199c01abSLiteSpeed Techcmake -DBORINGSSL_DIR=$BORINGSSL . 95e0197994SDmitri Tikhonovmake 96e0197994SDmitri Tikhonov``` 97e0197994SDmitri Tikhonov 9867b0dc15SDmitri Tikhonov3. Run tests 99e0197994SDmitri Tikhonov 100e0197994SDmitri Tikhonov``` 101e0197994SDmitri Tikhonovmake test 102e0197994SDmitri Tikhonov``` 103e0197994SDmitri Tikhonov 104306ecefeSBrian ProdoehlBuilding with Docker 105306ecefeSBrian Prodoehl--------- 10627187418SLiteSpeed TechThe library and the example client and server can be built with Docker. 10727187418SLiteSpeed Tech 10827187418SLiteSpeed TechInitialize Git submodules: 10927187418SLiteSpeed Tech``` 11027187418SLiteSpeed Techcd lsquic 11127187418SLiteSpeed Techgit submodule init 11227187418SLiteSpeed Techgit submodule update 11327187418SLiteSpeed Tech``` 11427187418SLiteSpeed Tech 11527187418SLiteSpeed TechBuild the Docker image: 116306ecefeSBrian Prodoehl``` 1175392f7a3SLiteSpeed Techdocker build -t lsquic . 118306ecefeSBrian Prodoehl``` 119306ecefeSBrian Prodoehl 12027187418SLiteSpeed TechThen you can use the examples from the command line. For example: 121306ecefeSBrian Prodoehl``` 12227187418SLiteSpeed Techsudo docker run -it --rm lsquic http_client -s www.google.com -p / -o version=Q046 12327187418SLiteSpeed 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 124306ecefeSBrian Prodoehl``` 125306ecefeSBrian Prodoehl 126e0197994SDmitri TikhonovPlatforms 127e0197994SDmitri Tikhonov--------- 128e0197994SDmitri Tikhonov 1295392f7a3SLiteSpeed TechThe library has been tested on the following platforms: 130e0197994SDmitri Tikhonov- Linux 131aff2a1d8SDmitri Tikhonov - i386 132e0197994SDmitri Tikhonov - x86_64 133e0197994SDmitri Tikhonov - ARM (Raspberry Pi 3) 134e0197994SDmitri Tikhonov- FreeBSD 135e0197994SDmitri Tikhonov - i386 136e0197994SDmitri Tikhonov- MacOS 137e0197994SDmitri Tikhonov - x86_64 1389a690580SDmitri Tikhonov- Android 1399a690580SDmitri Tikhonov - ARM 1405392f7a3SLiteSpeed Tech- Windows (this needs updating for the server part, now broken) 1415392f7a3SLiteSpeed Tech - x86_64 14250aadb33SDmitri Tikhonov 14350aadb33SDmitri TikhonovHave fun, 14450aadb33SDmitri Tikhonov 14550aadb33SDmitri TikhonovLiteSpeed QUIC Team. 14650aadb33SDmitri Tikhonov 147740e26dcSJoshua ReynoldsCopyright (c) 2017 - 2020 LiteSpeed Technologies Inc 148