README-test-server

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.

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.


Websocket version supported
---------------------------

The websocket client code is 04 version, the server supports
both 00/76 in text mode and 04 dynamically per-connection
depending on the version of the client / browser.

2011-01-22  Andy Green <andy@warmcat.com>