Introduction

However there are so many new features, mainly around serving, the purpose of this document is to give an overview about what's now possible.

All the domains on this server are now being served by libwebsockets + LWSWS... that includes the CGI features like cgit and mailman.

Summary of new features

• New vhosts allow unlimited separate serving domains inside a context, each may have its own listen socket, or share an existing one. Many lws features that there used to only be one of in the context, are now per-vhost. Each socket can be optionally restricted to listen on one network interface.

  For compatibility, by default only one vhost is created and works as before, but you can also now have no default vhost created at context creation time and add as many as you need afterwards, on same or different ports.

• SNI (Server Name Indication) SSL support allows disambiguating multiple servers on one port while being able to encrypt the connection with the right certificate

• Production-ready CGI support, using vfork() where available. See our cgit and Mailman for live examples. CGI producing headers, CGI chunking, CGI POST are all supported.

• Vhosts can have "mounts" attached, these associate parts of the server's URL namespace with an "origin" which may be a server directory, a redirect, or CGI handler. When lws sees it's being asked to serve content from a mount, it handles it automatically, inside the library, without needing any support from the user callback.
  • You no longer have to provide callback handling to serve content from mounts
  • Content from very different origins can populate the server URL space seamlessly, eg, /git is a CGI, and /testserver is html served from a mount
  • Common serving code is maintained in the library, providing more features centrally

• Mounts may also set caching policy, with E-tag hashes and automatic 304 indication to the client on subsequent matching. Cache defaults to defeated, it can be set to be possible at all and for what period, to require object revalidation or not and if intermediaries may cache the content.

• Vhosts can select which ws protocols are available to clients, and set per-vhost protocol options.

• Vhosts can also set where apache-compatible logs should be stored

• In addition to per-vhost SSL certs, Strict Transport Security (STS) may be enabled on each vhost. This is necessary to get the SSL Labs "A+" certification.

• WS Protocols may be implemented generically as lws "plugins", these are responsible for their own init and teardown and are designed to not require any user code. Plugins can be built standalone independent of the user application.

• A new generic webserver, LWSWS built around libwebsockets, is included. This lets you manage all the new server-related features without writing any code, by creating and managing vhosts, mounts and protocols in JSON generically. The combination of lws WS plugins and lwsws reduces the amount of code needed to deploy your protocol just down to the protocol itself. And if later you want to combine more features, the plugins have no dependencies on each other so they can be integrated into the same LWSWS instance seamlessly.

  So for server case, using LWSWS + WS protocol plugins should be considered instead of rolling your own app using LWS directly.

• A ws protocol plugin is provided which may be mounted on one or more vhosts to show server statistics, many kinds of statistics are reported on a live websocket, per vhost.

  You can see a live example for this server here.

Using plugins and mounts with vhosts in lws code

test-server-2.0.c

Everything is in a short single file and it uses the lws protocol plugins to get the test protocols.

Building plugins outside of lws

This has its own CMakeLists.txt to make it easy to build against and already-installed lws. Instructions can be found in README.build.md