1 Using test-server as a quickstart
2 ---------------------------------
4 For a Fedora x86_86 box, the following config line was
7 ./configure --prefix=/usr --libdir=/usr/lib64 --enable-openssl
9 For Apple systems, Christopher Baker reported that this is needed
10 (and I was told separately enabling openssl makes trouble somehow)
12 ./configure CC="gcc -arch i386 -arch x86_64" CXX="g++ -arch i386 -arch
13 x86_64" CPP="gcc -E" CXXCPP="g++ -E" --enable-nofork
16 otherwise if /usr/local/... and /usr/local/lib are OK then...
22 $ libwebsockets-test-server
24 should be enough to get a test server listening on port 7861.
26 There are a couple of other possible configure options
28 --enable-nofork disables the fork into the background API
29 and removes all references to fork() and
30 pr_ctl() from the sources. Use it if your
31 platform doesn't support forking.
33 --enable-libcrypto by default libwebsockets uses its own
34 built-in md5 and sha-1 implementation for
35 simplicity. However the libcrypto ones
36 may be faster, and in a distro context it
37 may be highly desirable to use a common
38 library implementation for ease of security
39 upgrades. Give this configure option
40 to disable the built-in ones and force use
41 of the libcrypto (part of openssl) ones.
43 --with-client-cert-dir=dir tells the client ssl support where to
44 look for trust certificates to validate
45 the remote certificate against.
47 --enable-noping Don't try to build the ping test app
48 It needs some unixy environment that
49 may choke in other build contexts, this
50 lets you cleanly stop it being built
52 --enable-x-google-mux Enable experimental x-google-mux support
53 in the build (see notes later in document)
55 Testing server with a browser
56 -----------------------------
58 If you point your browser (eg, Chrome) to
62 It will fetch a script in the form of test.html, and then run the
63 script in there on the browser to open a websocket connection.
64 Incrementing numbers should appear in the browser display.
66 Using SSL on the server side
67 ----------------------------
69 To test it using SSL/WSS, just run the test server with
71 $ libwebsockets-test-server --ssl
75 https://127.0.0.1:7681
77 The connection will be entirely encrypted using some generated
78 certificates that your browser will not accept, since they are
79 not signed by any real Certificate Authority. Just accept the
80 certificates in the browser and the connection will proceed
81 in first https and then websocket wss, acting exactly the
84 test-server.c is all that is needed to use libwebsockets for
85 serving both the script html over http and websockets.
91 If your target device does not offer fork(), you can use
92 libwebsockets from your own main loop instead. Use the
93 configure option --nofork and simply call libwebsocket_service()
94 from your own main loop as shown in the test app sources.
97 Testing websocket client support
98 --------------------------------
100 If you run the test server as described above, you can also
101 connect to it using the test client as well as a browser.
103 $ libwebsockets-test-client localhost
105 will by default connect to the test server on localhost:7681
106 and print the dumb increment number from the server at the
107 same time as drawing random circles in the mirror protocol;
108 if you connect to the test server using a browser at the
109 same time you will be able to see the circles being drawn.
112 Testing SSL on the client side
113 ------------------------------
115 To test SSL/WSS client action, just run the client test with
117 $ libwebsockets-test-client localhost --ssl
119 By default the client test applet is set to accept selfsigned
120 certificates used by the test server, this is indicated by the
121 use_ssl var being set to 2. Set it to 1 to reject any server
122 certificate that it doesn't have a trusted CA cert for.
125 Using the websocket ping utility
126 --------------------------------
128 libwebsockets-test-ping connects as a client to a remote
129 websocket server using 04 protocol and pings it like the
130 normal unix ping utility.
132 $ libwebsockets-test-ping localhost
133 handshake OK for protocol lws-mirror-protocol
134 Websocket PING localhost.localdomain (127.0.0.1) 64 bytes of data.
135 64 bytes from localhost: req=1 time=0.1ms
136 64 bytes from localhost: req=2 time=0.1ms
137 64 bytes from localhost: req=3 time=0.1ms
138 64 bytes from localhost: req=4 time=0.2ms
139 64 bytes from localhost: req=5 time=0.1ms
140 64 bytes from localhost: req=6 time=0.2ms
141 64 bytes from localhost: req=7 time=0.2ms
142 64 bytes from localhost: req=8 time=0.1ms
144 --- localhost.localdomain websocket ping statistics ---
145 8 packets transmitted, 8 received, 0% packet loss, time 7458ms
146 rtt min/avg/max = 0.110/0.185/0.218 ms
149 By default it sends 64 byte payload packets using the 04
150 PING packet opcode type. You can change the payload size
151 using the -s= flag, up to a maximum of 125 mandated by the
154 Using the lws-mirror protocol that is provided by the test
155 server, libwebsockets-test-ping can also use larger payload
156 sizes up to 4096 is BINARY packets; lws-mirror will copy
157 them back to the client and they appear as a PONG. Use the
158 -m flag to select this operation.
160 The default interval between pings is 1s, you can use the -i=
161 flag to set this, including fractions like -i=0.01 for 10ms
164 Before you can even use the PING opcode that is part of the
165 standard, you must complete a handshake with a specified
166 protocol. By default lws-mirror-protocol is used which is
167 supported by the test server. But if you are using it on
168 another server, you can specify the protcol to handshake with
169 by --protocol=protocolname
175 By default it runs in server mode
177 $ libwebsockets-test-fraggle
178 libwebsockets test fraggle
179 (C) Copyright 2010-2011 Andy Green <andy@warmcat.com> licensed under LGPL2.1
180 Compiled with SSL support, not using it
181 Listening on port 7681
182 server sees client connect
183 accepted v06 connection
184 Spamming 360 random fragments
185 Spamming session over, len = 371913. sum = 0x2D3C0AE
186 Spamming 895 random fragments
187 Spamming session over, len = 875970. sum = 0x6A74DA1
190 You need to run a second session in client mode, you have to
191 give the -c switch and the server address at least:
193 $ libwebsockets-test-fraggle -c localhost
194 libwebsockets test fraggle
195 (C) Copyright 2010-2011 Andy Green <andy@warmcat.com> licensed under LGPL2.1
197 Connecting to localhost:7681
198 denied deflate-stream extension
199 handshake OK for protocol fraggle-protocol
200 client connects to server
201 EOM received 371913 correctly from 360 fragments
202 EOM received 875970 correctly from 895 fragments
203 EOM received 247140 correctly from 258 fragments
204 EOM received 695451 correctly from 692 fragments
207 The fraggle test sends a random number up to 1024 fragmented websocket frames
208 each of a random size between 1 and 2001 bytes in a single message, then sends
209 a checksum and starts sending a new randomly sized and fragmented message.
211 The fraggle test client receives the same message fragments and computes the
212 same checksum using websocket framing to see when the message has ended. It
213 then accepts the server checksum message and compares that to its checksum.
219 The http_proxy environment variable is respected by the client
220 connection code for both ws:// and wss://. It doesn't support
225 export http_proxy=myproxy.com:3128
226 libwebsockets-test-client someserver.com
229 Websocket version supported
230 ---------------------------
232 The websocket client code is 04 and 05 version, the server
233 supports 00/76 in text mode and 04 and 05 dynamically
234 per-connection depending on the version of the
238 External Polling Loop support
239 -----------------------------
241 libwebsockets maintains an internal poll() array for all of its
242 sockets, but you can instead integrate the sockets into an
243 external polling array. That's needed if libwebsockets will
244 cooperate with an existing poll array maintained by another
247 Four callbacks LWS_CALLBACK_ADD_POLL_FD, LWS_CALLBACK_DEL_POLL_FD,
248 LWS_CALLBACK_SET_MODE_POLL_FD and LWS_CALLBACK_CLEAR_MODE_POLL_FD
249 appear in the callback for protocol 0 and allow interface code to
250 manage socket descriptors in other poll loops.
256 Experimental and super-preliminary x-google-mux support is available if
257 enabled in ./configure with --enable-x-google-mux. Note that when changing
258 configurations, you will need to do a make distclean before, then the new
259 configure and then make ; make install. Don't forget the necessary other
260 flags for your platform as described at the top of the readme.
262 It has the following notes:
264 1) To enable it, reconfigure with --enable-x-google-mux
266 2) It conflicts with deflate-stream, use the -u switch on
267 the test client to disable deflate-stream
269 3) It deviates from the google standard by sending full
270 headers in the addchannel subcommand rather than just
271 changed ones from original connect
273 4) Quota is not implemented yet
275 5) Close of subchannel is not really implemented yet
277 6) Google opcode 0xf is changed to 0x7 to account for
278 v7 protocol changes to opcode layout
280 However despite those caveats, in fact it can run the
281 test client reliably over one socket (both dumb-increment
282 and lws-mirror-protocol), you can open a browser on the
283 same test server too and see the circles, etc.
286 2011-05-23 Andy Green <andy@warmcat.com>