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