1# Copyright (c) 2017 - 2022 LiteSpeed Technologies Inc. See LICENSE. 2LSQUIC Examples 3=============== 4 5LSQUIC comes with several examples of how the library is used. 6 7The client and server programs described below are built on a common 8framework and share many options. 9 10Echo client and server 11---------------------- 12 13Echo client and server (see bin/echo_{client,server}.c) are for simple 14line-based request and reply communication. Only one stream per connection 15is supported for simplicity. The client reads input from stdin. 16 17MD5 client and server 18--------------------- 19 20See bin/md5_{client,server}.c 21 22MD5 server accepts connections, computes MD5 sum of streams' (one or more) 23payload, and sends back the checksum. MD5 client sends one or more file 24contents to the server. Both client and server support various options to 25exercise different aspects of LSQUIC. 26 27HTTP client and server 28---------------------- 29 30See bin/http_{client,server}.c 31 32This pair of programs is to demonstrate how to use HTTP features of QUIC. 33HTTP server is interoperable with proto-quic's quic_client. 34 35Duck client and server 36---------------------- 37 38See bin/duck_{client,server}.c 39 40This pair of programs implement the siduck-00 protocol. They provide an 41illustration of using the datagram API. 42 43Usage Examples 44-------------- 45 46Fetch Google's home page: 47 48 ./bin/http_client -s www.google.com -p / 49 50The default port number is 443, but it can be specified after colon 51using the -s flag. The value of the `host' header as well as the SNI 52value defaults to the host part of the -s option. -H option can be 53used to override it. For example: 54 55 ./bin/http_client -H www.youtube.com -s www.google.com:443 -p / -M HEAD 56 57The host part can be an IP address. Both IPv4 and IPv6 are supported. 58See ./bin/http_client -h for a (long) list of different flags. 59 60POST a file to calculate its CRC32 checksum: 61 62 ./bin/http_client -H www.litespeedtech.com -s 443 \ 63 -p /cgi-bin/crc32.cgi -P file-256M -M POST 64 65 HTTP/1.1 200 OK 66 content-type: text/plain 67 date: Fri, 09 Jun 2017 08:40:45 GMT 68 server: LiteSpeed 69 alt-svc: quic=":443"; v="35,37" 70 71 CRC32: 2A0E7DBB 72 73This is a good way to check that the payload gets to the other side 74correctly. The CGI script is: 75 76 #!/usr/bin/perl 77 use String::CRC32; 78 printf "Content-type: text/plain\r\n\r\nCRC32: %X\n", crc32(*STDIN) 79 80On the command line, I do 81 82 alias crc32="perl -MString::CRC32 -e'printf qq(%X\n), crc32(<>)'" 83 84To submit several requests concurrently, one can use -n and -r options: 85 86 ./bin/http_client -H www.litespeedtech.com -s 443 \ 87 -p /cgi-bin/crc32.cgi -P file-256M -M POST -n 3 -r 10 88 89This will open three parallel connections which will make ten POST 90requests together. 91 92To perform load testing, it is good to mix sending and receiving data: 93 94 for i in {1..100}; do 95 ./bin/http_client $COMMON_OPTS -p /cgi-bin/crc32.cgi -P file-256M \ 96 -M POST >out-post.$i & 97 ./bin/http_client $COMMON_OPTS -p /docs/file-256M >out-get.$i & 98 sleep 1 99 done 100 101If you don't want to create a hundred 256-megabyte out-get.* files, use -K 102flag to discard output. 103 104Testing Large Packet Sizes 105--------------------------------- 106 107IETF QUIC supports all valid UDP packet sizes. This section outlines the 108environment setup and testing parameters necessary to test this feature. 109 110Compilation 111 - Make sure to compile the library in DEBUG mode so that the NDEBUG 112 define is off. 113 - Build both the http_client and http_server test programs. 114 115Running Instructions 116 - Specify maximum packet size using -o base_plpmtu=$number. 117 Valid sizes are up to 65535. 118 - Use the -W flag for http_client and http_server for the ability 119 to send packets of large size. 120 - On the client side, use the -z flag to specify the maximum size 121 of packet that the client will accept. 122 123Example Usage 124 ./bin/http_client -p /file-1M -H www.litespeedtech.com -s 192.168.0.85:5443 125 -o version=FF000014 126 ./bin/http_server -c www.litespeedtech.com,certschain,privkey 127 -s 0.0.0.0:5443 -W -o base_plpmtu=65535 128 129Additional Notes 130 Since this feature does not have MTU discovery enabled at the time of 131 writing, make sure to use client and server machines that share a path 132 with the intended MTU. 133 134Control QUIC Settings via -o Flag 135--------------------------------- 136 137Most of the settings in struct squic_engine_settings can be controlled 138via -o flag. With exception of es_versions, which is a bit mask, other 139es_* options can be mapped to corresponding -o value via s/^es_//: 140 141 es_cfcw => -o cwcf=12345 142 es_max_streams_in => -o max_streams_in=123 143 144And so on. 145 146For example, to test version negotiation: 147 148 ./bin/http_server -c www.litespeedtech.com,certschain,privkey \ 149 -o version=Q035 -L debug 2>server.out & 150 ./bin/http_client -H www.litespeedtech.com -p Makefile -L debug 2>client.out 151 152Above, the client will start with the default, which is the highest supported 153QUIC version, which the server should negotiate down. You should see it from 154the log files. 155 156The code to set options via -o flag lives in set_engine_option(). It is good 157to update this function at the same time as member fields are added to struct 158lsquic_engine_settings. 159 160Control LSQUIC Behavior via Environment Variables 161------------------------------------------------- 162 163LSQUIC_PACKET_OUT_LIMIT 164 165 If set, the value of this environment variable is the maximum number 166 of packets that can be sent out in one shot. The limit is in the test 167 program framework's ea_packets_out() callback. 168 169 It is not applicable when sendmmsg(2) is used. 170 171 Note 1: sendmmsg can be enabled using -g option, if available for your 172 platform. 173 174 Note 2: see -m option for a related packet-out limitation. 175 176LSQUIC_LOSE_PACKETS_RE 177 178 If set, this regular expression specifies the numbers of packets which 179 the sender will lose on purpose. For example: 180 181 export LSQUIC_LOSE_PACKETS_RE='^(3|5|10)$' 182 183 The act of losing a packet is performed by changing its payload to 184 zero-filled buffer of the same size, which is almost as good as 185 not sending anything. The latter is difficult to implement without 186 negatively affecting the regular code flow. 187 188 Only available in debug builds. 189 190LSQUIC_PACER_INTERTICK 191 192 Number of microsecods to use as constant intertick time in lieu of the 193 pacer's dynamic intertick time approximation. 194 195 Only available in debug builds. 196 197LSQUIC_CUBIC_SAMPLING_RATE 198 199 Number of microseconds between times CWND is logged at info level. 200 201 Only available in debug builds. 202 203LSQUIC_RANDOM_SEND_FAILURE 204 205 Frequency with which sending of packets fails: one out of this many 206 times on average. 207 208 Only available when compiled with -DLSQUIC_RANDOM_SEND_FAILURE=1 209 210LSQUIC_LOG_SECRETS 211 212 If set to true value, crypto secrets will be logged. Applies to 213 IETF QUIC only. 214 215LSQUIC_COALESCE 216 217 If set to false, packets are not coalesced. Defaults to true. 218 219LSQUIC_USE_POOLS 220 221 If set to false, all memory pooling code is replaced with calls to 222 malloc() and free(). This facilitates debugging memory issues. 223 The default is true. 224 225LSQUIC_ACK_ATTACK 226 227 If set to true, generate optimistic ACKs. 228 229Control Network-Related Stuff 230----------------------------- 231 232 -D Set `do not fragment' flag on outgoing UDP packets. 233 234 -z BYTES Maximum size of outgoing UDP packets. The default is 1370 235 bytes for IPv4 socket and 1350 bytes for IPv6 socket. 236 237 -S opt=val Socket options. Supported options: 238 sndbuf=12345 # Sets SO_SNDBUF 239 rcvbuf=12345 # Sets SO_RCVBUF 240 241 -g Use sendmmsg() to send packets. This is only compiled in 242 if available. 243 244More Compilation Options 245------------------------ 246 247-DLSQUIC_CONN_STATS=1 248 249 Track some statistics about connections -- packets in, sent, delayed, 250 stream payload per packet size ratio, and some others -- and print them 251 at NOTICE level when connection is destroyed. 252 253 Cumulative connections statistics are printed by the engine when it is 254 destroyed if lsquic_engine_api.ea_stats_fh is set. The HTTP client 255 programs sets it when -t or -T command-line option is used. 256 257-DLSQUIC_PACKINTS_SANITY_CHECK=1 258 259 Turn on sanity checking for packet interval code. The packet interval 260 code, shared by both send and receive history modules, contained a bug 261 which prompted me to add a checking function. 262 263-DLSQUIC_SEND_STATS=0 264 265 Turn off statistics collection performed by the send controller: number 266 of packets sent, resent, and delayed. 267 268-DLOG_PACKET_CHECKSUM=1 269 270 When turned on, CRC32 checksum of each sent and received packet is 271 logged as an event. 272 273-DLSQUIC_LOWEST_LOG_LEVEL=LSQ_LOG_WARN 274 275 If you want to go even faster: compile out some log levels entirely. 276 277-DLSQUIC_EXTRA_CHECKS=1 278 279 Add relatively expensive run-time sanity checks 280 281-DLSQUIC_RANDOM_SEND_FAILURE=1 282 283 Simulate failure to send packets to test send resumption logic. When 284 this flag is specified, sending of packets will randomly fail, about 285 one out of every 10 attempts. Set environment variable 286 LSQUIC_RANDOM_SEND_FAILURE to change this frequency. 287 288-DLSQUIC_ECN_BLACK_HOLE=1 289 290 When compiled with this flag, setting environment variable 291 LSQUIC_ECN_BLACK_HOLE to 1 will emulate ECN black hole: all received 292 packets with ECN markings are dropped on the floor. 293 294-DLSQUIC_ACK_ATTACK=1 295 296 Enable ACK attack mode. See LSQUIC_ACK_ATTACK environment variable 297 entry above. 298