1 Libwebsockets Web Server
2 ------------------------
4 lwsws is an implementation of a very lightweight, ws-capable generic web
5 server, which uses libwebsockets to implement everything underneath.
10 Just enable -DLWS_WITH_LWSWS=1 at cmake-time.
12 It enables libuv and plugin support automatically.
18 lwsws uses JSON config files, they're pure JSON but # may be used to turn the rest of the line into a comment.
20 There is a single file intended for global settings
25 # these are the server global settings
26 # stuff related to vhosts should go in one
27 # file per vhost in ../conf.d/
31 "uid": "48", # apache user
32 "gid": "48", # apache user
34 "server-string": "myserver v1", # returned in http headers
40 and a config directory intended to take one file per vhost
42 /etc/lwsws/conf.d/warmcat.com
47 "name": "warmcat.com",
49 "interface": "eth0", # optional
50 "host-ssl-key": "/etc/pki/tls/private/warmcat.com.key", # if given enable ssl
51 "host-ssl-cert": "/etc/pki/tls/certs/warmcat.com.crt",
52 "host-ssl-ca": "/etc/pki/tls/certs/warmcat.com.cer",
53 "mounts": [{ # autoserve
55 "origin": "file:///var/www/warmcat.com",
56 "default": "index.html"
65 One server can run many vhosts, where SSL is in use SNI is used to match
66 the connection to a vhost and its vhost-specific SSL keys during SSL
69 Listing multiple vhosts looks something like this
76 "host-ssl-key": "/etc/pki/tls/private/libwebsockets.org.key",
77 "host-ssl-cert": "/etc/pki/tls/certs/libwebsockets.org.crt",
78 "host-ssl-ca": "/etc/pki/tls/certs/libwebsockets.org.cer",
81 "origin": "file:///var/www/libwebsockets.org",
82 "default": "index.html"
84 "mountpoint": "/testserver",
85 "origin": "file:///usr/local/share/libwebsockets-test-server",
86 "default": "test.html"
88 # which protocols are enabled for this vhost, and optional
89 # vhost-specific config options for the protocol
100 "host-ssl-key": "/etc/pki/tls/private/libwebsockets.org.key",
101 "host-ssl-cert": "/etc/pki/tls/certs/libwebsockets.org.crt",
102 "host-ssl-ca": "/etc/pki/tls/certs/libwebsockets.org.cer",
105 "origin": ">https://localhost"
113 "origin": ">https://localhost"
121 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
127 The vhost name field is used to match on incoming SNI or Host: header, so it
128 must always be the host name used to reach the vhost externally.
130 - Vhosts may have the same name and different ports, these will each create a
131 listening socket on the appropriate port.
133 - Vhosts may also have the same port and different name: these will be treated as
134 true vhosts on one listening socket and the active vhost decided at SSL
135 negotiation time (via SNI) or if no SSL, then after the Host: header from
136 the client has been parsed.
142 Vhosts by default have available the union of any initial protocols from context creation time, and
143 any protocols exposed by plugins.
145 Vhosts can select which plugins they want to offer and give them per-vhost settings using this syntax
149 "warmcat-timezoom": {
156 The "x":"y" parameters like "status":"ok" are made available to the protocol during its per-vhost
157 LWS_CALLBACK_PROTOCOL_INIT (@in is a pointer to a linked list of struct lws_protocol_vhost_options
158 containing the name and value pointers).
160 To indicate that a protocol should be used when no Protocol: header is sent
161 by the client, you can use "default": "1"
165 "warmcat-timezoom": {
177 - If the three options `host-ssl-cert`, `host-ssl-ca` and `host-ssl-key` are given, then the vhost supports SSL.
179 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.
181 - `keeplive-timeout` (in secs) defaults to 60 for lwsws, it may be set as a vhost option
183 - `interface` lets you specify which network interface to listen on, if not given listens on all
185 - "`unix-socket`": "1" causes the unix socket specified in the interface option to be used instead of an INET socket
187 - "`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.
189 - "`access-log`": "filepath" sets where apache-compatible access logs will be written
191 - `"enable-client-ssl"`: `"1"` enables the vhost's client SSL context, you will need this if you plan to create client conections on the vhost that will use SSL. You don't need it if you only want http / ws client connections.
193 - "`ciphers`": "<cipher list>" sets the allowed list of ciphers and key exchange protocols for the vhost. The default list is restricted to only those providing PFS (Perfect Forward Secrecy) on the author's Fedora system.
195 If you need to allow weaker ciphers,you can provide an alternative list here per-vhost.
197 - "`ecdh-curve`": "<curve name>" The default ecdh curve is "prime256v1", but you can override it here, per-vhost
203 Where mounts are given in the vhost definition, then directory contents may
204 be auto-served if it matches the mountpoint.
206 Mount protocols are used to control what kind of translation happens
208 - file:// serve the uri using the remainder of the url past the mountpoint based on the origin directory.
210 Eg, with this mountpoint
215 "origin": "file:///var/www/mysite.com",
220 The uri /file.jpg would serve /var/www/mysite.com/file.jpg, since / matched.
222 - ^http:// or ^https:// these cause any url matching the mountpoint to issue a redirect to the origin url
224 - cgi:// this causes any matching url to be given to the named cgi, eg
228 "mountpoint": "/git",
229 "origin": "cgi:///var/www/cgi-bin/cgit",
232 "mountpoint": "/cgit-data",
233 "origin": "file:///usr/share/cgit",
238 would cause the url /git/myrepo to pass "myrepo" to the cgi /var/www/cgi-bin/cgit and send the results to the client.
240 Note: currently only a fixed set of mimetypes are supported.
246 1) When using a cgi:// protcol origin at a mountpoint, you may also give cgi environment variables specific to the mountpoint like this
250 "mountpoint": "/git",
251 "origin": "cgi:///var/www/cgi-bin/cgit",
254 "CGIT_CONFIG": "/etc/cgitrc/libwebsockets.org"
259 This allows you to customize one cgi depending on the mountpoint (and / or vhost).
261 2) It's also possible to set the cgi timeout (in secs) per cgi:// mount, like this
267 3) `callback://` protocol may be used when defining a mount to associate a
268 named protocol callback with the URL namespace area. For example
272 "mountpoint": "/formtest",
273 "origin": "callback://protocol-post-demo"
277 All handling of client access to /formtest[anything] will be passed to the
278 callback registered to the protocol "protocol-post-demo".
280 This is useful for handling POST http body content or general non-cgi http
281 payload generation inside a plugin.
283 See the related notes in README.coding.md
285 4) Cache policy of the files in the mount can also be set. If no
286 options are given, the content is marked uncacheable.
290 "origin": "file:///var/www/mysite.com",
291 "cache-max-age": "60", # seconds
292 "cache-reuse": "1", # allow reuse at client at all
293 "cache-revalidate": "1", # check it with server each time
294 "cache-intermediaries": "1" # allow intermediary caches to hold
301 Protcols and extensions may also be provided from "plugins", these are
302 lightweight dynamic libraries. They are scanned for at init time, and
303 any protocols and extensions found are added to the list given at context
306 Protocols receive init (LWS_CALLBACK_PROTOCOL_INIT) and destruction
307 (LWS_CALLBACK_PROTOCOL_DESTROY) callbacks per-vhost, and there are arrangements
308 they can make per-vhost allocations and get hold of the correct pointer from
309 the wsi at the callback.
311 This allows a protocol to choose to strictly segregate data on a per-vhost
312 basis, and also allows the plugin to handle its own initialization and
315 To help that happen conveniently, there are some new apis
318 - lws_protocol_get(wsi)
319 - lws_callback_on_writable_all_protocol_vhost(vhost, protocol)
320 - lws_protocol_vh_priv_zalloc(vhost, protocol, size)
321 - lws_protocol_vh_priv_get(vhost, protocol)
323 dumb increment, mirror and status protocol plugins are provided as examples.
326 Additional plugin search paths
327 ------------------------------
329 Packages that have their own lws plugins can install them in their own
330 preferred dir and ask lwsws to scan there by using a config fragment
331 like this, in its own conf.d/ file managed by the other package
335 "plugin-dir": "/usr/local/share/coherent-timeline/plugins"
340 lws-server-status plugin
341 ------------------------
343 One provided protocol can be used to monitor the server status.
345 Enable the protocol like this on a vhost's ws-protocols section
347 "lws-server-status": {
352 "update-ms" is used to control how often updated JSON is sent on a ws link.
354 And map the provided HTML into the vhost in the mounts section
357 "mountpoint": "/server-status",
358 "origin": "file:///usr/local/share/libwebsockets-test-server/server-status",
359 "default": "server-status.html"
362 You might choose to put it on its own vhost which has "interface": "lo", so it's not
366 Integration with Systemd
367 ------------------------
369 lwsws needs a service file like this as `/usr/lib/systemd/system/lwsws.service`
373 Description=Libwebsockets Web Server
377 ExecStart=/usr/local/bin/lwsws
381 WantedBy=multi-user.target
385 You can find this prepared in `./lwsws/usr-lib-systemd-system-lwsws.service`
388 Integration with logrotate
389 --------------------------
391 For correct operation with logrotate, `/etc/logrotate.d/lwsws` (if that's
392 where we're putting the logs) should contain
395 /var/log/lwsws/*log {
403 You can find this prepared in `/lwsws/etc-logrotate.d-lwsws`
405 Prepare the log directory like this
408 sudo mkdir /var/log/lwsws
409 sudo chmod 700 /var/log/lwsws