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