forked from Mirrors/freeswitch
293 lines
9.6 KiB
Plaintext
293 lines
9.6 KiB
Plaintext
Using test-server as a quickstart
|
|
---------------------------------
|
|
|
|
You need to regenerate the autotools and libtoolize stuff for your system
|
|
|
|
$ autoreconf
|
|
$ libtoolize
|
|
|
|
Then 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>
|
|
|