README.md revision 740e26dc
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 18bc520ef7SDmitri TikhonovCurrently supported QUIC versions are Q043, Q046, Q050, ID-25, and ID-27. 19767cf611SDmitri TikhonovSupport for newer versions will be added soon after they are released. 2050aadb33SDmitri Tikhonov 2150aadb33SDmitri TikhonovDocumentation 2250aadb33SDmitri Tikhonov------------- 2350aadb33SDmitri Tikhonov 24740e26dcSJoshua ReynoldsThe documentation for this module is admittedly sparse but is now externally hosted at [Read the Docs](https://lsquic.readthedocs.io/en/latest/). The API is 2550aadb33SDmitri Tikhonovdocumented in include/lsquic.h. If you have doxygen, you can run 26e0197994SDmitri Tikhonov`doxygen dox.cfg` or `make docs`. The example program is 2750aadb33SDmitri Tikhonovtest/http_client.c: a bare-bones, but working, QUIC client. Have a look 2850aadb33SDmitri Tikhonovin EXAMPLES.txt to see how it can be used. 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``` 544947ba95SDmitri Tikhonovgit checkout 49de1fc2910524c888866c7e2b0db1ba8af2a530 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 1395392f7a3SLiteSpeed Tech- Windows (this needs updating for the server part, now broken) 1405392f7a3SLiteSpeed Tech - x86_64 14150aadb33SDmitri Tikhonov 14250aadb33SDmitri TikhonovHave fun, 14350aadb33SDmitri Tikhonov 14450aadb33SDmitri TikhonovLiteSpeed QUIC Team. 14550aadb33SDmitri Tikhonov 146740e26dcSJoshua ReynoldsCopyright (c) 2017 - 2020 LiteSpeed Technologies Inc 147