4 @section lwsws Libwebsockets Web Server
6 lwsws is an implementation of a very lightweight, ws-capable generic web
7 server, which uses libwebsockets to implement everything underneath.
9 If you are basically implementing a standalone server with lws, you can avoid
10 reinventing the wheel and use a debugged server including lws.
15 Just enable -DLWS_WITH_LWSWS=1 at cmake-time.
17 It enables libuv and plugin support automatically.
19 NOTICE on Ubuntu, the default libuv package is called "libuv-0.10". This is ancient.
21 You should replace this with libuv1 and libuv1-dev before proceeding.
23 @section lwswsc Lwsws Configuration
25 lwsws uses JSON config files, they're pure JSON except:
27 - '#' may be used to turn the rest of the line into a comment.
29 - There's also a single substitution, if a string contains "_lws_ddir_", then that is
30 replaced with the LWS install data directory path, eg, "/usr/share" or whatever was
31 set when LWS was built + installed. That lets you refer to installed paths without
32 having to change the config if your install path was different.
34 There is a single file intended for global settings
38 # these are the server global settings
39 # stuff related to vhosts should go in one
40 # file per vhost in ../conf.d/
44 "uid": "48", # apache user
45 "gid": "48", # apache user
47 "server-string": "myserver v1", # returned in http headers
48 "ws-pingpong-secs": "200", # confirm idle established ws connections this often
53 and a config directory intended to take one file per vhost
55 /etc/lwsws/conf.d/warmcat.com
59 "name": "warmcat.com",
61 "interface": "eth0", # optional
62 "host-ssl-key": "/etc/pki/tls/private/warmcat.com.key", # if given enable ssl
63 "host-ssl-cert": "/etc/pki/tls/certs/warmcat.com.crt",
64 "host-ssl-ca": "/etc/pki/tls/certs/warmcat.com.cer",
65 "mounts": [{ # autoserve
67 "origin": "file:///var/www/warmcat.com",
68 "default": "index.html"
73 To get started quickly, an example config reproducing the old test server
74 on port 7681, non-SSL is provided. To set it up
76 # mkdir -p /etc/lwsws/conf.d /var/log/lwsws
77 # cp ./lwsws/etc-lwsws-conf-EXAMPLE /etc/lwsws/conf
78 # cp ./lwsws/etc-lwsws-conf.d-localhost-EXAMPLE /etc/lwsws/conf.d/test-server
82 @section lwsogo Other Global Options
84 - `reject-service-keywords` allows you to return an HTTP error code and message of your choice
85 if a keyword is found in the user agent
88 "reject-service-keywords": [{
89 "scumbot": "404 Not Found"
93 - `timeout-secs` lets you set the global timeout for various network-related
94 operations in lws, in seconds. It defaults to 5.
96 @section lwswsv Lwsws Vhosts
98 One server can run many vhosts, where SSL is in use SNI is used to match
99 the connection to a vhost and its vhost-specific SSL keys during SSL
102 Listing multiple vhosts looks something like this
108 "host-ssl-key": "/etc/pki/tls/private/libwebsockets.org.key",
109 "host-ssl-cert": "/etc/pki/tls/certs/libwebsockets.org.crt",
110 "host-ssl-ca": "/etc/pki/tls/certs/libwebsockets.org.cer",
113 "origin": "file:///var/www/libwebsockets.org",
114 "default": "index.html"
116 "mountpoint": "/testserver",
117 "origin": "file:///usr/local/share/libwebsockets-test-server",
118 "default": "test.html"
120 # which protocols are enabled for this vhost, and optional
121 # vhost-specific config options for the protocol
124 "warmcat,timezoom": {
132 "host-ssl-key": "/etc/pki/tls/private/libwebsockets.org.key",
133 "host-ssl-cert": "/etc/pki/tls/certs/libwebsockets.org.crt",
134 "host-ssl-ca": "/etc/pki/tls/certs/libwebsockets.org.cer",
137 "origin": ">https://localhost"
145 "origin": ">https://localhost"
153 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
156 @section lwswsvn Lwsws Vhost name and port sharing
158 The vhost name field is used to match on incoming SNI or Host: header, so it
159 must always be the host name used to reach the vhost externally.
161 - Vhosts may have the same name and different ports, these will each create a
162 listening socket on the appropriate port.
164 - Vhosts may also have the same port and different name: these will be treated as
165 true vhosts on one listening socket and the active vhost decided at SSL
166 negotiation time (via SNI) or if no SSL, then after the Host: header from
167 the client has been parsed.
170 @section lwswspr Lwsws Protocols
172 Vhosts by default have available the union of any initial protocols from context creation time, and
173 any protocols exposed by plugins.
175 Vhosts can select which plugins they want to offer and give them per-vhost settings using this syntax
178 "warmcat-timezoom": {
184 The "x":"y" parameters like "status":"ok" are made available to the protocol during its per-vhost
185 LWS_CALLBACK_PROTOCOL_INIT (@in is a pointer to a linked list of struct lws_protocol_vhost_options
186 containing the name and value pointers).
188 To indicate that a protocol should be used when no Protocol: header is sent
189 by the client, you can use "default": "1"
192 "warmcat-timezoom": {
200 @section lwswsovo Lwsws Other vhost options
202 - If the three options `host-ssl-cert`, `host-ssl-ca` and `host-ssl-key` are given, then the vhost supports SSL.
204 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.
206 - `keeplive-timeout` (in secs) defaults to 60 for lwsws, it may be set as a vhost option
208 - `interface` lets you specify which network interface to listen on, if not given listens on all
210 - "`unix-socket`": "1" causes the unix socket specified in the interface option to be used instead of an INET socket
212 - "`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.
214 - "`access-log`": "filepath" sets where apache-compatible access logs will be written
216 - `"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.
218 - "`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.
220 If you need to allow weaker ciphers,you can provide an alternative list here per-vhost.
222 - "`ecdh-curve`": "<curve name>" The default ecdh curve is "prime256v1", but you can override it here, per-vhost
224 - "`noipv6`": "on" Disable ipv6 completely for this vhost
226 - "`ipv6only`": "on" Only allow ipv6 on this vhost / "off" only allow ipv4 on this vhost
228 - "`ssl-option-set`": "<decimal>" Sets the SSL option flag value for the vhost.
229 It may be used multiple times and OR's the flags together.
231 The values are derived from /usr/include/openssl/ssl.h
233 # define SSL_OP_NO_TLSv1_1 0x10000000L
239 "`ssl-option-set`": "268435456"
241 - "`ssl-option-clear'": "<decimal>" Clears the SSL option flag value for the vhost.
242 It may be used multiple times and OR's the flags together.
244 - "`headers':: [{ "header1": "h1value", "header2": "h2value" }]
246 allows you to set arbitrary headers on every file served by the vhost
248 recommended vhost headers for good client security are
252 "Content-Security-Policy": "script-src 'self'",
253 "X-Content-Type-Options": "nosniff",
254 "X-XSS-Protection": "1; mode=block",
255 "X-Frame-Options": "SAMEORIGIN"
260 @section lwswsm Lwsws Mounts
262 Where mounts are given in the vhost definition, then directory contents may
263 be auto-served if it matches the mountpoint.
265 Mount protocols are used to control what kind of translation happens
267 - file:// serve the uri using the remainder of the url past the mountpoint based on the origin directory.
269 Eg, with this mountpoint
273 "origin": "file:///var/www/mysite.com",
277 The uri /file.jpg would serve /var/www/mysite.com/file.jpg, since / matched.
279 - ^http:// or ^https:// these cause any url matching the mountpoint to issue a redirect to the origin url
281 - cgi:// this causes any matching url to be given to the named cgi, eg
284 "mountpoint": "/git",
285 "origin": "cgi:///var/www/cgi-bin/cgit",
288 "mountpoint": "/cgit-data",
289 "origin": "file:///usr/share/cgit",
293 would cause the url /git/myrepo to pass "myrepo" to the cgi /var/www/cgi-bin/cgit and send the results to the client.
295 - http:// or https:// these perform reverse proxying, serving the remote origin content from the mountpoint. Eg
299 "mountpoint": "/proxytest",
300 "origin": "https://libwebsockets.org"
304 This will cause your local url `/proxytest` to serve content fetched from libwebsockets.org over ssl; whether it's served from your server using ssl is unrelated and depends how you configured your local server. Notice if you will use the proxying feature, `LWS_WITH_HTTP_PROXY` is required to be enabled at cmake, and for `https` proxy origins, your lwsws configuration must include `"init-ssl": "1"` and the vhost with the proxy mount must have `"enable-client-ssl": "1"`, even if you are not using ssl to serve.
306 `/proxytest/abc`, or `/proxytest/abc?def=ghi` etc map to the origin + the part past `/proxytest`, so links and img src urls etc work as do all urls under the origin path.
308 In addition link and src urls in the document are rewritten so / or the origin url part are rewritten to the mountpoint part.
311 @section lwswsomo Lwsws Other mount options
313 1) Some protocols may want "per-mount options" in name:value format. You can
314 provide them using "pmo"
317 "mountpoint": "/stuff",
318 "origin": "callback://myprotocol",
324 2) When using a cgi:// protcol origin at a mountpoint, you may also give cgi environment variables specific to the mountpoint like this
327 "mountpoint": "/git",
328 "origin": "cgi:///var/www/cgi-bin/cgit",
331 "CGIT_CONFIG": "/etc/cgitrc/libwebsockets.org"
335 This allows you to customize one cgi depending on the mountpoint (and / or vhost).
337 3) It's also possible to set the cgi timeout (in secs) per cgi:// mount, like this
341 4) `callback://` protocol may be used when defining a mount to associate a
342 named protocol callback with the URL namespace area. For example
345 "mountpoint": "/formtest",
346 "origin": "callback://protocol-post-demo"
349 All handling of client access to /formtest[anything] will be passed to the
350 callback registered to the protocol "protocol-post-demo".
352 This is useful for handling POST http body content or general non-cgi http
353 payload generation inside a plugin.
355 See the related notes in README.coding.md
357 5) Cache policy of the files in the mount can also be set. If no
358 options are given, the content is marked uncacheable.
362 "origin": "file:///var/www/mysite.com",
363 "cache-max-age": "60", # seconds
364 "cache-reuse": "1", # allow reuse at client at all
365 "cache-revalidate": "1", # check it with server each time
366 "cache-intermediaries": "1" # allow intermediary caches to hold
370 6) You can also define a list of additional mimetypes per-mount
373 ".zip": "application/zip",
378 Normally a file suffix MUST match one of the canned mimetypes or one of the extra
379 mimetypes, or the file is not served. This adds a little bit of security because
380 even if there is a bug somewhere and the mount dirs are circumvented, lws will not
381 serve, eg, /etc/passwd.
383 If you provide an extra mimetype entry
387 Then any file is served, if the mimetype was not known then it is served without a
388 Content-Type: header.
390 7) A mount can be protected by HTTP Basic Auth. This only makes sense when using
391 https, since otherwise the password can be sniffed.
393 You can add a `basic-auth` entry on a mount like this
397 "mountpoint": "/basic-auth",
398 "origin": "file://_lws_ddir_/libwebsockets-test-server/private",
399 "basic-auth": "/var/www/balogins-private"
403 Before serving anything, lws will signal to the browser that a username / password
404 combination is required, and it will pop up a dialog. When the user has filled it
405 in, lwsws checks the user:password string against the text file named in the `basic-auth`
408 The file should contain user:pass one per line
415 The file should be readable by lwsws, and for a little bit of extra security not
416 have a file suffix, so lws would reject to serve it even if it could find it on
420 @section lwswspl Lwsws Plugins
422 Protcols and extensions may also be provided from "plugins", these are
423 lightweight dynamic libraries. They are scanned for at init time, and
424 any protocols and extensions found are added to the list given at context
427 Protocols receive init (LWS_CALLBACK_PROTOCOL_INIT) and destruction
428 (LWS_CALLBACK_PROTOCOL_DESTROY) callbacks per-vhost, and there are arrangements
429 they can make per-vhost allocations and get hold of the correct pointer from
430 the wsi at the callback.
432 This allows a protocol to choose to strictly segregate data on a per-vhost
433 basis, and also allows the plugin to handle its own initialization and
436 To help that happen conveniently, there are some new apis
439 - lws_protocol_get(wsi)
440 - lws_callback_on_writable_all_protocol_vhost(vhost, protocol)
441 - lws_protocol_vh_priv_zalloc(vhost, protocol, size)
442 - lws_protocol_vh_priv_get(vhost, protocol)
444 dumb increment, mirror and status protocol plugins are provided as examples.
447 @section lwswsplaplp Additional plugin search paths
449 Packages that have their own lws plugins can install them in their own
450 preferred dir and ask lwsws to scan there by using a config fragment
451 like this, in its own conf.d/ file managed by the other package
455 "plugin-dir": "/usr/local/share/coherent-timeline/plugins"
460 @section lwswsssp lws-server-status plugin
462 One provided protocol can be used to monitor the server status.
464 Enable the protocol like this on a vhost's ws-protocols section
466 "lws-server-status": {
471 `"update-ms"` is used to control how often updated JSON is sent on a ws link.
473 And map the provided HTML into the vhost in the mounts section
476 "mountpoint": "/server-status",
477 "origin": "file:///usr/local/share/libwebsockets-test-server/server-status",
478 "default": "server-status.html"
481 You might choose to put it on its own vhost which has "interface": "lo", so it's not
482 externally visible, or use the Basic Auth support to require authentication to
485 `"hide-vhosts": "{0 | 1}"` lets you control if information about your vhosts is included.
486 Since this includes mounts, you might not want to leak that information, mount names,
489 `"filespath":"{path}"` lets you give a server filepath which is read and sent to the browser
490 on each refresh. For example, you can provide server temperature information on most
491 Linux systems by giving an appropriate path down /sys.
493 This may be given multiple times.
496 @section lwswsreload Lwsws Configuration Reload
498 You may send lwsws a `HUP` signal, by, eg
501 $ sudo killall -HUP lwsws
504 This causes lwsws to "deprecate" the existing lwsws process, and remove and close all of
505 its listen sockets, but otherwise allowing it to continue to run, until all
506 of its open connections close.
508 When a deprecated lwsws process has no open connections left, it is destroyed
511 After sending the SIGHUP to the main lwsws process, a new lwsws process, which can
512 pick up the newly-available listen sockets, and use the current configuration
513 files, is automatically started.
515 The new configuration may differ from the original one in arbitrary ways, the new
516 context is created from scratch each time without reference to the original one.
520 1) Protocols that provide a "shared world" like mirror will have as many "worlds"
521 as there are lwsws processes still active. People connected to a deprecated lwsws
522 process remain connected to the existing peers.
524 But any new connections will apply to the new lwsws process, which does not share
525 per-vhost "shared world" data with the deprecated process. That means no new
526 connections on the deprecated context, ie a "shrinking world" for those guys, and a
527 "growing world" for people who connect after the SIGHUP.
529 2) The new lwsws process owes nothing to the previous one. It starts with fresh
530 plugins, fresh configuration, fresh root privileges if that how you start it.
532 The plugins may have been updated in arbitrary ways including struct size changes
533 etc, and lwsws or lws may also have been updated arbitrarily.
535 3) A root parent process is left up that is not able to do anything except
536 respond to SIGHUP or SIGTERM. Actual serving and network listening etc happens
537 in child processes which use the privileges set in the lwsws config files.
539 @section lwswssysd Lwsws Integration with Systemd
541 lwsws needs a service file like this as `/usr/lib/systemd/system/lwsws.service`
544 Description=Libwebsockets Web Server
548 ExecStart=/usr/local/bin/lwsws
549 ExecReload=/usr/bin/killall -s SIGHUP lwsws ; sleep 1 ; /usr/local/bin/lwsws
553 WantedBy=multi-user.target
556 You can find this prepared in `./lwsws/usr-lib-systemd-system-lwsws.service`
559 @section lwswslr Lwsws Integration with logrotate
561 For correct operation with logrotate, `/etc/logrotate.d/lwsws` (if that's
562 where we're putting the logs) should contain
564 /var/log/lwsws/*log {
571 You can find this prepared in `/lwsws/etc-logrotate.d-lwsws`
573 Prepare the log directory like this
576 sudo mkdir /var/log/lwsws
577 sudo chmod 700 /var/log/lwsws