README-test-server

   1 Using test-server as a quickstart
   2 ---------------------------------
   3
   4 For a Fedora x86_86 box, the following config line was
   5 needed:
   6
   7  ./configure --prefix=/usr --libdir=/usr/lib64 --enable-openssl
   8
   9 For Apple systems, in addition to whatever other typical
  10 configure magic you need, you will also need --enable-nofork and
  11 it seems don't enable openssl.
  12
  13 otherwise if /usr/local/... and /usr/local/lib are OK then...
  14
  15 $ ./configure
  16 $ make clean
  17 $ make
  18 $ sudo make install
  19 $ libwebsockets-test-server
  20
  21 should be enough to get a test server listening on port 7861.
  22
  23 There are a couple of other possible configure options
  24
  25 --enable-nofork         disables the fork into the background API
  26                         and removes all references to fork() and
  27                         pr_ctl() from the sources.  Use it if your
  28                         platform doesn't support forking.
  29
  30 --enable-libcrypto      by default libwebsockets uses its own
  31                         built-in md5 and sha-1 implementation for
  32                         simplicity.  However the libcrypto ones
  33                         may be faster, and in a distro context it
  34                         may be highly desirable to use a common
  35                         library implementation for ease of security
  36                         upgrades.  Give this configure option
  37                         to disable the built-in ones and force use
  38                         of the libcrypto (part of openssl) ones.
  39
  40 --with-client-cert-dir=dir   tells the client ssl support where to
  41                              look for trust certificates to validate
  42                              the remote certificate against.
  43
  44 --enable-noping         Don't try to build the ping test app
  45                         It needs some unixy environment that
  46                         may choke in other build contexts, this
  47                         lets you cleanly stop it being built
  48
  49 Testing server with a browser
  50 -----------------------------
  51
  52 If you point your browser (eg, Chrome) to
  53
  54   http://127.0.0.1:7681
  55
  56 It will fetch a script in the form of test.html, and then run the
  57 script in there on the browser to open a websocket connection.
  58 Incrementing numbers should appear in the browser display.
  59
  60 Using SSL on the server side
  61 ----------------------------
  62
  63 To test it using SSL/WSS, just run the test server with
  64
  65 $ libwebsockets-test-server --ssl
  66
  67 and use the URL
  68
  69   https://127.0.0.1:7681
  70
  71 The connection will be entirely encrypted using some generated
  72 certificates that your browser will not accept, since they are
  73 not signed by any real Certificate Authority.  Just accept the
  74 certificates in the browser and the connection will proceed
  75 in first https and then websocket wss, acting exactly the
  76 same.
  77
  78 test-server.c is all that is needed to use libwebsockets for
  79 serving both the script html over http and websockets.
  80
  81
  82 Forkless operation
  83 ------------------
  84
  85 If your target device does not offer fork(), you can use
  86 libwebsockets from your own main loop instead.  Use the
  87 configure option --nofork and simply call libwebsocket_service()
  88 from your own main loop as shown in the test app sources.
  89
  90
  91 Testing websocket client support
  92 --------------------------------
  93
  94 If you run the test server as described above, you can also
  95 connect to it using the test client as well as a browser.
  96
  97 $ libwebsockets-test-client localhost
  98
  99 will by default connect to the test server on localhost:7681
 100 and print the dumb increment number from the server at the
 101 same time as drawing random circles in the mirror protocol;
 102 if you connect to the test server using a browser at the
 103 same time you will be able to see the circles being drawn.
 104
 105
 106 Testing SSL on the client side
 107 ------------------------------
 108
 109 To test SSL/WSS client action, just run the client test with
 110
 111 $ libwebsockets-test-client localhost --ssl
 112
 113 By default the client test applet is set to accept selfsigned
 114 certificates used by the test server, this is indicated by the
 115 use_ssl var being set to 2.  Set it to 1 to reject any server
 116 certificate that it doesn't have a trusted CA cert for.
 117
 118
 119 Using the websocket ping utility
 120 --------------------------------
 121
 122 libwebsockets-test-ping connects as a client to a remote
 123 websocket server using 04 protocol and pings it like the
 124 normal unix ping utility.
 125
 126 $ libwebsockets-test-ping localhost
 127 handshake OK for protocol lws-mirror-protocol
 128 Websocket PING localhost.localdomain (127.0.0.1) 64 bytes of data.
 129 64 bytes from localhost: req=1 time=0.1ms
 130 64 bytes from localhost: req=2 time=0.1ms
 131 64 bytes from localhost: req=3 time=0.1ms
 132 64 bytes from localhost: req=4 time=0.2ms
 133 64 bytes from localhost: req=5 time=0.1ms
 134 64 bytes from localhost: req=6 time=0.2ms
 135 64 bytes from localhost: req=7 time=0.2ms
 136 64 bytes from localhost: req=8 time=0.1ms
 137 ^C
 138 --- localhost.localdomain websocket ping statistics ---
 139 8 packets transmitted, 8 received, 0% packet loss, time 7458ms
 140 rtt min/avg/max = 0.110/0.185/0.218 ms
 141 $
 142
 143 By default it sends 64 byte payload packets using the 04
 144 PING packet opcode type.  You can change the payload size
 145 using the -s= flag, up to a maximum of 125 mandated by the
 146 04 standard.
 147
 148 Using the lws-mirror protocol that is provided by the test
 149 server, libwebsockets-test-ping can also use larger payload
 150 sizes up to 4096 is BINARY packets; lws-mirror will copy
 151 them back to the client and they appear as a PONG.  Use the
 152 -m flag to select this operation.
 153
 154 The default interval between pings is 1s, you can use the -i=
 155 flag to set this, including fractions like -i=0.01 for 10ms
 156 interval.
 157
 158 Before you can even use the PING opcode that is part of the
 159 standard, you must complete a handshake with a specified
 160 protocol.  By default lws-mirror-protocol is used which is
 161 supported by the test server.  But if you are using it on
 162 another server, you can specify the protcol to handshake with
 163 by --protocol=protocolname
 164
 165
 166 proxy support
 167 -------------
 168
 169 The http_proxy environment variable is respected by the client
 170 connection code for both ws:// and wss://.  It doesn't support
 171 authentication yet.
 172
 173 You use it like this
 174
 175 export http_proxy=myproxy.com:3128
 176 libwebsockets-test-client someserver.com
 177
 178
 179 Websocket version supported
 180 ---------------------------
 181
 182 The websocket client code is 04 and 05 version, the server
 183 supports 00/76 in text mode and 04 and 05 dynamically
 184 per-connection depending on the version of the
 185 client / browser.
 186
 187
 188 External Polling Loop support
 189 -----------------------------
 190
 191 libwebsockets maintains an internal poll() array for all of its
 192 sockets, but you can instead integrate the sockets into an
 193 external polling array.  That's needed if libwebsockets will
 194 cooperate with an existing poll array maintained by another
 195 server.
 196
 197 Four callbacks LWS_CALLBACK_ADD_POLL_FD, LWS_CALLBACK_DEL_POLL_FD,
 198 LWS_CALLBACK_SET_MODE_POLL_FD and LWS_CALLBACK_CLEAR_MODE_POLL_FD
 199 appear in the callback for protocol 0 and allow interface code to
 200 manage socket descriptors in other poll loops.
 201
 202 2011-02-12  Andy Green <andy@warmcat.com>
 203