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 otherwise if /usr/local/... and /usr/local/lib are OK then... $ ./configure --enable-openssl $ 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 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 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. 2011-02-12 Andy Green