prosody-modules
125279f4a5b8
mod_http_upload/README.markdown

Find changesets by keywords by author, files, the commit message, revision number or hash, or revset expression.

Software / code / prosody-modules

Annotate

mod_http_upload/README.markdown @ 4476:125279f4a5b8

mod_rest: Restructure API spec To make referencing individual fields easier, apparently some things don't like references to individual properties of an object.
author Kim Alvefur <zash@zash.se>
date Sun, 28 Feb 2021 18:55:18 +0100
parent 4443:0a56dc6c61af
child 4617:260a33eabbd3
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
1913
188c38c1a711 mod_http_upload/README: Update with XEP reference, stage, description
Kim Alvefur <zash@zash.se>
parents: 1862
diff changeset
1 ---
188c38c1a711 mod_http_upload/README: Update with XEP reference, stage, description
Kim Alvefur <zash@zash.se>
parents: 1862
diff changeset
2 description: HTTP File Upload
2284
1266f5c17c0d mod_http_upload: Mention modules_enabled, but no example
Kim Alvefur <zash@zash.se>
parents: 2215
diff changeset
3 labels: 'Stage-Alpha'
1266f5c17c0d mod_http_upload: Mention modules_enabled, but no example
Kim Alvefur <zash@zash.se>
parents: 2215
diff changeset
4 ---
1913
188c38c1a711 mod_http_upload/README: Update with XEP reference, stage, description
Kim Alvefur <zash@zash.se>
parents: 1862
diff changeset
5
1816
e5d723afd6ba mod_http_upload: Add README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
6 Introduction
e5d723afd6ba mod_http_upload: Add README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
7 ============
e5d723afd6ba mod_http_upload: Add README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
8
2641
2d83e6c8160b mod_http_upload: add support for XEP-0363 version 0.3
Emmanuel Gil Peyrot <linkmauve@linkmauve.fr>
parents: 2326
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: 2326
diff changeset
10 clients upload files over HTTP.
1816
e5d723afd6ba mod_http_upload: Add README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
11
e5d723afd6ba mod_http_upload: Add README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
12 Configuration
e5d723afd6ba mod_http_upload: Add README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
13 =============
e5d723afd6ba mod_http_upload: Add README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
14
1840
3bd265f7a95f mod_http_upload/README: Point to Prosodys HTTP docs
Kim Alvefur <zash@zash.se>
parents: 1816
diff changeset
15 mod\_http\_upload relies on Prosodys HTTP server and mod\_http for
2284
1266f5c17c0d mod_http_upload: Mention modules_enabled, but no example
Kim Alvefur <zash@zash.se>
parents: 2215
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: 2215
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: 2215
diff changeset
18
1266f5c17c0d mod_http_upload: Mention modules_enabled, but no example
Kim Alvefur <zash@zash.se>
parents: 2215
diff changeset
19 The module can be added as a new Component definition:
1840
3bd265f7a95f mod_http_upload/README: Point to Prosodys HTTP docs
Kim Alvefur <zash@zash.se>
parents: 1816
diff changeset
20
2284
1266f5c17c0d mod_http_upload: Mention modules_enabled, but no example
Kim Alvefur <zash@zash.se>
parents: 2215
diff changeset
21 ``` {.lua}
1266f5c17c0d mod_http_upload: Mention modules_enabled, but no example
Kim Alvefur <zash@zash.se>
parents: 2215
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: 2215
diff changeset
23 ```
1816
e5d723afd6ba mod_http_upload: Add README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
24
3838
9f0c10bd4633 mod_http_upload: Recommend against adding to modules_enabled
Matthew Wild <mwild1@gmail.com>
parents: 3441
diff changeset
25 It should **not** be added to modules_enabled.
1816
e5d723afd6ba mod_http_upload: Add README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
26
3960
c8e4efef5cdb mod_http_upload/README: Add example disco_items use
Kim Alvefur <zash@zash.se>
parents: 3838
diff changeset
27 ## Discoverability
c8e4efef5cdb mod_http_upload/README: Add example disco_items use
Kim Alvefur <zash@zash.se>
parents: 3838
diff changeset
28
c8e4efef5cdb mod_http_upload/README: Add example disco_items use
Kim Alvefur <zash@zash.se>
parents: 3838
diff changeset
29 Prosody makes subdomains of your VirtualHosts easily discoverable by
c8e4efef5cdb mod_http_upload/README: Add example disco_items use
Kim Alvefur <zash@zash.se>
parents: 3838
diff changeset
30 clients. To make the component discoverable by other hosts, use
c8e4efef5cdb mod_http_upload/README: Add example disco_items use
Kim Alvefur <zash@zash.se>
parents: 3838
diff changeset
31 [`disco_items`][doc:modules:mod_disco#configuration].
c8e4efef5cdb mod_http_upload/README: Add example disco_items use
Kim Alvefur <zash@zash.se>
parents: 3838
diff changeset
32
c8e4efef5cdb mod_http_upload/README: Add example disco_items use
Kim Alvefur <zash@zash.se>
parents: 3838
diff changeset
33 ``` {.lua}
c8e4efef5cdb mod_http_upload/README: Add example disco_items use
Kim Alvefur <zash@zash.se>
parents: 3838
diff changeset
34 VirtualHost "foo.example.org"
c8e4efef5cdb mod_http_upload/README: Add example disco_items use
Kim Alvefur <zash@zash.se>
parents: 3838
diff changeset
35 disco_items = {
c8e4efef5cdb mod_http_upload/README: Add example disco_items use
Kim Alvefur <zash@zash.se>
parents: 3838
diff changeset
36 { "upload.example.com" },
c8e4efef5cdb mod_http_upload/README: Add example disco_items use
Kim Alvefur <zash@zash.se>
parents: 3838
diff changeset
37 }
c8e4efef5cdb mod_http_upload/README: Add example disco_items use
Kim Alvefur <zash@zash.se>
parents: 3838
diff changeset
38 ```
c8e4efef5cdb mod_http_upload/README: Add example disco_items use
Kim Alvefur <zash@zash.se>
parents: 3838
diff changeset
39
4443
0a56dc6c61af mod_http_upload: Add access config option
Nicolas Cedilnik <nicoco@nicoco.fr>
parents: 4070
diff changeset
40 ## Access
0a56dc6c61af mod_http_upload: Add access config option
Nicolas Cedilnik <nicoco@nicoco.fr>
parents: 4070
diff changeset
41
0a56dc6c61af mod_http_upload: Add access config option
Nicolas Cedilnik <nicoco@nicoco.fr>
parents: 4070
diff changeset
42 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: 4070
diff changeset
43 by using the `http_upload_access` config option.
0a56dc6c61af mod_http_upload: Add access config option
Nicolas Cedilnik <nicoco@nicoco.fr>
parents: 4070
diff changeset
44
0a56dc6c61af mod_http_upload: Add access config option
Nicolas Cedilnik <nicoco@nicoco.fr>
parents: 4070
diff changeset
45 ``` {.lua}
0a56dc6c61af mod_http_upload: Add access config option
Nicolas Cedilnik <nicoco@nicoco.fr>
parents: 4070
diff changeset
46 http_upload_access = {"gateway.example.com"};
0a56dc6c61af mod_http_upload: Add access config option
Nicolas Cedilnik <nicoco@nicoco.fr>
parents: 4070
diff changeset
47 ```
0a56dc6c61af mod_http_upload: Add access config option
Nicolas Cedilnik <nicoco@nicoco.fr>
parents: 4070
diff changeset
48
1851
03c5639882a7 mod_http_upload: Add support for a file size limit
Kim Alvefur <zash@zash.se>
parents: 1847
diff changeset
49 Limits
03c5639882a7 mod_http_upload: Add support for a file size limit
Kim Alvefur <zash@zash.se>
parents: 1847
diff changeset
50 ------
03c5639882a7 mod_http_upload: Add support for a file size limit
Kim Alvefur <zash@zash.se>
parents: 1847
diff changeset
51
2679
5f60dd12dbb8 mod_http_upload/README: Add sub-headings under limits
Kim Alvefur <zash@zash.se>
parents: 2678
diff changeset
52 ### Max size
5f60dd12dbb8 mod_http_upload/README: Add sub-headings under limits
Kim Alvefur <zash@zash.se>
parents: 2678
diff changeset
53
1851
03c5639882a7 mod_http_upload: Add support for a file size limit
Kim Alvefur <zash@zash.se>
parents: 1847
diff changeset
54 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: 1847
diff changeset
55
03c5639882a7 mod_http_upload: Add support for a file size limit
Kim Alvefur <zash@zash.se>
parents: 1847
diff changeset
56 ``` {.lua}
2052
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: 1967
diff changeset
57 http_upload_file_size_limit = 123 -- bytes
1851
03c5639882a7 mod_http_upload: Add support for a file size limit
Kim Alvefur <zash@zash.se>
parents: 1847
diff changeset
58 ```
03c5639882a7 mod_http_upload: Add support for a file size limit
Kim Alvefur <zash@zash.se>
parents: 1847
diff changeset
59
2284
1266f5c17c0d mod_http_upload: Mention modules_enabled, but no example
Kim Alvefur <zash@zash.se>
parents: 2215
diff changeset
60 Default is 1MB (1024\*1024).
2052
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: 1967
diff changeset
61
2326
8fad27d568aa mod_http_upload/README: Mention the new HTTP parser limit on body/upload size
Kim Alvefur <zash@zash.se>
parents: 2284
diff changeset
62 This can not be set over the value of `http_max_content_size` (default 10M).
2948
7646f565c8ca mod_http_upload/README: Point at mod_http_upload_external
Kim Alvefur <zash@zash.se>
parents: 2731
diff changeset
63 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: 2731
diff changeset
64 this limit.
2326
8fad27d568aa mod_http_upload/README: Mention the new HTTP parser limit on body/upload size
Kim Alvefur <zash@zash.se>
parents: 2284
diff changeset
65
2679
5f60dd12dbb8 mod_http_upload/README: Add sub-headings under limits
Kim Alvefur <zash@zash.se>
parents: 2678
diff changeset
66 ### Max age
5f60dd12dbb8 mod_http_upload/README: Add sub-headings under limits
Kim Alvefur <zash@zash.se>
parents: 2678
diff changeset
67
2677
6daaa1ad2559 mod_http_upload: Add option for expiry of files after a configurable time (closes #557)
Kim Alvefur <zash@zash.se>
parents: 2641
diff changeset
68 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: 2641
diff changeset
69
6daaa1ad2559 mod_http_upload: Add option for expiry of files after a configurable time (closes #557)
Kim Alvefur <zash@zash.se>
parents: 2641
diff changeset
70 ``` lua
6daaa1ad2559 mod_http_upload: Add option for expiry of files after a configurable time (closes #557)
Kim Alvefur <zash@zash.se>
parents: 2641
diff changeset
71 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: 2641
diff changeset
72 ```
6daaa1ad2559 mod_http_upload: Add option for expiry of files after a configurable time (closes #557)
Kim Alvefur <zash@zash.se>
parents: 2641
diff changeset
73
3439
5912f3bacdb4 mod_http_upload: Clarify when expiry is checked
Kim Alvefur <zash@zash.se>
parents: 2948
diff changeset
74 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: 2948
diff changeset
75
3440
64d1af33084f mod_http_upload: Document prosodyctl command for expiring uploads
Kim Alvefur <zash@zash.se>
parents: 3439
diff changeset
76 A command exists to invoke expiry:
64d1af33084f mod_http_upload: Document prosodyctl command for expiring uploads
Kim Alvefur <zash@zash.se>
parents: 3439
diff changeset
77
64d1af33084f mod_http_upload: Document prosodyctl command for expiring uploads
Kim Alvefur <zash@zash.se>
parents: 3439
diff changeset
78 ```
3963
acd231e2b46f mod_http_upload/README: User/host arguments to command not optional (thanks kaliko)
Kim Alvefur <zash@zash.se>
parents: 3960
diff changeset
79 prosodyctl mod_http_upload expire [list of users or hosts]
3440
64d1af33084f mod_http_upload: Document prosodyctl command for expiring uploads
Kim Alvefur <zash@zash.se>
parents: 3439
diff changeset
80 ```
64d1af33084f mod_http_upload: Document prosodyctl command for expiring uploads
Kim Alvefur <zash@zash.se>
parents: 3439
diff changeset
81
2679
5f60dd12dbb8 mod_http_upload/README: Add sub-headings under limits
Kim Alvefur <zash@zash.se>
parents: 2678
diff changeset
82 ### User quota
5f60dd12dbb8 mod_http_upload/README: Add sub-headings under limits
Kim Alvefur <zash@zash.se>
parents: 2678
diff changeset
83
2678
2dec7cad9218 mod_http_upload: Implement quota support (closes #823)
Kim Alvefur <zash@zash.se>
parents: 2677
diff changeset
84 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: 2677
diff changeset
85
2dec7cad9218 mod_http_upload: Implement quota support (closes #823)
Kim Alvefur <zash@zash.se>
parents: 2677
diff changeset
86 ``` lua
2dec7cad9218 mod_http_upload: Implement quota support (closes #823)
Kim Alvefur <zash@zash.se>
parents: 2677
diff changeset
87 http_upload_quota = 1234 -- bytes
2dec7cad9218 mod_http_upload: Implement quota support (closes #823)
Kim Alvefur <zash@zash.se>
parents: 2677
diff changeset
88 ```
2dec7cad9218 mod_http_upload: Implement quota support (closes #823)
Kim Alvefur <zash@zash.se>
parents: 2677
diff changeset
89
3441
0bff7d5ca81d mod_http_upload: Clarify how quotas affect upload requests
Kim Alvefur <zash@zash.se>
parents: 3440
diff changeset
90 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: 3440
diff changeset
91
1967
2ce2b194d501 mod_http_upload: Make file system path configurable
Kim Alvefur <zash@zash.se>
parents: 1913
diff changeset
92 Path
2ce2b194d501 mod_http_upload: Make file system path configurable
Kim Alvefur <zash@zash.se>
parents: 1913
diff changeset
93 ----
2ce2b194d501 mod_http_upload: Make file system path configurable
Kim Alvefur <zash@zash.se>
parents: 1913
diff changeset
94
2ce2b194d501 mod_http_upload: Make file system path configurable
Kim Alvefur <zash@zash.se>
parents: 1913
diff changeset
95 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: 1913
diff changeset
96 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: 1913
diff changeset
97
2ce2b194d501 mod_http_upload: Make file system path configurable
Kim Alvefur <zash@zash.se>
parents: 1913
diff changeset
98 ``` {.lua}
4070
268fa9d45840 mod_http_upload/README: Fix typo (thanks bjoernb)
Kim Alvefur <zash@zash.se>
parents: 3963
diff changeset
99 http_upload_path = "/path/to/uploaded/files"
1967
2ce2b194d501 mod_http_upload: Make file system path configurable
Kim Alvefur <zash@zash.se>
parents: 1913
diff changeset
100 ```
2ce2b194d501 mod_http_upload: Make file system path configurable
Kim Alvefur <zash@zash.se>
parents: 1913
diff changeset
101
1847
cd98a1103ecf mod_http_upload/README: Say it works with 0.9+
Kim Alvefur <zash@zash.se>
parents: 1840
diff changeset
102 Compatibility
cd98a1103ecf mod_http_upload/README: Say it works with 0.9+
Kim Alvefur <zash@zash.se>
parents: 1840
diff changeset
103 =============
cd98a1103ecf mod_http_upload/README: Say it works with 0.9+
Kim Alvefur <zash@zash.se>
parents: 1840
diff changeset
104
cd98a1103ecf mod_http_upload/README: Say it works with 0.9+
Kim Alvefur <zash@zash.se>
parents: 1840
diff changeset
105 Works with Prosody 0.9.x and later.