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