Mercurial > prosody-modules

annotate mod_http_upload/README.markdown @ 5442:7480dde4cd2e

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_auth_oauth_external: Stub not implemented auth module methods Not providing some of these may trigger errors on use, which is something that would be nice to fix on the Prosody side, one day.
author Kim Alvefur <zash@zash.se>
date Wed, 10 May 2023 19:11:25 +0200
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).