README.md
1# Deaddrop: File upload and sharing plugin
2
3## Building the plugin
4
5Just configure lws with `cmake .. -DLWS_WITH_PLUGINS=1` and build lws as normal.
6
7## Configurable settings
8
9|pvo name|value meaning|
10|---|---|
11|upload-dir|A writeable directory where uploaded files will go|
12|max-size|Maximum individual file size in bytes|
13|basic-auth|Path to basic auth credential file so wss can also be protected|
14
15## Required mounts
16
17To use deaddrop meaningfully, all the mounts and the ws protocol must be
18protected by basic auth. And to use basic auth securely, the connection must
19be protected from snooping by tls.
20
211) Set the basic-auth pvo to require valid credentials as described above
22
232) Protect your basic fileserving mount by the same basic auth file... this is
24 used to serve index.html, the css etc.
25
263) Add a callback mount into "lws-deaddrop" protocol at "upload"... so if your
27 URL for deaddrop is "/tools/share", this would be at "/tools/share/upload".
28 It must also be protected by the basic auth file.
29
304) Add a fileserving mount at the url "get" (continuing the example above, it
31 would be "/tools/share/get" whose origin matches the "upload-dir" pvo
32 value you selected. This mount needs any additional mimtype mappings since
33 it's where the uploaded files are shared from.
34
35## Using with C
36
37See ./minimal-examples/http-server/minimal-example-http-server-deaddrop for
38how to use the plugin directly with C.
39
40## Using with lwsws / lejp-conf
41
42As a plugin, you can configure the mounts and pvos per-vhost easily in JSON.
43
44All the snippets here
45
46The mountpoints would look something like this (added to vhost/mounts)
47
48```
49 {
50 "mountpoint": "/tools/share",
51 "origin": "file:///var/www/deaddrop",
52 "default": "index.html",
53 "basic-auth": "/var/www/ba"
54 }, {
55 "mountpoint": "/tools/share/upload",
56 "origin": "callback://lws-deaddrop",
57 "basic-auth": "/var/www/ba"
58 }, {
59 "mountpoint": "/tools/share/get",
60 "origin": "file:///var/cache/deaddrop-uploads",
61 "basic-auth": "/var/www/ba",
62
63 "extra-mimetypes": {
64 ".bin": "application/octet-stream",
65 ".ttf": "application/x-font-truetype",
66 ".otf": "application/font-sfnt",
67 ".zip": "application/zip",
68 ".webm": "video/webm",
69 ".romfs": "application/octet-stream",
70 ".pdf": "application/pdf",
71 ".odt": "application/vnd.oasis.opendocument.text",
72 ".tgz": "application/x-gzip",
73 ".tar.gz": "application/x-gzip"
74 }
75 }
76```
77
78This enables the plugin on the vhost, configures the pvos, and makes
79the wss serving also depend on having a valid basic auth credential.
80
81```
82 "ws-protocols": [{
83 "lws-deaddrop": {
84 "status": "ok",
85 "upload-dir": "/var/cache/deaddrop-uploads",
86 "max-size": "52428800",
87 "basic-auth": "/var/www/ba"
88 }
89 }],
90```
91
92