Andy Green | b214977 | 2010-10-31 13:15:56 +0000 | [diff] [blame] | 1 | Using test-server as a quickstart |
| 2 | --------------------------------- |
| 3 | |
Andy Green | a1e3ec0 | 2010-11-08 17:16:50 +0000 | [diff] [blame] | 4 | For a Fedora x86_86 box, the following config line was |
| 5 | needed: |
| 6 | |
Andy Green | 8c40415 | 2011-02-16 18:50:01 +0000 | [diff] [blame] | 7 | ./configure --prefix=/usr --libdir=/usr/lib64 --enable-openssl |
| 8 | |
Andy Green | a54986f | 2011-02-28 07:48:27 +0000 | [diff] [blame] | 9 | For Apple systems, Christopher Baker reported that this is needed |
| 10 | (and I was told separately enabling openssl makes trouble somehow) |
| 11 | |
| 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 |
| 14 | |
Andy Green | a1e3ec0 | 2010-11-08 17:16:50 +0000 | [diff] [blame] | 15 | |
| 16 | otherwise if /usr/local/... and /usr/local/lib are OK then... |
| 17 | |
Andy Green | 8c40415 | 2011-02-16 18:50:01 +0000 | [diff] [blame] | 18 | $ ./configure |
Andy Green | 9293b05 | 2011-01-23 17:53:54 +0000 | [diff] [blame] | 19 | $ make clean |
Andy Green | 05a0a7b | 2010-10-31 17:51:39 +0000 | [diff] [blame] | 20 | $ make |
Andy Green | 7310e9c | 2010-11-01 09:12:17 +0000 | [diff] [blame] | 21 | $ sudo make install |
| 22 | $ libwebsockets-test-server |
Andy Green | b214977 | 2010-10-31 13:15:56 +0000 | [diff] [blame] | 23 | |
| 24 | should be enough to get a test server listening on port 7861. |
| 25 | |
Andy Green | 9293b05 | 2011-01-23 17:53:54 +0000 | [diff] [blame] | 26 | There are a couple of other possible configure options |
| 27 | |
| 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. |
| 32 | |
| 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. |
| 42 | |
Andy Green | 90c7cbc | 2011-01-27 06:26:52 +0000 | [diff] [blame] | 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. |
| 46 | |
Andy Green | a6cbece | 2011-01-27 20:06:03 +0000 | [diff] [blame] | 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 |
Andy Green | a41314f | 2011-05-23 10:00:03 +0100 | [diff] [blame] | 51 | |
| 52 | --enable-x-google-mux Enable experimental x-google-mux support |
| 53 | in the build (see notes later in document) |
Andy Green | a6cbece | 2011-01-27 20:06:03 +0000 | [diff] [blame] | 54 | |
Andy Green | 4739e5c | 2011-01-22 12:51:57 +0000 | [diff] [blame] | 55 | Testing server with a browser |
| 56 | ----------------------------- |
Andy Green | ed11a02 | 2011-01-20 10:23:50 +0000 | [diff] [blame] | 57 | |
Andy Green | b214977 | 2010-10-31 13:15:56 +0000 | [diff] [blame] | 58 | If you point your browser (eg, Chrome) to |
| 59 | |
| 60 | http://127.0.0.1:7681 |
| 61 | |
Andy Green | 3c97469 | 2010-11-08 17:04:09 +0000 | [diff] [blame] | 62 | It will fetch a script in the form of test.html, and then run the |
Andy Green | 7310e9c | 2010-11-01 09:12:17 +0000 | [diff] [blame] | 63 | script in there on the browser to open a websocket connection. |
| 64 | Incrementing numbers should appear in the browser display. |
Andy Green | b214977 | 2010-10-31 13:15:56 +0000 | [diff] [blame] | 65 | |
Andy Green | 90c7cbc | 2011-01-27 06:26:52 +0000 | [diff] [blame] | 66 | Using SSL on the server side |
| 67 | ---------------------------- |
Andy Green | 4739e5c | 2011-01-22 12:51:57 +0000 | [diff] [blame] | 68 | |
Andy Green | 3c97469 | 2010-11-08 17:04:09 +0000 | [diff] [blame] | 69 | To test it using SSL/WSS, just run the test server with |
| 70 | |
| 71 | $ libwebsockets-test-server --ssl |
| 72 | |
| 73 | and use the URL |
| 74 | |
| 75 | https://127.0.0.1:7681 |
| 76 | |
| 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 |
| 82 | same. |
| 83 | |
Andy Green | b214977 | 2010-10-31 13:15:56 +0000 | [diff] [blame] | 84 | test-server.c is all that is needed to use libwebsockets for |
| 85 | serving both the script html over http and websockets. |
| 86 | |
Andy Green | 90c7cbc | 2011-01-27 06:26:52 +0000 | [diff] [blame] | 87 | |
Andy Green | ed11a02 | 2011-01-20 10:23:50 +0000 | [diff] [blame] | 88 | Forkless operation |
| 89 | ------------------ |
| 90 | |
| 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. |
| 95 | |
Andy Green | 90c7cbc | 2011-01-27 06:26:52 +0000 | [diff] [blame] | 96 | |
Andy Green | 4739e5c | 2011-01-22 12:51:57 +0000 | [diff] [blame] | 97 | Testing websocket client support |
| 98 | -------------------------------- |
| 99 | |
| 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. |
| 102 | |
| 103 | $ libwebsockets-test-client localhost |
| 104 | |
| 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. |
| 110 | |
Andy Green | ed11a02 | 2011-01-20 10:23:50 +0000 | [diff] [blame] | 111 | |
Andy Green | 90c7cbc | 2011-01-27 06:26:52 +0000 | [diff] [blame] | 112 | Testing SSL on the client side |
| 113 | ------------------------------ |
| 114 | |
| 115 | To test SSL/WSS client action, just run the client test with |
| 116 | |
| 117 | $ libwebsockets-test-client localhost --ssl |
| 118 | |
| 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. |
| 123 | |
| 124 | |
Andy Green | a6cbece | 2011-01-27 20:06:03 +0000 | [diff] [blame] | 125 | Using the websocket ping utility |
| 126 | -------------------------------- |
| 127 | |
| 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. |
| 131 | |
| 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 |
| 143 | ^C |
| 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 |
| 147 | $ |
| 148 | |
| 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 |
| 152 | 04 standard. |
| 153 | |
| 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. |
| 159 | |
| 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 |
| 162 | interval. |
| 163 | |
| 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 |
| 170 | |
| 171 | |
Andy Green | 98a623f | 2011-03-08 08:43:59 +0000 | [diff] [blame] | 172 | Fraggle test app |
| 173 | ---------------- |
| 174 | |
| 175 | By default it runs in server mode |
| 176 | |
| 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 |
| 188 | ... |
| 189 | |
| 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: |
| 192 | |
| 193 | $ libwebsockets-test-fraggle -c localhost |
| 194 | libwebsockets test fraggle |
| 195 | (C) Copyright 2010-2011 Andy Green <andy@warmcat.com> licensed under LGPL2.1 |
| 196 | Client mode |
| 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 |
| 205 | ... |
| 206 | |
| 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. |
| 210 | |
| 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. |
| 214 | |
| 215 | |
Andy Green | 9659f37 | 2011-01-27 22:01:43 +0000 | [diff] [blame] | 216 | proxy support |
| 217 | ------------- |
| 218 | |
| 219 | The http_proxy environment variable is respected by the client |
| 220 | connection code for both ws:// and wss://. It doesn't support |
| 221 | authentication yet. |
| 222 | |
| 223 | You use it like this |
| 224 | |
| 225 | export http_proxy=myproxy.com:3128 |
| 226 | libwebsockets-test-client someserver.com |
| 227 | |
| 228 | |
Andy Green | ed11a02 | 2011-01-20 10:23:50 +0000 | [diff] [blame] | 229 | Websocket version supported |
| 230 | --------------------------- |
| 231 | |
Andy Green | e7981dc | 2011-02-12 21:24:03 +0000 | [diff] [blame] | 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 |
| 235 | client / browser. |
Andy Green | ed11a02 | 2011-01-20 10:23:50 +0000 | [diff] [blame] | 236 | |
Andy Green | e7981dc | 2011-02-12 21:24:03 +0000 | [diff] [blame] | 237 | |
| 238 | External Polling Loop support |
| 239 | ----------------------------- |
| 240 | |
| 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 |
| 245 | server. |
| 246 | |
| 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. |
| 251 | |
Andy Green | a41314f | 2011-05-23 10:00:03 +0100 | [diff] [blame] | 252 | |
| 253 | x-google-mux support |
| 254 | -------------------- |
| 255 | |
| 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. |
| 261 | |
| 262 | It has the following notes: |
| 263 | |
| 264 | 1) To enable it, reconfigure with --enable-x-google-mux |
| 265 | |
| 266 | 2) It conflicts with deflate-stream, use the -u switch on |
| 267 | the test client to disable deflate-stream |
| 268 | |
| 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 |
| 272 | |
| 273 | 4) Quota is not implemented yet |
| 274 | |
| 275 | 5) Close of subchannel is not really implemented yet |
| 276 | |
| 277 | 6) Google opcode 0xf is changed to 0x7 to account for |
| 278 | v7 protocol changes to opcode layout |
| 279 | |
| 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. |
| 284 | |
| 285 | |
| 286 | 2011-05-23 Andy Green <andy@warmcat.com> |
Andy Green | b214977 | 2010-10-31 13:15:56 +0000 | [diff] [blame] | 287 | |