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, they're pure JSON but # may be used to turn the rest of the line into a comment.
  19
  20 There is a single file intended for global settings
  21
  22 /etc/lwsws/conf
  23
  24 ```
  25 # these are the server global settings
  26 # stuff related to vhosts should go in one
  27 # file per vhost in ../conf.d/
  28
  29 {
  30   "global": {
  31    "uid": "48",  # apache user
  32    "gid": "48",  # apache user
  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                 "interface": "eth0",  # optional
  49                 "host-ssl-key": "/etc/pki/tls/private/warmcat.com.key",  # if given enable ssl
  50                 "host-ssl-cert": "/etc/pki/tls/certs/warmcat.com.crt",
  51                 "host-ssl-ca": "/etc/pki/tls/certs/warmcat.com.cer",
  52                 "mounts": [{  # autoserve
  53                         "mountpoint": "/",
  54                         "origin": "file:///var/www/warmcat.com",
  55                         "default": "index.html"
  56                 }]
  57         }]
  58 }
  59 ```
  60
  61 Vhosts
  62 ------
  63
  64 One server can run many vhosts, where SSL is in use SNI is used to match
  65 the connection to a vhost and its vhost-specific SSL keys during SSL
  66 negotiation.
  67
  68 Listing multiple vhosts looks something like this
  69
  70 ```
  71 {
  72  "vhosts": [ {
  73      "name": "localhost",
  74      "port": "443",
  75      "host-ssl-key":  "/etc/pki/tls/private/libwebsockets.org.key",
  76      "host-ssl-cert": "/etc/pki/tls/certs/libwebsockets.org.crt",
  77      "host-ssl-ca":   "/etc/pki/tls/certs/libwebsockets.org.cer",
  78      "mounts": [{
  79        "mountpoint": "/",
  80        "origin": "file:///var/www/libwebsockets.org",
  81        "default": "index.html"
  82        }, {
  83         "mountpoint": "/testserver",
  84         "origin": "file:///usr/local/share/libwebsockets-test-server",
  85         "default": "test.html"
  86        }],
  87      # which protocols are enabled for this vhost, and optional
  88      # vhost-specific config options for the protocol
  89      #
  90      "ws-protocols": [{
  91        "warmcat,timezoom": {
  92          "status": "ok"
  93        }
  94      }]
  95     },
  96     {
  97     "name": "localhost",
  98     "port": "7681",
  99      "host-ssl-key":  "/etc/pki/tls/private/libwebsockets.org.key",
 100      "host-ssl-cert": "/etc/pki/tls/certs/libwebsockets.org.crt",
 101      "host-ssl-ca":   "/etc/pki/tls/certs/libwebsockets.org.cer",
 102      "mounts": [{
 103        "mountpoint": "/",
 104        "origin": ">https://localhost"
 105      }]
 106    },
 107     {
 108     "name": "localhost",
 109     "port": "80",
 110      "mounts": [{
 111        "mountpoint": "/",
 112        "origin": ">https://localhost"
 113      }]
 114    }
 115
 116   ]
 117 }
 118 ```
 119
 120 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
 121
 122
 123 Vhost name and port
 124 -------------------
 125
 126 The vhost name field is used to match on incoming SNI or Host: header, so it
 127 must always be the host name used to reach the vhost externally.
 128
 129  - Vhosts may have the same name and different ports, these will each create a
 130 listening socket on the appropriate port.
 131
 132  - Vhosts may also have the same port and different name: these will be treated as
 133 true vhosts on one listening socket and the active vhost decided at SSL
 134 negotiation time (via SNI) or if no SSL, then after the Host: header from
 135 the client has been parsed.
 136
 137
 138 Protocols
 139 ---------
 140
 141 Vhosts by default have available the union of any initial protocols from context creation time, and
 142 any protocols exposed by plugins.
 143
 144 Vhosts can select which plugins they want to offer and give them per-vhost settings using this syntax
 145
 146 ```
 147      "ws-protocols": [{
 148        "warmcat,timezoom": {
 149          "status": "ok"
 150        }
 151      }]
 152
 153 ```
 154
 155 Other vhost options
 156 -------------------
 157
 158  - If the three options `host-ssl-cert`, `host-ssl-ca` and `host-ssl-key` are given, then the vhost supports SSL.
 159
 160  Each vhost may have its own certs, SNI is used during the initial connection negotiation to figure out which certs to use by the server name it's asking for from the request DNS name.
 161
 162  - `keeplive-timeout` (in secs) defaults to 60 for lwsws, it may be set as a vhost option
 163
 164  - `interface` lets you specify which network interface to listen on, if not given listens on all
 165
 166  - "`unix-socket`": "1" causes the unix socket specified in the interface option to be used instead of an INET socket
 167
 168  - "`sts`": "1" causes lwsws to send a Strict Transport Security header with responses that informs the client he should never accept to connect to this address using http.  This is needed to get the A+ security rating from SSL Labs for your server.
 169
 170  - "`access-log`": "filepath"   sets where apache-compatible access logs will be written
 171
 172 Mounts
 173 ------
 174
 175 Where mounts are given in the vhost definition, then directory contents may
 176 be auto-served if it matches the mountpoint.
 177
 178 Mount protocols are used to control what kind of translation happens
 179
 180  - file://  serve the uri using the remainder of the url past the mountpoint based on the origin directory.
 181
 182  Eg, with this mountpoint
 183
 184 ```
 185        {
 186         "mountpoint": "/",
 187         "origin": "file:///var/www/mysite.com",
 188         "default": "/"
 189        }
 190 ```
 191
 192  The uri /file.jpg would serve /var/www/mysite.com/file.jpg, since / matched.
 193
 194  - ^http:// or ^https://  these cause any url matching the mountpoint to issue a redirect to the origin url
 195
 196  - cgi://   this causes any matching url to be given to the named cgi, eg
 197
 198 ```
 199        {
 200         "mountpoint": "/git",
 201         "origin": "cgi:///var/www/cgi-bin/cgit",
 202         "default": "/"
 203        }, {
 204         "mountpoint": "/cgit-data",
 205         "origin": "file:///usr/share/cgit",
 206         "default": "/"
 207        },
 208 ```
 209
 210  would cause the url /git/myrepo to pass "myrepo" to the cgi /var/www/cgi-bin/cgit and send the results to the client.
 211
 212  When using a cgi:// protcol origin at a mountpoint, you may also give cgi environment variables specific to the mountpoint like this
 213
 214 ```
 215        {
 216         "mountpoint": "/git",
 217         "origin": "cgi:///var/www/cgi-bin/cgit",
 218         "default": "/",
 219         "cgi-env": [{
 220                 "CGIT_CONFIG": "/etc/cgitrc/libwebsockets.org"
 221         }]
 222        }
 223 ```
 224
 225  This allows you to customize one cgi depending on the mountpoint (and / or vhost).
 226
 227  It's also possible to set the cgi timeout (in secs) per cgi:// mount, like this
 228
 229 ```
 230         "cgi-timeout": "30"
 231 ```
 232
 233
 234 Note: currently only a fixed set of mimetypes are supported.
 235
 236
 237 Plugins
 238 -------
 239
 240 Protcols and extensions may also be provided from "plugins", these are
 241 lightweight dynamic libraries.  They are scanned for at init time, and
 242 any protocols and extensions found are added to the list given at context
 243 creation time.
 244
 245 Protocols receive init (LWS_CALLBACK_PROTOCOL_INIT) and destruction
 246 (LWS_CALLBACK_PROTOCOL_DESTROY) callbacks per-vhost, and there are arrangements
 247 they can make per-vhost allocations and get hold of the correct pointer from
 248 the wsi at the callback.
 249
 250 This allows a protocol to choose to strictly segregate data on a per-vhost
 251 basis, and also allows the plugin to handle its own initialization and
 252 context storage.
 253
 254 To help that happen conveniently, there are some new apis
 255
 256  - lws_vhost_get(wsi)
 257  - lws_protocol_get(wsi)
 258  - lws_callback_on_writable_all_protocol_vhost(vhost, protocol)
 259  - lws_protocol_vh_priv_zalloc(vhost, protocol, size)
 260  - lws_protocol_vh_priv_get(vhost, protocol)
 261
 262 dumb increment, mirror and status protocol plugins are provided as examples.
 263
 264
 265