1 Overview of lws test apps
2 =========================
4 Are you building a client? You just need to look at the test client
5 [libwebsockets-test-client](../test-apps/test-client.c).
7 If you are building a standalone server, there are three choices, in order of
10 1) lwsws + protocol plugins
12 Lws provides a generic web server app that can be configured with JSON
13 config files. https://libwebsockets.org itself uses this method.
15 With lwsws handling the serving part, you only need to write an lws protocol
16 plugin. See [plugin-standalone](../plugin-standalone) for an example of how
17 to do that outside lws itself, using lws public apis.
19 $ cmake .. -DLWS_WITH_LWSWS=1
21 See [README.lwsws.md](../READMEs/README.lwsws.md) for information on how to configure
24 NOTE this method implies libuv is used by lws, to provide crossplatform
25 implementations of timers, dynamic lib loading etc for plugins and lwsws.
29 This method lets you configure web serving in code, instead of using lwsws.
31 Plugins are still used, but you have a choice whether to dynamically load
32 them or statically include them. In this example, they are dynamically
35 $ cmake .. -DLWS_WITH_PLUGINS=1
37 See [test-server-v2.0.c](../test-apps/test-server-v2.0.c)
39 3) protocols in the server app
41 This is the original way lws implemented servers, plugins and libuv are not
42 required, but without plugins separating the protocol code directly, the
43 combined code is all squidged together and is much less maintainable.
45 This method is still supported in lws but all ongoing and future work is
46 being done in protocol plugins only.
48 You can simply include the plugin contents and have it buit statically into
49 your server, just define this before including the plugin source
52 #define LWS_PLUGIN_STATIC
55 This gets you most of the advantages without needing dynamic loading +
59 Notes about lws test apps
60 =========================
62 @section tsb Testing server with a browser
64 If you run [libwebsockets-test-server](../test-apps/test-server.c) and point your browser
69 It will fetch a script in the form of `test.html`, and then run the
70 script in there on the browser to open a websocket connection.
71 Incrementing numbers should appear in the browser display.
73 By default the test server logs to both stderr and syslog, you can control
74 what is logged using `-d <log level>`, see later.
77 @section tsd Running test server as a Daemon
79 You can use the -D option on the test server to have it fork into the
80 background and return immediately. In this daemonized mode all stderr is
81 disabled and logging goes only to syslog, eg, `/var/log/messages` or similar.
83 The server maintains a lockfile at `/tmp/.lwsts-lock` that contains the pid
84 of the master process, and deletes this file when the master process
87 To stop the daemon, do
89 $ kill \`cat /tmp/.lwsts-lock\`
91 If it finds a stale lock (the pid mentioned in the file does not exist
92 any more) it will delete the lock and create a new one during startup.
94 If the lock is valid, the daemon will exit with a note on stderr that
95 it was already running.
97 @section clicert Testing Client Certs
99 Here is a very quick way to create a CA, and a client and server cert from it,
103 $ cp -rp ./scripts/client-ca /tmp
106 $ ./create-server-cert.sh server
107 $ ./create-client-cert.sh client
110 The last step wants an export password, you will need this password again to
111 import the p12 format certificate into your browser.
113 This will get you the following
117 |ca.pem|Your Certificate Authority cert|
118 |ca.key|Private key for the CA cert|
119 |client.pem|Client certificate, signed by your CA|
120 |client.key|Client private key|
121 |client.p12|combined client.pem + client.key in p12 format for browsers|
122 |server.pem|Server cert, signed by your CA|
123 |server.key|Server private key|
125 You can confirm yourself the client and server certs are signed by the CA.
128 $ openssl verify -verbose -trusted ca.pem server.pem
129 $ openssl verify -verbose -trusted ca.pem client.pem
132 Import the client.p12 file into your browser. In FFOX57 it's
136 - Certificates | View Certificates
137 - Certificate Manager | Your Certificates | Import...
138 - Enter the password you gave when creating client1.p12
141 You can then run the test server like this:
144 $ libwebsockets-test-server -s -A ca.pem -K server.key -C server.pem -v
147 When you connect your browser to https://localhost:7681 after accepting the
148 selfsigned server cert, your browser will pop up a prompt to send the server
149 your client cert (the -v switch enables this). The server will only accept
150 a client cert that has been signed by ca.pem.
152 @section sssl Using SSL on the server side
154 To test it using SSL/WSS, just run the test server with
156 $ libwebsockets-test-server --ssl
160 https://127.0.0.1:7681
162 The connection will be entirely encrypted using some generated
163 certificates that your browser will not accept, since they are
164 not signed by any real Certificate Authority. Just accept the
165 certificates in the browser and the connection will proceed
166 in first https and then websocket wss, acting exactly the
169 [test-server.c](../test-apps/test-server.c) is all that is needed to use libwebsockets for
170 serving both the script html over http and websockets.
172 @section lwstsdynvhost Dynamic Vhosts
174 You can send libwebsockets-test-server or libwebsockets-test-server-v2.0 a SIGUSR1
175 to toggle the creation and destruction of an identical second vhost on port + 1.
177 This is intended as a test and demonstration for how to bring up and remove
180 @section unixskt Testing Unix Socket Server support
182 Start the test server with -U and the path to create the unix domain socket
185 $ libwebsockets-test-server -U /tmp/uds
188 On exit, lws will delete the socket inode.
190 To test the client side, eg
193 $ nc -C -U /tmp/uds -i 30
200 followed by two ENTER. The contents of test.html should be returned.
202 @section wscl Testing websocket client support
204 If you run the test server as described above, you can also
205 connect to it using the test client as well as a browser.
208 $ libwebsockets-test-client localhost
211 will by default connect to the test server on localhost:7681
212 and print the dumb increment number from the server at the
213 same time as drawing random circles in the mirror protocol;
214 if you connect to the test server using a browser at the
215 same time you will be able to see the circles being drawn.
217 The test client supports SSL too, use
220 $ libwebsockets-test-client localhost --ssl -s
223 the -s tells it to accept the default self-signed cert from the server,
224 otherwise it will strictly fail the connection if there is no CA cert to
225 validate the server's certificate.
228 @section choosingts Choosing between test server variations
230 If you will be doing standalone serving with lws, ideally you should avoid
231 making your own server at all, and use lwsws with your own protocol plugins.
233 The second best option is follow test-server-v2.0.c, which uses a mount to
234 autoserve a directory, and lws protocol plugins for ws, without needing any
235 user callback code (other than what's needed in the protocol plugin).
237 For those two options libuv is needed to support the protocol plugins, if
238 that's not possible then the other variations with their own protocol code
239 should be considered.
241 @section tassl Testing SSL on the client side
243 To test SSL/WSS client action, just run the client test with
245 $ libwebsockets-test-client localhost --ssl
247 By default the client test applet is set to accept self-signed
248 certificates used by the test server, this is indicated by the
249 `use_ssl` var being set to `2`. Set it to `1` to reject any server
250 certificate that it doesn't have a trusted CA cert for.
253 @section taping Using the websocket ping utility
255 libwebsockets-test-ping connects as a client to a remote
256 websocket server and pings it like the
257 normal unix ping utility.
259 $ libwebsockets-test-ping localhost
260 handshake OK for protocol lws-mirror-protocol
261 Websocket PING localhost.localdomain (127.0.0.1) 64 bytes of data.
262 64 bytes from localhost: req=1 time=0.1ms
263 64 bytes from localhost: req=2 time=0.1ms
264 64 bytes from localhost: req=3 time=0.1ms
265 64 bytes from localhost: req=4 time=0.2ms
266 64 bytes from localhost: req=5 time=0.1ms
267 64 bytes from localhost: req=6 time=0.2ms
268 64 bytes from localhost: req=7 time=0.2ms
269 64 bytes from localhost: req=8 time=0.1ms
271 --- localhost.localdomain websocket ping statistics ---
272 8 packets transmitted, 8 received, 0% packet loss, time 7458ms
273 rtt min/avg/max = 0.110/0.185/0.218 ms
276 By default it sends 64 byte payload packets using the 04
277 PING packet opcode type. You can change the payload size
278 using the `-s=` flag, up to a maximum of 125 mandated by the
281 Using the lws-mirror protocol that is provided by the test
282 server, libwebsockets-test-ping can also use larger payload
283 sizes up to 4096 is BINARY packets; lws-mirror will copy
284 them back to the client and they appear as a PONG. Use the
285 `-m` flag to select this operation.
287 The default interval between pings is 1s, you can use the -i=
288 flag to set this, including fractions like `-i=0.01` for 10ms
291 Before you can even use the PING opcode that is part of the
292 standard, you must complete a handshake with a specified
293 protocol. By default lws-mirror-protocol is used which is
294 supported by the test server. But if you are using it on
295 another server, you can specify the protocol to handshake with
296 by `--protocol=protocolname`
299 @section ta fraggle Fraggle test app
301 By default it runs in server mode
303 $ libwebsockets-test-fraggle
304 libwebsockets test fraggle
305 (C) Copyright 2010-2011 Andy Green <andy@warmcat.com> licensed under LGPL2.1
306 Compiled with SSL support, not using it
307 Listening on port 7681
308 server sees client connect
309 accepted v06 connection
310 Spamming 360 random fragments
311 Spamming session over, len = 371913. sum = 0x2D3C0AE
312 Spamming 895 random fragments
313 Spamming session over, len = 875970. sum = 0x6A74DA1
316 You need to run a second session in client mode, you have to
317 give the `-c` switch and the server address at least:
319 $ libwebsockets-test-fraggle -c localhost
320 libwebsockets test fraggle
321 (C) Copyright 2010-2011 Andy Green <andy@warmcat.com> licensed under LGPL2.1
323 Connecting to localhost:7681
324 denied deflate-stream extension
325 handshake OK for protocol fraggle-protocol
326 client connects to server
327 EOM received 371913 correctly from 360 fragments
328 EOM received 875970 correctly from 895 fragments
329 EOM received 247140 correctly from 258 fragments
330 EOM received 695451 correctly from 692 fragments
333 The fraggle test sends a random number up to 1024 fragmented websocket frames
334 each of a random size between 1 and 2001 bytes in a single message, then sends
335 a checksum and starts sending a new randomly sized and fragmented message.
337 The fraggle test client receives the same message fragments and computes the
338 same checksum using websocket framing to see when the message has ended. It
339 then accepts the server checksum message and compares that to its checksum.
342 @section taproxy proxy support
344 The http_proxy environment variable is respected by the client
345 connection code for both `ws://` and `wss://`. It doesn't support
350 $ export http_proxy=myproxy.com:3128
351 $ libwebsockets-test-client someserver.com
354 @section talog debug logging
356 By default logging of severity "notice", "warn" or "err" is enabled to stderr.
358 Again by default other logging is compiled in but disabled from printing.
360 By default debug logs below "notice" in severity are not compiled in. To get
361 them included, add this option in CMAKE
364 $ cmake .. -DCMAKE_BUILD_TYPE=DEBUG
367 If you want to see more detailed debug logs, you can control a bitfield to
368 select which logs types may print using the `lws_set_log_level()` api, in the
369 test apps you can use `-d <number>` to control this. The types of logging
370 available are (OR together the numbers to select multiple)
384 @section ws13 Websocket version supported
386 The final IETF standard is supported for both client and server, protocol
390 @section latency Latency Tracking
392 Since libwebsockets runs using `poll()` and a single threaded approach, any
393 unexpected latency coming from system calls would be bad news. There's now
394 a latency tracking scheme that can be built in with `-DLWS_WITH_LATENCY=1` at
395 cmake, logging the time taken for system calls to complete and if
396 the whole action did complete that time or was deferred.
398 You can see the detailed data by enabling logging level 512 (eg, `-d 519` on
399 the test server to see that and the usual logs), however even without that
400 the "worst" latency is kept and reported to the logs with NOTICE severity
401 when the context is destroyed.
403 Some care is needed interpreting them, if the action completed the first figure
404 (in us) is the time taken for the whole action, which may have retried through
405 the poll loop many times and will depend on network roundtrip times. High
406 figures here don't indicate a problem. The figure in us reported after "lat"
407 in the logging is the time taken by this particular attempt. High figures
408 here may indicate a problem, or if you system is loaded with another app at
409 that time, such as the browser, it may simply indicate the OS gave preferential
410 treatment to the other app during that call.
413 @section autobahn Autobahn Test Suite
415 Lws can be tested against the autobahn websocket fuzzer in both client and
418 1) pip install autobahntestsuite
420 2) From your build dir:
423 $ cmake .. -DLWS_WITHOUT_EXTENSIONS=0 -DLWS_WITH_MINIMAL_EXAMPLES=1 && make
426 3) ../scripts/autobahn-test.sh
428 4) In a browser go to the directory you ran wstest in (eg, /projects/libwebsockets)
430 file:///projects/libwebsockets/build/reports/clients/index.html
435 @section autobahnnotes Autobahn Test Notes
437 1) Two of the tests make no sense for Libwebsockets to support and we fail them.
439 - Tests 2.10 + 2.11: sends multiple pings on one connection. Lws policy is to
440 only allow one active ping in flight on each connection, the rest are dropped.
441 The autobahn test itself admits this is not part of the standard, just someone's
442 random opinion about how they think a ws server should act. So we will fail
443 this by design and it is no problem about RFC6455 compliance.
445 2) Currently two parts of autobahn are broken and we skip them
447 https://github.com/crossbario/autobahn-testsuite/issues/71