README.md revision b1a7c3f9
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, 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 18b1a7c3f9SDmitri TikhonovCurrently supported QUIC versions are Q043, Q046, Q050, ID-27, ID-28, ID-29, 19b1a7c3f9SDmitri Tikhonovand ID-30. Support for newer versions will be added soon after they are 20b1a7c3f9SDmitri Tikhonovreleased. 2150aadb33SDmitri Tikhonov 2250aadb33SDmitri TikhonovDocumentation 2350aadb33SDmitri Tikhonov------------- 2450aadb33SDmitri Tikhonov 25a5fa05f9SDmitri TikhonovDocumentation is available at https://lsquic.readthedocs.io/en/latest/. 26a5fa05f9SDmitri Tikhonov 27a5fa05f9SDmitri TikhonovIn addition, see example programs for API usage and EXAMPLES.txt for 28a5fa05f9SDmitri Tikhonovsome compilation and run-time options. 2950aadb33SDmitri Tikhonov 30e0197994SDmitri TikhonovRequirements 31e0197994SDmitri Tikhonov------------ 3250aadb33SDmitri Tikhonov 33e0197994SDmitri TikhonovTo build LSQUIC, you need CMake, zlib, and BoringSSL. The example program 34e0197994SDmitri Tikhonovuses libevent to provide the event loop. 3550aadb33SDmitri Tikhonov 36e0197994SDmitri TikhonovBuilding BoringSSL 37e0197994SDmitri Tikhonov------------------ 38e0197994SDmitri Tikhonov 39e0197994SDmitri TikhonovBoringSSL is not packaged; you have to build it yourself. The process is 40e0197994SDmitri Tikhonovstraightforward. You will need `go` installed. 41e0197994SDmitri Tikhonov 42e0197994SDmitri Tikhonov1. Clone BoringSSL by issuing the following command: 43e0197994SDmitri Tikhonov 44e0197994SDmitri Tikhonov``` 45e0197994SDmitri Tikhonovgit clone https://boringssl.googlesource.com/boringssl 46e0197994SDmitri Tikhonovcd boringssl 47e0197994SDmitri Tikhonov``` 48e0197994SDmitri Tikhonov 495392f7a3SLiteSpeed TechYou may need to install pre-requisites like zlib and libevent. 50e0197994SDmitri Tikhonov 51c38e7df7SDmitri Tikhonov2. Use specific BoringSSL version 52c38e7df7SDmitri Tikhonov 53c38e7df7SDmitri Tikhonov``` 54f913a297SDmitri Tikhonovgit checkout 251b5169fd44345f455438312ec4e18ae07fd58c 55c38e7df7SDmitri Tikhonov``` 56c38e7df7SDmitri Tikhonov 574947ba95SDmitri Tikhonov3. Compile the library 58e0197994SDmitri Tikhonov 59e0197994SDmitri Tikhonov``` 60e0197994SDmitri Tikhonovcmake . && make 61e0197994SDmitri Tikhonov``` 62e0197994SDmitri Tikhonov 63199c01abSLiteSpeed TechRemember where BoringSSL sources are: 64e0197994SDmitri Tikhonov``` 65199c01abSLiteSpeed TechBORINGSSL=$PWD 66e0197994SDmitri Tikhonov``` 67e0197994SDmitri Tikhonov 68199c01abSLiteSpeed TechIf you want to turn on optimizations, do 69e0197994SDmitri Tikhonov 70e0197994SDmitri Tikhonov``` 71199c01abSLiteSpeed Techcmake -DCMAKE_BUILD_TYPE=Release . && make 72e0197994SDmitri Tikhonov``` 73e0197994SDmitri Tikhonov 745392f7a3SLiteSpeed TechBuilding LSQUIC Library 755392f7a3SLiteSpeed Tech----------------------- 76e0197994SDmitri Tikhonov 775392f7a3SLiteSpeed TechLSQUIC's `http_client`, `http_server`, and the tests link BoringSSL 785392f7a3SLiteSpeed Techlibraries statically. Following previous section, you can build LSQUIC 795392f7a3SLiteSpeed Techas follows: 80e0197994SDmitri Tikhonov 8167b0dc15SDmitri Tikhonov1. Get the source code 8267b0dc15SDmitri Tikhonov 8367b0dc15SDmitri Tikhonov``` 845392f7a3SLiteSpeed Techgit clone https://github.com/litespeedtech/lsquic.git 855392f7a3SLiteSpeed Techcd lsquic 865392f7a3SLiteSpeed Techgit submodule init 875392f7a3SLiteSpeed Techgit submodule update 8867b0dc15SDmitri Tikhonov``` 8967b0dc15SDmitri Tikhonov 9067b0dc15SDmitri Tikhonov2. Compile the library 9167b0dc15SDmitri Tikhonov 9267b0dc15SDmitri Tikhonov 93e0197994SDmitri Tikhonov``` 94199c01abSLiteSpeed Tech# $BORINGSSL is the top-level BoringSSL directory from the previous step 95199c01abSLiteSpeed Techcmake -DBORINGSSL_DIR=$BORINGSSL . 96e0197994SDmitri Tikhonovmake 97e0197994SDmitri Tikhonov``` 98e0197994SDmitri Tikhonov 9967b0dc15SDmitri Tikhonov3. Run tests 100e0197994SDmitri Tikhonov 101e0197994SDmitri Tikhonov``` 102e0197994SDmitri Tikhonovmake test 103e0197994SDmitri Tikhonov``` 104e0197994SDmitri Tikhonov 105306ecefeSBrian ProdoehlBuilding with Docker 106306ecefeSBrian Prodoehl--------- 10727187418SLiteSpeed TechThe library and the example client and server can be built with Docker. 10827187418SLiteSpeed Tech 10927187418SLiteSpeed TechInitialize Git submodules: 11027187418SLiteSpeed Tech``` 11127187418SLiteSpeed Techcd lsquic 11227187418SLiteSpeed Techgit submodule init 11327187418SLiteSpeed Techgit submodule update 11427187418SLiteSpeed Tech``` 11527187418SLiteSpeed Tech 11627187418SLiteSpeed TechBuild the Docker image: 117306ecefeSBrian Prodoehl``` 1185392f7a3SLiteSpeed Techdocker build -t lsquic . 119306ecefeSBrian Prodoehl``` 120306ecefeSBrian Prodoehl 12127187418SLiteSpeed TechThen you can use the examples from the command line. For example: 122306ecefeSBrian Prodoehl``` 12327187418SLiteSpeed Techsudo docker run -it --rm lsquic http_client -s www.google.com -p / -o version=Q046 12427187418SLiteSpeed 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 125306ecefeSBrian Prodoehl``` 126306ecefeSBrian Prodoehl 127e0197994SDmitri TikhonovPlatforms 128e0197994SDmitri Tikhonov--------- 129e0197994SDmitri Tikhonov 1305392f7a3SLiteSpeed TechThe library has been tested on the following platforms: 131e0197994SDmitri Tikhonov- Linux 132aff2a1d8SDmitri Tikhonov - i386 133e0197994SDmitri Tikhonov - x86_64 134e0197994SDmitri Tikhonov - ARM (Raspberry Pi 3) 135e0197994SDmitri Tikhonov- FreeBSD 136e0197994SDmitri Tikhonov - i386 137e0197994SDmitri Tikhonov- MacOS 138e0197994SDmitri Tikhonov - x86_64 1399a690580SDmitri Tikhonov- Android 1409a690580SDmitri Tikhonov - ARM 141fb3e20e0SDmitri Tikhonov- Windows 1425392f7a3SLiteSpeed Tech - x86_64 14350aadb33SDmitri Tikhonov 14450aadb33SDmitri TikhonovHave fun, 14550aadb33SDmitri Tikhonov 14650aadb33SDmitri TikhonovLiteSpeed QUIC Team. 14750aadb33SDmitri Tikhonov 148740e26dcSJoshua ReynoldsCopyright (c) 2017 - 2020 LiteSpeed Technologies Inc 149