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, Christopher Baker reported that this is needed
  10 (and I was told separately enabling openssl makes trouble somehow)
  11
  12 ./configure CC="gcc -arch i386 -arch x86_64" CXX="g++ -arch i386 -arch
  13 x86_64" CPP="gcc -E" CXXCPP="g++ -E" --enable-nofork
  14
  15
  16 otherwise if /usr/local/... and /usr/local/lib are OK then...
  17
  18 $ ./configure
  19 $ make clean
  20 $ make
  21 $ sudo make install
  22 $ libwebsockets-test-server
  23
  24 should be enough to get a test server listening on port 7861.
  25
  26 There are a couple of other possible configure options
  27
  28 --enable-nofork         disables the fork into the background API
  29                         and removes all references to fork() and
  30                         pr_ctl() from the sources.  Use it if your
  31                         platform doesn't support forking.
  32
  33 --enable-libcrypto      by default libwebsockets uses its own
  34                         built-in md5 and sha-1 implementation for
  35                         simplicity.  However the libcrypto ones
  36                         may be faster, and in a distro context it
  37                         may be highly desirable to use a common
  38                         library implementation for ease of security
  39                         upgrades.  Give this configure option
  40                         to disable the built-in ones and force use
  41                         of the libcrypto (part of openssl) ones.
  42
  43 --with-client-cert-dir=dir   tells the client ssl support where to
  44                              look for trust certificates to validate
  45                              the remote certificate against.
  46
  47 --enable-noping         Don't try to build the ping test app
  48                         It needs some unixy environment that
  49                         may choke in other build contexts, this
  50                         lets you cleanly stop it being built
  51
  52 --enable-x-google-mux   Enable experimental x-google-mux support
  53                         in the build (see notes later in document)
  54
  55 Testing server with a browser
  56 -----------------------------
  57
  58 If you point your browser (eg, Chrome) to
  59
  60   http://127.0.0.1:7681
  61
  62 It will fetch a script in the form of test.html, and then run the
  63 script in there on the browser to open a websocket connection.
  64 Incrementing numbers should appear in the browser display.
  65
  66 Using SSL on the server side
  67 ----------------------------
  68
  69 To test it using SSL/WSS, just run the test server with
  70
  71 $ libwebsockets-test-server --ssl
  72
  73 and use the URL
  74
  75   https://127.0.0.1:7681
  76
  77 The connection will be entirely encrypted using some generated
  78 certificates that your browser will not accept, since they are
  79 not signed by any real Certificate Authority.  Just accept the
  80 certificates in the browser and the connection will proceed
  81 in first https and then websocket wss, acting exactly the
  82 same.
  83
  84 test-server.c is all that is needed to use libwebsockets for
  85 serving both the script html over http and websockets.
  86
  87
  88 Forkless operation
  89 ------------------
  90
  91 If your target device does not offer fork(), you can use
  92 libwebsockets from your own main loop instead.  Use the
  93 configure option --nofork and simply call libwebsocket_service()
  94 from your own main loop as shown in the test app sources.
  95
  96
  97 Testing websocket client support
  98 --------------------------------
  99
 100 If you run the test server as described above, you can also
 101 connect to it using the test client as well as a browser.
 102
 103 $ libwebsockets-test-client localhost
 104
 105 will by default connect to the test server on localhost:7681
 106 and print the dumb increment number from the server at the
 107 same time as drawing random circles in the mirror protocol;
 108 if you connect to the test server using a browser at the
 109 same time you will be able to see the circles being drawn.
 110
 111
 112 Testing SSL on the client side
 113 ------------------------------
 114
 115 To test SSL/WSS client action, just run the client test with
 116
 117 $ libwebsockets-test-client localhost --ssl
 118
 119 By default the client test applet is set to accept selfsigned
 120 certificates used by the test server, this is indicated by the
 121 use_ssl var being set to 2.  Set it to 1 to reject any server
 122 certificate that it doesn't have a trusted CA cert for.
 123
 124
 125 Using the websocket ping utility
 126 --------------------------------
 127
 128 libwebsockets-test-ping connects as a client to a remote
 129 websocket server using 04 protocol and pings it like the
 130 normal unix ping utility.
 131
 132 $ libwebsockets-test-ping localhost
 133 handshake OK for protocol lws-mirror-protocol
 134 Websocket PING localhost.localdomain (127.0.0.1) 64 bytes of data.
 135 64 bytes from localhost: req=1 time=0.1ms
 136 64 bytes from localhost: req=2 time=0.1ms
 137 64 bytes from localhost: req=3 time=0.1ms
 138 64 bytes from localhost: req=4 time=0.2ms
 139 64 bytes from localhost: req=5 time=0.1ms
 140 64 bytes from localhost: req=6 time=0.2ms
 141 64 bytes from localhost: req=7 time=0.2ms
 142 64 bytes from localhost: req=8 time=0.1ms
 143 ^C
 144 --- localhost.localdomain websocket ping statistics ---
 145 8 packets transmitted, 8 received, 0% packet loss, time 7458ms
 146 rtt min/avg/max = 0.110/0.185/0.218 ms
 147 $
 148
 149 By default it sends 64 byte payload packets using the 04
 150 PING packet opcode type.  You can change the payload size
 151 using the -s= flag, up to a maximum of 125 mandated by the
 152 04 standard.
 153
 154 Using the lws-mirror protocol that is provided by the test
 155 server, libwebsockets-test-ping can also use larger payload
 156 sizes up to 4096 is BINARY packets; lws-mirror will copy
 157 them back to the client and they appear as a PONG.  Use the
 158 -m flag to select this operation.
 159
 160 The default interval between pings is 1s, you can use the -i=
 161 flag to set this, including fractions like -i=0.01 for 10ms
 162 interval.
 163
 164 Before you can even use the PING opcode that is part of the
 165 standard, you must complete a handshake with a specified
 166 protocol.  By default lws-mirror-protocol is used which is
 167 supported by the test server.  But if you are using it on
 168 another server, you can specify the protcol to handshake with
 169 by --protocol=protocolname
 170
 171
 172 Fraggle test app
 173 ----------------
 174
 175 By default it runs in server mode
 176
 177 $ libwebsockets-test-fraggle
 178 libwebsockets test fraggle
 179 (C) Copyright 2010-2011 Andy Green <andy@warmcat.com> licensed under LGPL2.1
 180  Compiled with SSL support, not using it
 181  Listening on port 7681
 182 server sees client connect
 183 accepted v06 connection
 184 Spamming 360 random fragments
 185 Spamming session over, len = 371913. sum = 0x2D3C0AE
 186 Spamming 895 random fragments
 187 Spamming session over, len = 875970. sum = 0x6A74DA1
 188 ...
 189
 190 You need to run a second session in client mode, you have to
 191 give the -c switch and the server address at least:
 192
 193 $ libwebsockets-test-fraggle -c localhost
 194 libwebsockets test fraggle
 195 (C) Copyright 2010-2011 Andy Green <andy@warmcat.com> licensed under LGPL2.1
 196  Client mode
 197 Connecting to localhost:7681
 198 denied deflate-stream extension
 199 handshake OK for protocol fraggle-protocol
 200 client connects to server
 201 EOM received 371913 correctly from 360 fragments
 202 EOM received 875970 correctly from 895 fragments
 203 EOM received 247140 correctly from 258 fragments
 204 EOM received 695451 correctly from 692 fragments
 205 ...
 206
 207 The fraggle test sends a random number up to 1024 fragmented websocket frames
 208 each of a random size between 1 and 2001 bytes in a single message, then sends
 209 a checksum and starts sending a new randomly sized and fragmented message.
 210
 211 The fraggle test client receives the same message fragments and computes the
 212 same checksum using websocket framing to see when the message has ended.  It
 213 then accepts the server checksum message and compares that to its checksum.
 214
 215
 216 proxy support
 217 -------------
 218
 219 The http_proxy environment variable is respected by the client
 220 connection code for both ws:// and wss://.  It doesn't support
 221 authentication yet.
 222
 223 You use it like this
 224
 225 export http_proxy=myproxy.com:3128
 226 libwebsockets-test-client someserver.com
 227
 228
 229 Websocket version supported
 230 ---------------------------
 231
 232 The websocket client code is 04 and 05 version, the server
 233 supports 00/76 in text mode and 04 and 05 dynamically
 234 per-connection depending on the version of the
 235 client / browser.
 236
 237
 238 External Polling Loop support
 239 -----------------------------
 240
 241 libwebsockets maintains an internal poll() array for all of its
 242 sockets, but you can instead integrate the sockets into an
 243 external polling array.  That's needed if libwebsockets will
 244 cooperate with an existing poll array maintained by another
 245 server.
 246
 247 Four callbacks LWS_CALLBACK_ADD_POLL_FD, LWS_CALLBACK_DEL_POLL_FD,
 248 LWS_CALLBACK_SET_MODE_POLL_FD and LWS_CALLBACK_CLEAR_MODE_POLL_FD
 249 appear in the callback for protocol 0 and allow interface code to
 250 manage socket descriptors in other poll loops.
 251
 252
 253 x-google-mux support
 254 --------------------
 255
 256 Experimental and super-preliminary x-google-mux support is available if
 257 enabled in ./configure with --enable-x-google-mux.  Note that when changing
 258 configurations, you will need to do a make distclean before, then the new
 259 configure and then make ; make install.  Don't forget the necessary other
 260 flags for your platform as described at the top of the readme.
 261
 262 It has the following notes:
 263
 264     1) To enable it, reconfigure with --enable-x-google-mux
 265
 266     2) It conflicts with deflate-stream, use the -u switch on
 267        the test client to disable deflate-stream
 268
 269     3) It deviates from the google standard by sending full
 270        headers in the addchannel subcommand rather than just
 271        changed ones from original connect
 272
 273     4) Quota is not implemented yet
 274
 275     5) Close of subchannel is not really implemented yet
 276
 277     6) Google opcode 0xf is changed to 0x7 to account for
 278        v7 protocol changes to opcode layout
 279
 280     However despite those caveats, in fact it can run the
 281     test client reliably over one socket (both dumb-increment
 282     and lws-mirror-protocol), you can open a browser on the
 283     same test server too and see the circles, etc.
 284
 285
 286 2011-05-23  Andy Green <andy@warmcat.com>
 287