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