EXAMPLES.txt revision 19f667fb 
1# Copyright (c) 2017 - 2019 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
100LSQUIC_RANDOM_SEND_FAILURE
101
102    Frequency with which sending of packets fails: one out of this many
103    times on average.
104
105    Only available when compiled with -DLSQUIC_RANDOM_SEND_FAILURE=1
106
107Control Network-Related Stuff
108-----------------------------
109
110   -D          Set `do not fragment' flag on outgoing UDP packets.
111
112   -z BYTES    Maximum size of outgoing UDP packets.  The default is 1370
113               bytes for IPv4 socket and 1350 bytes for IPv6 socket.
114
115   -S opt=val  Socket options.  Supported options:
116                   sndbuf=12345    # Sets SO_SNDBUF
117                   rcvbuf=12345    # Sets SO_RCVBUF
118
119More Compilation Options
120------------------------
121
122-DLSQUIC_CONN_STATS=1
123
124    Track some statistics about connections -- packets in, sent, delayed,
125    stream payload per packet size ratio, and some others -- and print them
126    at NOTICE level when connection is destroyed.
127
128    Cumulative connections statistics are printed by the engine when it is
129    destroyed if lsquic_engine_api.ea_stats_fh is set.  The HTTP client
130    programs sets it when -t or -T command-line option is used.
131
132-DLSQUIC_PACKINTS_SANITY_CHECK=1
133
134    Turn on sanity checking for packet interval code.  The packet interval
135    code, shared by both send and receive history modules, contained a bug
136    which prompted me to add a checking function.
137
138-DLSQUIC_SEND_STATS=0
139
140    Turn off statistics collection performed by the send controller: number
141    of packets sent, resent, and delayed.
142
143-DLSQUIC_LOWEST_LOG_LEVEL=LSQ_LOG_WARN
144
145    If you want to go even faster: compile out some log levels entirely.
146
147-DLSQUIC_EXTRA_CHECKS=1
148
149    Add relatively expensive run-time sanity checks
150
151-DLSQUIC_RANDOM_SEND_FAILURE=1
152
153    Simulate failure to send packets to test send resumption logic.  When
154    this flag is specified, sending of packets will randomly fail, about
155    one out of every 10 attempts.  Set environment variable
156    LSQUIC_RANDOM_SEND_FAILURE to change this frequency.
157