README.lwsws.md

   1 Libwebsockets Web Server
   2 ------------------------
   3
   4 lwsws is an implementation of a very lightweight, ws-capable generic web
   5 server, which uses libwebsockets to implement everything underneath.
   6
   7 Build
   8 -----
   9
  10 Just enable -DLWS_WITH_LWSWS=1 at cmake-time.
  11
  12 It enables libuv and plugin support automatically.
  13
  14
  15 Configuration
  16 -------------
  17
  18 lwsws uses JSON config files, there is a single file intended for global
  19 settings
  20
  21 /etc/lwsws/conf
  22
  23 ```
  24 # these are the server global settings
  25 # stuff related to vhosts should go in one
  26 # file per vhost in ../conf.d/
  27
  28 {
  29   "global": {
  30    "uid": "99",
  31    "gid": "99",
  32    "interface": "eth0",
  33    "count-threads": "1",
  34    "init-ssl": "yes"
  35  }
  36 }
  37 ```
  38
  39 and a config directory intended to take one file per vhost
  40
  41 /etc/lwsws/conf.d/warmcat.com
  42
  43 ```
  44 {
  45         "vhosts": [{
  46                 "name": "warmcat.com",
  47                 "port": "443",
  48                 "host-ssl-key": "/etc/pki/tls/private/warmcat.com.key",
  49                 "host-ssl-cert": "/etc/pki/tls/certs/warmcat.com.crt",
  50                 "host-ssl-ca": "/etc/pki/tls/certs/warmcat.com.cer",
  51                 "mounts": [{
  52                         "mountpoint": "/",
  53                         "origin": "file:///var/www/warmcat.com",
  54                         "default": "index.html"
  55                 }]
  56         }]
  57 }
  58 ```
  59
  60 Vhosts
  61 ------
  62
  63 One server can run many vhosts, where SSL is in use SNI is used to match
  64 the connection to a vhost and its vhost-specific SSL keys during SSL
  65 negotiation.
  66
  67 Listing multiple vhosts looks something like this
  68
  69 ```
  70 {
  71  "vhosts": [ {
  72      "name": "localhost",
  73      "port": "443",
  74      "host-ssl-key":  "/etc/pki/tls/private/libwebsockets.org.key",
  75      "host-ssl-cert": "/etc/pki/tls/certs/libwebsockets.org.crt",
  76      "host-ssl-ca":   "/etc/pki/tls/certs/libwebsockets.org.cer",
  77      "mounts": [{
  78        "mountpoint": "/",
  79        "origin": "file:///var/www/libwebsockets.org",
  80        "default": "index.html"
  81        }, {
  82         "mountpoint": "/testserver",
  83         "origin": "file:///usr/local/share/libwebsockets-test-server",
  84         "default": "test.html"
  85        }],
  86      # which protocols are enabled for this vhost, and optional
  87      # vhost-specific config options for the protocol
  88      #
  89      "ws-protocols": [{
  90        "warmcat,timezoom": {
  91          "status": "ok"
  92        }
  93      }]
  94     },
  95     {
  96     "name": "localhost",
  97     "port": "7681",
  98      "host-ssl-key":  "/etc/pki/tls/private/libwebsockets.org.key",
  99      "host-ssl-cert": "/etc/pki/tls/certs/libwebsockets.org.crt",
 100      "host-ssl-ca":   "/etc/pki/tls/certs/libwebsockets.org.cer",
 101      "mounts": [{
 102        "mountpoint": "/",
 103        "origin": ">https://localhost"
 104      }]
 105    },
 106     {
 107     "name": "localhost",
 108     "port": "80",
 109      "mounts": [{
 110        "mountpoint": "/",
 111        "origin": ">https://localhost"
 112      }]
 113    }
 114
 115   ]
 116 }
 117 ```
 118
 119 That sets up three vhosts all called "localhost" on ports 443 and 7681 with SSL, and port 80 without SSL but with a forced redirect to https://localhost
 120
 121
 122 Vhost name and port
 123 -------------------
 124
 125 The vhost name field is used to match on incoming SNI or Host: header, so it
 126 must always be the host name used to reach the vhost externally.
 127
 128  - Vhosts may have the same name and different ports, these will each create a
 129 listening socket on the appropriate port.
 130
 131  - Vhosts may also have the same port and different name: these will be treated as
 132 true vhosts on one listening socket and the active vhost decided at SSL
 133 negotiation time (via SNI) or if no SSL, then after the Host: header from
 134 the client has been parsed.
 135
 136
 137 Mounts
 138 ------
 139
 140 Where mounts are given in the vhost definition, then directory contents may
 141 be auto-served if it matches the mountpoint.
 142
 143 Currently only file:// mount protocol and a fixed set of mimetypes are
 144 supported.
 145
 146
 147 Plugins
 148 -------
 149
 150 Protcols and extensions may also be provided from "plugins", these are
 151 lightweight dynamic libraries.  They are scanned for at init time, and
 152 any protocols and extensions found are added to the list given at context
 153 creation time.
 154
 155 Protocols receive init (LWS_CALLBACK_PROTOCOL_INIT) and destruction
 156 (LWS_CALLBACK_PROTOCOL_DESTROY) callbacks per-vhost, and there are arrangements
 157 they can make per-vhost allocations and get hold of the correct pointer from
 158 the wsi at the callback.
 159
 160 This allows a protocol to choose to strictly segregate data on a per-vhost
 161 basis, and also allows the plugin to handle its own initialization and
 162 context storage.
 163
 164 To help that happen conveniently, there are some new apis
 165
 166  - lws_vhost_get(wsi)
 167  - lws_protocol_get(wsi)
 168  - lws_callback_on_writable_all_protocol_vhost(vhost, protocol)
 169  - lws_protocol_vh_priv_zalloc(vhost, protocol, size)
 170  - lws_protocol_vh_priv_get(vhost, protocol)
 171
 172 dumb increment, mirror and status protocol plugins are provided as examples.
 173
 174
 175 Protocols
 176 ---------
 177
 178 Vhosts by default have available the union of any initial protocols from context creation time, and
 179 any protocols exposed by plugins.
 180
 181 Vhosts can select which plugins they want to offer and give them per-vhost settings using this syntax
 182
 183 ```
 184      "ws-protocols": [{
 185        "warmcat,timezoom": {
 186          "status": "ok"
 187        }
 188      }]
 189
 190 ```
 191