EXAMPLES.txt revision e0197994 
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_CUBIC_SHIFT_EPOCH
85
86    This environment variable determines whether cubic epoch is shifted
87    when sender is application-limited.
88
89    This is a leftover from the time when application-limited behavior was
90    implemented and is only available in debug builds.  By default, the
91    epoch is shifted.
92
93LSQUIC_PACER_INTERTICK
94
95    Number of microsecods to use as constant intertick time in lieu of the
96    pacer's dynamic intertick time approximation.
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