| Using test-server as a quickstart |
| --------------------------------- |
| |
| For a Fedora x86_86 box, the following config line was |
| needed: |
| |
| ./configure --prefix=/usr --libdir=/usr/lib64 --enable-openssl |
| |
| For Apple systems, Christopher Baker reported that this is needed |
| (and I was told separately enabling openssl makes trouble somehow) |
| |
| ./configure CC="gcc -arch i386 -arch x86_64" CXX="g++ -arch i386 -arch |
| x86_64" CPP="gcc -E" CXXCPP="g++ -E" --enable-nofork |
| |
| For mingw build, I did the following to get working build, ping test is |
| disabled when building this way |
| |
| 1) install mingw64_w32 compiler packages from Fedora |
| 2) additionally install mingw64-zlib package |
| 3) ./configure --prefix=/usr --enable-mingw --host=x86_64-w64-mingw32 |
| 4) make |
| |
| otherwise if /usr/local/... and /usr/local/lib are OK then... |
| |
| $ ./configure |
| $ make clean |
| $ make |
| $ sudo make install |
| $ libwebsockets-test-server |
| |
| should be enough to get a test server listening on port 7861. |
| |
| There are a couple of other possible configure options |
| |
| --enable-nofork disables the fork into the background API |
| and removes all references to fork() and |
| pr_ctl() from the sources. Use it if your |
| platform doesn't support forking. |
| |
| --enable-libcrypto by default libwebsockets uses its own |
| built-in md5 and sha-1 implementation for |
| simplicity. However the libcrypto ones |
| may be faster, and in a distro context it |
| may be highly desirable to use a common |
| library implementation for ease of security |
| upgrades. Give this configure option |
| to disable the built-in ones and force use |
| of the libcrypto (part of openssl) ones. |
| |
| --with-client-cert-dir=dir tells the client ssl support where to |
| look for trust certificates to validate |
| the remote certificate against. |
| |
| --enable-noping Don't try to build the ping test app |
| It needs some unixy environment that |
| may choke in other build contexts, this |
| lets you cleanly stop it being built |
| |
| --enable-x-google-mux Enable experimental x-google-mux support |
| in the build (see notes later in document) |
| |
| Testing server with a browser |
| ----------------------------- |
| |
| If you point your browser (eg, Chrome) to |
| |
| http://127.0.0.1:7681 |
| |
| It will fetch a script in the form of test.html, and then run the |
| script in there on the browser to open a websocket connection. |
| Incrementing numbers should appear in the browser display. |
| |
| Using SSL on the server side |
| ---------------------------- |
| |
| To test it using SSL/WSS, just run the test server with |
| |
| $ libwebsockets-test-server --ssl |
| |
| and use the URL |
| |
| https://127.0.0.1:7681 |
| |
| The connection will be entirely encrypted using some generated |
| certificates that your browser will not accept, since they are |
| not signed by any real Certificate Authority. Just accept the |
| certificates in the browser and the connection will proceed |
| in first https and then websocket wss, acting exactly the |
| same. |
| |
| test-server.c is all that is needed to use libwebsockets for |
| serving both the script html over http and websockets. |
| |
| |
| Forkless operation |
| ------------------ |
| |
| If your target device does not offer fork(), you can use |
| libwebsockets from your own main loop instead. Use the |
| configure option --nofork and simply call libwebsocket_service() |
| from your own main loop as shown in the test app sources. |
| |
| |
| Testing websocket client support |
| -------------------------------- |
| |
| If you run the test server as described above, you can also |
| connect to it using the test client as well as a browser. |
| |
| $ libwebsockets-test-client localhost |
| |
| will by default connect to the test server on localhost:7681 |
| and print the dumb increment number from the server at the |
| same time as drawing random circles in the mirror protocol; |
| if you connect to the test server using a browser at the |
| same time you will be able to see the circles being drawn. |
| |
| |
| Testing SSL on the client side |
| ------------------------------ |
| |
| To test SSL/WSS client action, just run the client test with |
| |
| $ libwebsockets-test-client localhost --ssl |
| |
| By default the client test applet is set to accept selfsigned |
| certificates used by the test server, this is indicated by the |
| use_ssl var being set to 2. Set it to 1 to reject any server |
| certificate that it doesn't have a trusted CA cert for. |
| |
| |
| Using the websocket ping utility |
| -------------------------------- |
| |
| libwebsockets-test-ping connects as a client to a remote |
| websocket server using 04 protocol and pings it like the |
| normal unix ping utility. |
| |
| $ libwebsockets-test-ping localhost |
| handshake OK for protocol lws-mirror-protocol |
| Websocket PING localhost.localdomain (127.0.0.1) 64 bytes of data. |
| 64 bytes from localhost: req=1 time=0.1ms |
| 64 bytes from localhost: req=2 time=0.1ms |
| 64 bytes from localhost: req=3 time=0.1ms |
| 64 bytes from localhost: req=4 time=0.2ms |
| 64 bytes from localhost: req=5 time=0.1ms |
| 64 bytes from localhost: req=6 time=0.2ms |
| 64 bytes from localhost: req=7 time=0.2ms |
| 64 bytes from localhost: req=8 time=0.1ms |
| ^C |
| --- localhost.localdomain websocket ping statistics --- |
| 8 packets transmitted, 8 received, 0% packet loss, time 7458ms |
| rtt min/avg/max = 0.110/0.185/0.218 ms |
| $ |
| |
| By default it sends 64 byte payload packets using the 04 |
| PING packet opcode type. You can change the payload size |
| using the -s= flag, up to a maximum of 125 mandated by the |
| 04 standard. |
| |
| Using the lws-mirror protocol that is provided by the test |
| server, libwebsockets-test-ping can also use larger payload |
| sizes up to 4096 is BINARY packets; lws-mirror will copy |
| them back to the client and they appear as a PONG. Use the |
| -m flag to select this operation. |
| |
| The default interval between pings is 1s, you can use the -i= |
| flag to set this, including fractions like -i=0.01 for 10ms |
| interval. |
| |
| Before you can even use the PING opcode that is part of the |
| standard, you must complete a handshake with a specified |
| protocol. By default lws-mirror-protocol is used which is |
| supported by the test server. But if you are using it on |
| another server, you can specify the protcol to handshake with |
| by --protocol=protocolname |
| |
| |
| Fraggle test app |
| ---------------- |
| |
| By default it runs in server mode |
| |
| $ libwebsockets-test-fraggle |
| libwebsockets test fraggle |
| (C) Copyright 2010-2011 Andy Green <andy@warmcat.com> licensed under LGPL2.1 |
| Compiled with SSL support, not using it |
| Listening on port 7681 |
| server sees client connect |
| accepted v06 connection |
| Spamming 360 random fragments |
| Spamming session over, len = 371913. sum = 0x2D3C0AE |
| Spamming 895 random fragments |
| Spamming session over, len = 875970. sum = 0x6A74DA1 |
| ... |
| |
| You need to run a second session in client mode, you have to |
| give the -c switch and the server address at least: |
| |
| $ libwebsockets-test-fraggle -c localhost |
| libwebsockets test fraggle |
| (C) Copyright 2010-2011 Andy Green <andy@warmcat.com> licensed under LGPL2.1 |
| Client mode |
| Connecting to localhost:7681 |
| denied deflate-stream extension |
| handshake OK for protocol fraggle-protocol |
| client connects to server |
| EOM received 371913 correctly from 360 fragments |
| EOM received 875970 correctly from 895 fragments |
| EOM received 247140 correctly from 258 fragments |
| EOM received 695451 correctly from 692 fragments |
| ... |
| |
| The fraggle test sends a random number up to 1024 fragmented websocket frames |
| each of a random size between 1 and 2001 bytes in a single message, then sends |
| a checksum and starts sending a new randomly sized and fragmented message. |
| |
| The fraggle test client receives the same message fragments and computes the |
| same checksum using websocket framing to see when the message has ended. It |
| then accepts the server checksum message and compares that to its checksum. |
| |
| |
| proxy support |
| ------------- |
| |
| The http_proxy environment variable is respected by the client |
| connection code for both ws:// and wss://. It doesn't support |
| authentication yet. |
| |
| You use it like this |
| |
| export http_proxy=myproxy.com:3128 |
| libwebsockets-test-client someserver.com |
| |
| |
| Websocket version supported |
| --------------------------- |
| |
| The websocket client code is 04 and 05 version, the server |
| supports 00/76 in text mode and 04 and 05 dynamically |
| per-connection depending on the version of the |
| client / browser. |
| |
| |
| External Polling Loop support |
| ----------------------------- |
| |
| libwebsockets maintains an internal poll() array for all of its |
| sockets, but you can instead integrate the sockets into an |
| external polling array. That's needed if libwebsockets will |
| cooperate with an existing poll array maintained by another |
| server. |
| |
| Four callbacks LWS_CALLBACK_ADD_POLL_FD, LWS_CALLBACK_DEL_POLL_FD, |
| LWS_CALLBACK_SET_MODE_POLL_FD and LWS_CALLBACK_CLEAR_MODE_POLL_FD |
| appear in the callback for protocol 0 and allow interface code to |
| manage socket descriptors in other poll loops. |
| |
| |
| x-google-mux support |
| -------------------- |
| |
| Experimental and super-preliminary x-google-mux support is available if |
| enabled in ./configure with --enable-x-google-mux. Note that when changing |
| configurations, you will need to do a make distclean before, then the new |
| configure and then make ; make install. Don't forget the necessary other |
| flags for your platform as described at the top of the readme. |
| |
| It has the following notes: |
| |
| 1) To enable it, reconfigure with --enable-x-google-mux |
| |
| 2) It deviates from the google standard by sending full |
| headers in the addchannel subcommand rather than just |
| changed ones from original connect |
| |
| 3) Quota is not implemented yet |
| |
| However despite those caveats, in fact it can run the |
| test client reliably over one socket (both dumb-increment |
| and lws-mirror-protocol), you can open a browser on the |
| same test server too and see the circles, etc. |
| |
| It also works compatibly with deflate-stream automatically. |
| |
| 2012-04-12 Andy Green <andy@warmcat.com> |
| |