lwsws cgi integration
[platform/upstream/libwebsockets.git] / 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 Mount protocols are used to control what kind of translation happens
144
145  - file://  serve the uri using the remainder of the url past the mountpoint based on the origin directory.
146
147  Eg, with this mountpoint
148
149 ```
150        {
151         "mountpoint": "/",
152         "origin": "file:///var/www/mysite.com",
153         "default": "/"
154        }
155 ```
156
157  The uri /file.jpg would serve /var/www/mysite.com/file.jpg, since / matched.
158
159  - ^http:// or ^https://  these cause any url matching the mountpoint to issue a redirect to the origin url
160
161  - cgi://   this causes any matching url to be given to the named cgi, eg
162
163 ```
164        {
165         "mountpoint": "/git",
166         "origin": "cgi:///var/www/cgi-bin/cgit",
167         "default": "/"
168        }, {
169         "mountpoint": "/cgit-data",
170         "origin": "file:///usr/share/cgit",
171         "default": "/"
172        },
173 ```
174
175  would cause the url /git/myrepo to pass "myrepo" to the cgi /var/www/cgi-bin/cgit and send the results to the client.
176
177  When using a cgi:// protcol origin at a mountpoint, you may also give cgi environment variables specific to the mountpoint like this
178
179 ```
180        {
181         "mountpoint": "/git",
182         "origin": "cgi:///var/www/cgi-bin/cgit",
183         "default": "/",
184         "cgi-env": [{
185                 "CGIT_CONFIG": "/etc/cgitrc/libwebsockets.org"
186         }]
187        }
188 ```
189
190  This allows you to customize one cgi depending on the mountpoint (and / or vhost).
191
192 Currently only a fixed set of mimetypes are supported.
193
194
195 Plugins
196 -------
197
198 Protcols and extensions may also be provided from "plugins", these are
199 lightweight dynamic libraries.  They are scanned for at init time, and
200 any protocols and extensions found are added to the list given at context
201 creation time.
202
203 Protocols receive init (LWS_CALLBACK_PROTOCOL_INIT) and destruction
204 (LWS_CALLBACK_PROTOCOL_DESTROY) callbacks per-vhost, and there are arrangements
205 they can make per-vhost allocations and get hold of the correct pointer from
206 the wsi at the callback.
207
208 This allows a protocol to choose to strictly segregate data on a per-vhost
209 basis, and also allows the plugin to handle its own initialization and
210 context storage.
211
212 To help that happen conveniently, there are some new apis
213
214  - lws_vhost_get(wsi)
215  - lws_protocol_get(wsi)
216  - lws_callback_on_writable_all_protocol_vhost(vhost, protocol)
217  - lws_protocol_vh_priv_zalloc(vhost, protocol, size)
218  - lws_protocol_vh_priv_get(vhost, protocol)
219  
220 dumb increment, mirror and status protocol plugins are provided as examples.
221
222
223 Protocols
224 ---------
225
226 Vhosts by default have available the union of any initial protocols from context creation time, and
227 any protocols exposed by plugins.
228
229 Vhosts can select which plugins they want to offer and give them per-vhost settings using this syntax
230
231 ```     
232      "ws-protocols": [{
233        "warmcat,timezoom": {
234          "status": "ok"
235        }
236      }]
237
238 ```
239