author | Kim Alvefur <zash@zash.se> |
Mon, 28 Nov 2022 19:05:48 +0100 | |
changeset 5097 | f2dfbcc676a6 |
parent 4910 | f07c9a6f19b3 |
child 5903 | 694b62d8a82f |
permissions | -rw-r--r-- |
1917
188c38c1a711
mod_http_upload/README: Update with XEP reference, stage, description
Kim Alvefur <zash@zash.se>
parents:
1866
diff
changeset
|
1 |
--- |
188c38c1a711
mod_http_upload/README: Update with XEP reference, stage, description
Kim Alvefur <zash@zash.se>
parents:
1866
diff
changeset
|
2 |
description: HTTP File Upload |
2288
1266f5c17c0d
mod_http_upload: Mention modules_enabled, but no example
Kim Alvefur <zash@zash.se>
parents:
2219
diff
changeset
|
3 |
labels: 'Stage-Alpha' |
1266f5c17c0d
mod_http_upload: Mention modules_enabled, but no example
Kim Alvefur <zash@zash.se>
parents:
2219
diff
changeset
|
4 |
--- |
1917
188c38c1a711
mod_http_upload/README: Update with XEP reference, stage, description
Kim Alvefur <zash@zash.se>
parents:
1866
diff
changeset
|
5 |
|
1820 | 6 |
Introduction |
7 |
============ |
|
8 |
||
2645
2d83e6c8160b
mod_http_upload: add support for XEP-0363 version 0.3
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
2330
diff
changeset
|
9 |
This module implements [XEP-0363], versions 0.2 and 0.3, which let |
2d83e6c8160b
mod_http_upload: add support for XEP-0363 version 0.3
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents:
2330
diff
changeset
|
10 |
clients upload files over HTTP. |
1820 | 11 |
|
12 |
Configuration |
|
13 |
============= |
|
14 |
||
1844
3bd265f7a95f
mod_http_upload/README: Point to Prosodys HTTP docs
Kim Alvefur <zash@zash.se>
parents:
1820
diff
changeset
|
15 |
mod\_http\_upload relies on Prosodys HTTP server and mod\_http for |
2288
1266f5c17c0d
mod_http_upload: Mention modules_enabled, but no example
Kim Alvefur <zash@zash.se>
parents:
2219
diff
changeset
|
16 |
serving HTTP requests. See [Prosodys HTTP server documentation][doc:http] |
1266f5c17c0d
mod_http_upload: Mention modules_enabled, but no example
Kim Alvefur <zash@zash.se>
parents:
2219
diff
changeset
|
17 |
for information about how to configure ports, HTTP Host names etc. |
1266f5c17c0d
mod_http_upload: Mention modules_enabled, but no example
Kim Alvefur <zash@zash.se>
parents:
2219
diff
changeset
|
18 |
|
1266f5c17c0d
mod_http_upload: Mention modules_enabled, but no example
Kim Alvefur <zash@zash.se>
parents:
2219
diff
changeset
|
19 |
The module can be added as a new Component definition: |
1844
3bd265f7a95f
mod_http_upload/README: Point to Prosodys HTTP docs
Kim Alvefur <zash@zash.se>
parents:
1820
diff
changeset
|
20 |
|
2288
1266f5c17c0d
mod_http_upload: Mention modules_enabled, but no example
Kim Alvefur <zash@zash.se>
parents:
2219
diff
changeset
|
21 |
``` {.lua} |
1266f5c17c0d
mod_http_upload: Mention modules_enabled, but no example
Kim Alvefur <zash@zash.se>
parents:
2219
diff
changeset
|
22 |
Component "upload.example.org" "http_upload" |
1266f5c17c0d
mod_http_upload: Mention modules_enabled, but no example
Kim Alvefur <zash@zash.se>
parents:
2219
diff
changeset
|
23 |
``` |
1820 | 24 |
|
3842
9f0c10bd4633
mod_http_upload: Recommend against adding to modules_enabled
Matthew Wild <mwild1@gmail.com>
parents:
3445
diff
changeset
|
25 |
It should **not** be added to modules_enabled. |
1820 | 26 |
|
3964
c8e4efef5cdb
mod_http_upload/README: Add example disco_items use
Kim Alvefur <zash@zash.se>
parents:
3842
diff
changeset
|
27 |
## Discoverability |
c8e4efef5cdb
mod_http_upload/README: Add example disco_items use
Kim Alvefur <zash@zash.se>
parents:
3842
diff
changeset
|
28 |
|
c8e4efef5cdb
mod_http_upload/README: Add example disco_items use
Kim Alvefur <zash@zash.se>
parents:
3842
diff
changeset
|
29 |
Prosody makes subdomains of your VirtualHosts easily discoverable by |
4621
260a33eabbd3
mod_http_upload: More emphasis on conditionality of disco_items
Kim Alvefur <zash@zash.se>
parents:
4447
diff
changeset
|
30 |
clients. To make the component discoverable by other hosts where the |
260a33eabbd3
mod_http_upload: More emphasis on conditionality of disco_items
Kim Alvefur <zash@zash.se>
parents:
4447
diff
changeset
|
31 |
component is **not a subdomain** of the VirtualHost, you can use |
3964
c8e4efef5cdb
mod_http_upload/README: Add example disco_items use
Kim Alvefur <zash@zash.se>
parents:
3842
diff
changeset
|
32 |
[`disco_items`][doc:modules:mod_disco#configuration]. |
c8e4efef5cdb
mod_http_upload/README: Add example disco_items use
Kim Alvefur <zash@zash.se>
parents:
3842
diff
changeset
|
33 |
|
c8e4efef5cdb
mod_http_upload/README: Add example disco_items use
Kim Alvefur <zash@zash.se>
parents:
3842
diff
changeset
|
34 |
``` {.lua} |
c8e4efef5cdb
mod_http_upload/README: Add example disco_items use
Kim Alvefur <zash@zash.se>
parents:
3842
diff
changeset
|
35 |
VirtualHost "foo.example.org" |
c8e4efef5cdb
mod_http_upload/README: Add example disco_items use
Kim Alvefur <zash@zash.se>
parents:
3842
diff
changeset
|
36 |
disco_items = { |
c8e4efef5cdb
mod_http_upload/README: Add example disco_items use
Kim Alvefur <zash@zash.se>
parents:
3842
diff
changeset
|
37 |
{ "upload.example.com" }, |
c8e4efef5cdb
mod_http_upload/README: Add example disco_items use
Kim Alvefur <zash@zash.se>
parents:
3842
diff
changeset
|
38 |
} |
c8e4efef5cdb
mod_http_upload/README: Add example disco_items use
Kim Alvefur <zash@zash.se>
parents:
3842
diff
changeset
|
39 |
``` |
c8e4efef5cdb
mod_http_upload/README: Add example disco_items use
Kim Alvefur <zash@zash.se>
parents:
3842
diff
changeset
|
40 |
|
4447
0a56dc6c61af
mod_http_upload: Add access config option
Nicolas Cedilnik <nicoco@nicoco.fr>
parents:
4074
diff
changeset
|
41 |
## Access |
0a56dc6c61af
mod_http_upload: Add access config option
Nicolas Cedilnik <nicoco@nicoco.fr>
parents:
4074
diff
changeset
|
42 |
|
0a56dc6c61af
mod_http_upload: Add access config option
Nicolas Cedilnik <nicoco@nicoco.fr>
parents:
4074
diff
changeset
|
43 |
You may want to give upload access to additional entities such as components |
0a56dc6c61af
mod_http_upload: Add access config option
Nicolas Cedilnik <nicoco@nicoco.fr>
parents:
4074
diff
changeset
|
44 |
by using the `http_upload_access` config option. |
0a56dc6c61af
mod_http_upload: Add access config option
Nicolas Cedilnik <nicoco@nicoco.fr>
parents:
4074
diff
changeset
|
45 |
|
0a56dc6c61af
mod_http_upload: Add access config option
Nicolas Cedilnik <nicoco@nicoco.fr>
parents:
4074
diff
changeset
|
46 |
``` {.lua} |
0a56dc6c61af
mod_http_upload: Add access config option
Nicolas Cedilnik <nicoco@nicoco.fr>
parents:
4074
diff
changeset
|
47 |
http_upload_access = {"gateway.example.com"}; |
0a56dc6c61af
mod_http_upload: Add access config option
Nicolas Cedilnik <nicoco@nicoco.fr>
parents:
4074
diff
changeset
|
48 |
``` |
0a56dc6c61af
mod_http_upload: Add access config option
Nicolas Cedilnik <nicoco@nicoco.fr>
parents:
4074
diff
changeset
|
49 |
|
1855
03c5639882a7
mod_http_upload: Add support for a file size limit
Kim Alvefur <zash@zash.se>
parents:
1851
diff
changeset
|
50 |
Limits |
03c5639882a7
mod_http_upload: Add support for a file size limit
Kim Alvefur <zash@zash.se>
parents:
1851
diff
changeset
|
51 |
------ |
03c5639882a7
mod_http_upload: Add support for a file size limit
Kim Alvefur <zash@zash.se>
parents:
1851
diff
changeset
|
52 |
|
2683
5f60dd12dbb8
mod_http_upload/README: Add sub-headings under limits
Kim Alvefur <zash@zash.se>
parents:
2682
diff
changeset
|
53 |
### Max size |
5f60dd12dbb8
mod_http_upload/README: Add sub-headings under limits
Kim Alvefur <zash@zash.se>
parents:
2682
diff
changeset
|
54 |
|
1855
03c5639882a7
mod_http_upload: Add support for a file size limit
Kim Alvefur <zash@zash.se>
parents:
1851
diff
changeset
|
55 |
A maximum file size can be set by: |
03c5639882a7
mod_http_upload: Add support for a file size limit
Kim Alvefur <zash@zash.se>
parents:
1851
diff
changeset
|
56 |
|
03c5639882a7
mod_http_upload: Add support for a file size limit
Kim Alvefur <zash@zash.se>
parents:
1851
diff
changeset
|
57 |
``` {.lua} |
2056
ad2966b932ed
mod_http_upload/README: Mention default upload size limit and change example to something that nobody should copy
Kim Alvefur <zash@zash.se>
parents:
1971
diff
changeset
|
58 |
http_upload_file_size_limit = 123 -- bytes |
1855
03c5639882a7
mod_http_upload: Add support for a file size limit
Kim Alvefur <zash@zash.se>
parents:
1851
diff
changeset
|
59 |
``` |
03c5639882a7
mod_http_upload: Add support for a file size limit
Kim Alvefur <zash@zash.se>
parents:
1851
diff
changeset
|
60 |
|
2288
1266f5c17c0d
mod_http_upload: Mention modules_enabled, but no example
Kim Alvefur <zash@zash.se>
parents:
2219
diff
changeset
|
61 |
Default is 1MB (1024\*1024). |
2056
ad2966b932ed
mod_http_upload/README: Mention default upload size limit and change example to something that nobody should copy
Kim Alvefur <zash@zash.se>
parents:
1971
diff
changeset
|
62 |
|
2330
8fad27d568aa
mod_http_upload/README: Mention the new HTTP parser limit on body/upload size
Kim Alvefur <zash@zash.se>
parents:
2288
diff
changeset
|
63 |
This can not be set over the value of `http_max_content_size` (default 10M). |
2952
7646f565c8ca
mod_http_upload/README: Point at mod_http_upload_external
Kim Alvefur <zash@zash.se>
parents:
2735
diff
changeset
|
64 |
Consider [mod_http_upload_external] instead of attempting to increase |
7646f565c8ca
mod_http_upload/README: Point at mod_http_upload_external
Kim Alvefur <zash@zash.se>
parents:
2735
diff
changeset
|
65 |
this limit. |
2330
8fad27d568aa
mod_http_upload/README: Mention the new HTTP parser limit on body/upload size
Kim Alvefur <zash@zash.se>
parents:
2288
diff
changeset
|
66 |
|
2683
5f60dd12dbb8
mod_http_upload/README: Add sub-headings under limits
Kim Alvefur <zash@zash.se>
parents:
2682
diff
changeset
|
67 |
### Max age |
5f60dd12dbb8
mod_http_upload/README: Add sub-headings under limits
Kim Alvefur <zash@zash.se>
parents:
2682
diff
changeset
|
68 |
|
2681
6daaa1ad2559
mod_http_upload: Add option for expiry of files after a configurable time (closes #557)
Kim Alvefur <zash@zash.se>
parents:
2645
diff
changeset
|
69 |
Files can be set to be deleted after some time: |
6daaa1ad2559
mod_http_upload: Add option for expiry of files after a configurable time (closes #557)
Kim Alvefur <zash@zash.se>
parents:
2645
diff
changeset
|
70 |
|
6daaa1ad2559
mod_http_upload: Add option for expiry of files after a configurable time (closes #557)
Kim Alvefur <zash@zash.se>
parents:
2645
diff
changeset
|
71 |
``` lua |
6daaa1ad2559
mod_http_upload: Add option for expiry of files after a configurable time (closes #557)
Kim Alvefur <zash@zash.se>
parents:
2645
diff
changeset
|
72 |
http_upload_expire_after = 60 * 60 * 24 * 7 -- a week in seconds |
6daaa1ad2559
mod_http_upload: Add option for expiry of files after a configurable time (closes #557)
Kim Alvefur <zash@zash.se>
parents:
2645
diff
changeset
|
73 |
``` |
6daaa1ad2559
mod_http_upload: Add option for expiry of files after a configurable time (closes #557)
Kim Alvefur <zash@zash.se>
parents:
2645
diff
changeset
|
74 |
|
3443
5912f3bacdb4
mod_http_upload: Clarify when expiry is checked
Kim Alvefur <zash@zash.se>
parents:
2952
diff
changeset
|
75 |
Expired files are deleted when a new upload slot is requested, |
5912f3bacdb4
mod_http_upload: Clarify when expiry is checked
Kim Alvefur <zash@zash.se>
parents:
2952
diff
changeset
|
76 |
|
3444
64d1af33084f
mod_http_upload: Document prosodyctl command for expiring uploads
Kim Alvefur <zash@zash.se>
parents:
3443
diff
changeset
|
77 |
A command exists to invoke expiry: |
64d1af33084f
mod_http_upload: Document prosodyctl command for expiring uploads
Kim Alvefur <zash@zash.se>
parents:
3443
diff
changeset
|
78 |
|
64d1af33084f
mod_http_upload: Document prosodyctl command for expiring uploads
Kim Alvefur <zash@zash.se>
parents:
3443
diff
changeset
|
79 |
``` |
3967
acd231e2b46f
mod_http_upload/README: User/host arguments to command not optional (thanks kaliko)
Kim Alvefur <zash@zash.se>
parents:
3964
diff
changeset
|
80 |
prosodyctl mod_http_upload expire [list of users or hosts] |
3444
64d1af33084f
mod_http_upload: Document prosodyctl command for expiring uploads
Kim Alvefur <zash@zash.se>
parents:
3443
diff
changeset
|
81 |
``` |
64d1af33084f
mod_http_upload: Document prosodyctl command for expiring uploads
Kim Alvefur <zash@zash.se>
parents:
3443
diff
changeset
|
82 |
|
2683
5f60dd12dbb8
mod_http_upload/README: Add sub-headings under limits
Kim Alvefur <zash@zash.se>
parents:
2682
diff
changeset
|
83 |
### User quota |
5f60dd12dbb8
mod_http_upload/README: Add sub-headings under limits
Kim Alvefur <zash@zash.se>
parents:
2682
diff
changeset
|
84 |
|
2682
2dec7cad9218
mod_http_upload: Implement quota support (closes #823)
Kim Alvefur <zash@zash.se>
parents:
2681
diff
changeset
|
85 |
A total maximum size of all uploaded files per user can be set by: |
2dec7cad9218
mod_http_upload: Implement quota support (closes #823)
Kim Alvefur <zash@zash.se>
parents:
2681
diff
changeset
|
86 |
|
2dec7cad9218
mod_http_upload: Implement quota support (closes #823)
Kim Alvefur <zash@zash.se>
parents:
2681
diff
changeset
|
87 |
``` lua |
2dec7cad9218
mod_http_upload: Implement quota support (closes #823)
Kim Alvefur <zash@zash.se>
parents:
2681
diff
changeset
|
88 |
http_upload_quota = 1234 -- bytes |
2dec7cad9218
mod_http_upload: Implement quota support (closes #823)
Kim Alvefur <zash@zash.se>
parents:
2681
diff
changeset
|
89 |
``` |
2dec7cad9218
mod_http_upload: Implement quota support (closes #823)
Kim Alvefur <zash@zash.se>
parents:
2681
diff
changeset
|
90 |
|
3445
0bff7d5ca81d
mod_http_upload: Clarify how quotas affect upload requests
Kim Alvefur <zash@zash.se>
parents:
3444
diff
changeset
|
91 |
A request for a slot that would take an user over quota is denied. |
0bff7d5ca81d
mod_http_upload: Clarify how quotas affect upload requests
Kim Alvefur <zash@zash.se>
parents:
3444
diff
changeset
|
92 |
|
1971
2ce2b194d501
mod_http_upload: Make file system path configurable
Kim Alvefur <zash@zash.se>
parents:
1917
diff
changeset
|
93 |
Path |
2ce2b194d501
mod_http_upload: Make file system path configurable
Kim Alvefur <zash@zash.se>
parents:
1917
diff
changeset
|
94 |
---- |
2ce2b194d501
mod_http_upload: Make file system path configurable
Kim Alvefur <zash@zash.se>
parents:
1917
diff
changeset
|
95 |
|
2ce2b194d501
mod_http_upload: Make file system path configurable
Kim Alvefur <zash@zash.se>
parents:
1917
diff
changeset
|
96 |
By default, uploaded files are put in a sub-directory of the default |
2ce2b194d501
mod_http_upload: Make file system path configurable
Kim Alvefur <zash@zash.se>
parents:
1917
diff
changeset
|
97 |
Prosody storage path (usually `/var/lib/prosody`). This can be changed: |
2ce2b194d501
mod_http_upload: Make file system path configurable
Kim Alvefur <zash@zash.se>
parents:
1917
diff
changeset
|
98 |
|
2ce2b194d501
mod_http_upload: Make file system path configurable
Kim Alvefur <zash@zash.se>
parents:
1917
diff
changeset
|
99 |
``` {.lua} |
4074
268fa9d45840
mod_http_upload/README: Fix typo (thanks bjoernb)
Kim Alvefur <zash@zash.se>
parents:
3967
diff
changeset
|
100 |
http_upload_path = "/path/to/uploaded/files" |
1971
2ce2b194d501
mod_http_upload: Make file system path configurable
Kim Alvefur <zash@zash.se>
parents:
1917
diff
changeset
|
101 |
``` |
2ce2b194d501
mod_http_upload: Make file system path configurable
Kim Alvefur <zash@zash.se>
parents:
1917
diff
changeset
|
102 |
|
1851
cd98a1103ecf
mod_http_upload/README: Say it works with 0.9+
Kim Alvefur <zash@zash.se>
parents:
1844
diff
changeset
|
103 |
Compatibility |
cd98a1103ecf
mod_http_upload/README: Say it works with 0.9+
Kim Alvefur <zash@zash.se>
parents:
1844
diff
changeset
|
104 |
============= |
cd98a1103ecf
mod_http_upload/README: Say it works with 0.9+
Kim Alvefur <zash@zash.se>
parents:
1844
diff
changeset
|
105 |
|
4910
f07c9a6f19b3
mod_http_upload: Update compatibility information
Matthew Wild <mwild1@gmail.com>
parents:
4621
diff
changeset
|
106 |
Works with Prosody 0.11.x and later. |
f07c9a6f19b3
mod_http_upload: Update compatibility information
Matthew Wild <mwild1@gmail.com>
parents:
4621
diff
changeset
|
107 |
|
f07c9a6f19b3
mod_http_upload: Update compatibility information
Matthew Wild <mwild1@gmail.com>
parents:
4621
diff
changeset
|
108 |
In Prosody 0.12 and later, consider switching to [mod_http_file_share](https://prosody.im/doc/modules/mod_http_file_share) |
f07c9a6f19b3
mod_http_upload: Update compatibility information
Matthew Wild <mwild1@gmail.com>
parents:
4621
diff
changeset
|
109 |
which is distributed with Prosody. You can migrate existing files using |
f07c9a6f19b3
mod_http_upload: Update compatibility information
Matthew Wild <mwild1@gmail.com>
parents:
4621
diff
changeset
|
110 |
[mod_migrate_http_upload](https://modules.prosody.im/mod_migrate_http_upload.html). |