EXAMPLES.txt revision bdba46fd 
1# Copyright (c) 2017 - 2018 LiteSpeed Technologies Inc.  See LICENSE.
2LSQUIC Examples
3===============
4
5test/http_client.c demonstrates how to use HTTP features of QUIC.
6
7Usage Examples
8--------------
9
10Fetch Google's home page:
11
12    ./http_client -H www.google.com -s 74.125.22.106:443 -p /
13
14    or even
15
16    ./http_client -H www.google.co.uk -s 2a00:1450:4009:80c::2003:443 -p /
17
18In the example above, -H specifies the domain; it is also used as the value
19of SNI paramater in the handshake.
20
21The IP address and the port number are specified using the -s flag.
22
23(Since www.google.com has different IP addresses in different regions, check
24that you are using the correct IP address by resolving www.google.com first
25by using nslookup, dig, ping, or some other tool.)
26
27POST a file to calculate its CRC32 checksum:
28
29    ./http_client -H www.litespeedtech.com -s 127.0.0.1:443 \
30                        -p /cgi-bin/crc32.cgi -P file-256M -M POST
31
32    HTTP/1.1 200 OK
33    content-type: text/plain
34    date: Fri, 09 Jun 2017 08:40:45 GMT
35    server: LiteSpeed
36    alt-svc: quic=":443"; v="35,37"
37
38    CRC32: 2A0E7DBB
39
40This is a good way to check that the payload gets to the other side
41correctly.  The CGI script is:
42
43    #!/usr/bin/perl
44    use String::CRC32;
45    printf "Content-type: text/plain\r\n\r\nCRC32: %X\n", crc32(*STDIN)
46
47On the command line, I do
48
49    alias crc32="perl -MString::CRC32 -e'printf qq(%X\n), crc32(<>)'"
50
51To submit several requests concurrently, one can use -n and -r options:
52
53    ./http_client -H www.litespeedtech.com -s 127.0.0.1:443 \
54                -p /cgi-bin/crc32.cgi -P file-256M -M POST -n 3 -r 10
55
56This will open three parallel connections which will make ten POST
57requests together.
58
59To perform load testing, it is good to mix sending and receiving data:
60
61    for i in {1..100}; do
62        ./http_client $COMMON_OPTS -p /cgi-bin/crc32.cgi -P file-256M \
63                                                    -M POST >out-post.$i &
64        ./http_client $COMMON_OPTS -p /docs/file-256M >out-get.$i        &
65        sleep 1
66    done
67
68If you don't want to create a hundred 256-megabyte out-get.* files, use -K
69flag to discard output.
70
71Control QUIC Settings via -o Flag
72---------------------------------
73
74Most of the settings in struct lsquic_engine_settings can be controlled
75via -o flag.  With exception of es_versions, which is a bit mask, other
76es_* options can be mapped to corresponding -o value via s/^es_//:
77
78    es_cfcw             =>  -o cwcf=12345
79    es_max_streams_in   =>  -o max_streams_in=123
80
81And so on.
82
83The code to set options via -o flag lives in set_engine_option().  It is good
84to update this function at the same time as member fields are added to struct
85lsquic_engine_settings.
86
87Control LSQUIC Behavior via Environment Variables
88-------------------------------------------------
89
90LSQUIC_PACER_INTERTICK
91
92    Number of microsecods to use as constant intertick time in lieu of the
93    pacer's dynamic intertick time approximation.
94
95    Only available in debug builds.
96
97LSQUIC_CUBIC_SAMPLING_RATE
98
99    Number of microseconds between times CWND is logged at info level.
100
101    Only available in debug builds.
102
103Control Network-Related Stuff
104-----------------------------
105
106   -D          Set `do not fragment' flag on outgoing UDP packets.
107
108   -z BYTES    Maximum size of outgoing UDP packets.  The default is 1370
109               bytes for IPv4 socket and 1350 bytes for IPv6 socket.
110
111   -S opt=val  Socket options.  Supported options:
112                   sndbuf=12345    # Sets SO_SNDBUF
113                   rcvbuf=12345    # Sets SO_RCVBUF
114
115More Compilation Options
116------------------------
117
118-DFULL_CONN_STATS=1
119
120    Track some statistics about full connection -- packets in, sent, delayed,
121    stream payload per packet size ratio, and some others -- and print them
122    at NOTICE level when connection is destroyed.
123
124    This is useful when performing network testing and especially analyzing
125    the effects of changing send buffer size (see -S sndbuf= in the previous
126    section).
127
128-DLSQUIC_PACKINTS_SANITY_CHECK=1
129
130    Turn on sanity checking for packet interval code.  The packet interval
131    code, shared by both send and receive history modules, contained a bug
132    which prompted me to add a checking function.
133
134-DLSQUIC_SEND_STATS=0
135
136    Turn off statistics collection performed by the send controller: number
137    of packets sent, resent, and delayed.
138
139-DLSQUIC_LOWEST_LOG_LEVEL=LSQ_LOG_WARN
140
141    If you want to go even faster: compile out some log levels entirely.
142
143-DLSQUIC_EXTRA_CHECKS=1
144
145    Add relatively expensive run-time sanity checks
146
147