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