README-test-server - platform/external/libwebsockets - Git at Google

 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, in addition to whatever other typical
 configure magic you need, you will also need --enable-nofork and
 it seems don't enable openssl.

 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

 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 <andy@warmcat.com>
	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, in addition to whatever other typical
	configure magic you need, you will also need --enable-nofork and
	it seems don't enable openssl.

	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

	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 <andy@warmcat.com>