Mercurial > prosody-modules

annotate mod_http_upload/README.markdown @ 5785:671a6ad1f026

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_http_admin_api: Fix some luacheck warnings and code style issues
author Matthew Wild <mwild1@gmail.com>
date Thu, 07 Dec 2023 15:43:16 +0000
parents f07c9a6f19b3
children 694b62d8a82f
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
4617
260a33eabbd3 mod_http_upload: More emphasis on conditionality of disco_items
Kim Alvefur <zash@zash.se>
parents: 4443
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: 4443
diff changeset
31 component is **not a subdomain** of the VirtualHost, you can use
3960
c8e4efef5cdb mod_http_upload/README: Add example disco_items use
Kim Alvefur <zash@zash.se>
parents: 3838
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: 3838
diff changeset
33
c8e4efef5cdb mod_http_upload/README: Add example disco_items use
Kim Alvefur <zash@zash.se>
parents: 3838
diff changeset
34 ``` {.lua}
c8e4efef5cdb mod_http_upload/README: Add example disco_items use
Kim Alvefur <zash@zash.se>
parents: 3838
diff changeset
35 VirtualHost "foo.example.org"
c8e4efef5cdb mod_http_upload/README: Add example disco_items use
Kim Alvefur <zash@zash.se>
parents: 3838
diff changeset
36 disco_items = {
c8e4efef5cdb mod_http_upload/README: Add example disco_items use
Kim Alvefur <zash@zash.se>
parents: 3838
diff changeset
37 { "upload.example.com" },
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 ```
c8e4efef5cdb mod_http_upload/README: Add example disco_items use
Kim Alvefur <zash@zash.se>
parents: 3838
diff changeset
40
4443
0a56dc6c61af mod_http_upload: Add access config option
Nicolas Cedilnik <nicoco@nicoco.fr>
parents: 4070
diff changeset
41 ## Access
0a56dc6c61af mod_http_upload: Add access config option
Nicolas Cedilnik <nicoco@nicoco.fr>
parents: 4070
diff changeset
42
0a56dc6c61af mod_http_upload: Add access config option
Nicolas Cedilnik <nicoco@nicoco.fr>
parents: 4070
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: 4070
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: 4070
diff changeset
45
0a56dc6c61af mod_http_upload: Add access config option
Nicolas Cedilnik <nicoco@nicoco.fr>
parents: 4070
diff changeset
46 ``` {.lua}
0a56dc6c61af mod_http_upload: Add access config option
Nicolas Cedilnik <nicoco@nicoco.fr>
parents: 4070
diff changeset
47 http_upload_access = {"gateway.example.com"};
0a56dc6c61af mod_http_upload: Add access config option
Nicolas Cedilnik <nicoco@nicoco.fr>
parents: 4070
diff changeset
48 ```
0a56dc6c61af mod_http_upload: Add access config option
Nicolas Cedilnik <nicoco@nicoco.fr>
parents: 4070
diff changeset
49
1851
03c5639882a7 mod_http_upload: Add support for a file size limit
Kim Alvefur <zash@zash.se>
parents: 1847
diff changeset
50 Limits
03c5639882a7 mod_http_upload: Add support for a file size limit
Kim Alvefur <zash@zash.se>
parents: 1847
diff changeset
51 ------
03c5639882a7 mod_http_upload: Add support for a file size limit
Kim Alvefur <zash@zash.se>
parents: 1847
diff changeset
52
2679
5f60dd12dbb8 mod_http_upload/README: Add sub-headings under limits
Kim Alvefur <zash@zash.se>
parents: 2678
diff changeset
53 ### Max size
5f60dd12dbb8 mod_http_upload/README: Add sub-headings under limits
Kim Alvefur <zash@zash.se>
parents: 2678
diff changeset
54
1851
03c5639882a7 mod_http_upload: Add support for a file size limit
Kim Alvefur <zash@zash.se>
parents: 1847
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: 1847
diff changeset
56
03c5639882a7 mod_http_upload: Add support for a file size limit
Kim Alvefur <zash@zash.se>
parents: 1847
diff changeset
57 ``` {.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
58 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
59 ```
03c5639882a7 mod_http_upload: Add support for a file size limit
Kim Alvefur <zash@zash.se>
parents: 1847
diff changeset
60
2284
1266f5c17c0d mod_http_upload: Mention modules_enabled, but no example
Kim Alvefur <zash@zash.se>
parents: 2215
diff changeset
61 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
62
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
63 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
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: 2731
diff changeset
65 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
66
2679
5f60dd12dbb8 mod_http_upload/README: Add sub-headings under limits
Kim Alvefur <zash@zash.se>
parents: 2678
diff changeset
67 ### Max age
5f60dd12dbb8 mod_http_upload/README: Add sub-headings under limits
Kim Alvefur <zash@zash.se>
parents: 2678
diff changeset
68
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
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: 2641
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: 2641
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: 2641
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: 2641
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: 2641
diff changeset
74
3439
5912f3bacdb4 mod_http_upload: Clarify when expiry is checked
Kim Alvefur <zash@zash.se>
parents: 2948
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: 2948
diff changeset
76
3440
64d1af33084f mod_http_upload: Document prosodyctl command for expiring uploads
Kim Alvefur <zash@zash.se>
parents: 3439
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: 3439
diff changeset
78
64d1af33084f mod_http_upload: Document prosodyctl command for expiring uploads
Kim Alvefur <zash@zash.se>
parents: 3439
diff changeset
79 ```
3963
acd231e2b46f mod_http_upload/README: User/host arguments to command not optional (thanks kaliko)
Kim Alvefur <zash@zash.se>
parents: 3960
diff changeset
80 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
81 ```
64d1af33084f mod_http_upload: Document prosodyctl command for expiring uploads
Kim Alvefur <zash@zash.se>
parents: 3439
diff changeset
82
2679
5f60dd12dbb8 mod_http_upload/README: Add sub-headings under limits
Kim Alvefur <zash@zash.se>
parents: 2678
diff changeset
83 ### User quota
5f60dd12dbb8 mod_http_upload/README: Add sub-headings under limits
Kim Alvefur <zash@zash.se>
parents: 2678
diff changeset
84
2678
2dec7cad9218 mod_http_upload: Implement quota support (closes #823)
Kim Alvefur <zash@zash.se>
parents: 2677
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: 2677
diff changeset
86
2dec7cad9218 mod_http_upload: Implement quota support (closes #823)
Kim Alvefur <zash@zash.se>
parents: 2677
diff changeset
87 ``` lua
2dec7cad9218 mod_http_upload: Implement quota support (closes #823)
Kim Alvefur <zash@zash.se>
parents: 2677
diff changeset
88 http_upload_quota = 1234 -- bytes
2dec7cad9218 mod_http_upload: Implement quota support (closes #823)
Kim Alvefur <zash@zash.se>
parents: 2677
diff changeset
89 ```
2dec7cad9218 mod_http_upload: Implement quota support (closes #823)
Kim Alvefur <zash@zash.se>
parents: 2677
diff changeset
90
3441
0bff7d5ca81d mod_http_upload: Clarify how quotas affect upload requests
Kim Alvefur <zash@zash.se>
parents: 3440
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: 3440
diff changeset
92
1967
2ce2b194d501 mod_http_upload: Make file system path configurable
Kim Alvefur <zash@zash.se>
parents: 1913
diff changeset
93 Path
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
2ce2b194d501 mod_http_upload: Make file system path configurable
Kim Alvefur <zash@zash.se>
parents: 1913
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: 1913
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: 1913
diff changeset
98
2ce2b194d501 mod_http_upload: Make file system path configurable
Kim Alvefur <zash@zash.se>
parents: 1913
diff changeset
99 ``` {.lua}
4070
268fa9d45840 mod_http_upload/README: Fix typo (thanks bjoernb)
Kim Alvefur <zash@zash.se>
parents: 3963
diff changeset
100 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
101 ```
2ce2b194d501 mod_http_upload: Make file system path configurable
Kim Alvefur <zash@zash.se>
parents: 1913
diff changeset
102
1847
cd98a1103ecf mod_http_upload/README: Say it works with 0.9+
Kim Alvefur <zash@zash.se>
parents: 1840
diff changeset
103 Compatibility
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
4906
f07c9a6f19b3 mod_http_upload: Update compatibility information
Matthew Wild <mwild1@gmail.com>
parents: 4617
diff changeset
106 Works with Prosody 0.11.x and later.
f07c9a6f19b3 mod_http_upload: Update compatibility information
Matthew Wild <mwild1@gmail.com>
parents: 4617
diff changeset
107
f07c9a6f19b3 mod_http_upload: Update compatibility information
Matthew Wild <mwild1@gmail.com>
parents: 4617
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: 4617
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: 4617
diff changeset
110 [mod_migrate_http_upload](https://modules.prosody.im/mod_migrate_http_upload.html).