Mercurial > prosody-modules

annotate mod_http_upload/README.markdown @ 4152:87daef9ed4e7

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Improve mod_firewall readme
author Christian Weiske <cweiske@cweiske.de>
date Mon, 21 Sep 2020 21:57:25 +0200
parents 268fa9d45840
children 0a56dc6c61af
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
1851
03c5639882a7 mod_http_upload: Add support for a file size limit
Kim Alvefur <zash@zash.se>
parents: 1847
diff changeset
40 Limits
03c5639882a7 mod_http_upload: Add support for a file size limit
Kim Alvefur <zash@zash.se>
parents: 1847
diff changeset
41 ------
03c5639882a7 mod_http_upload: Add support for a file size limit
Kim Alvefur <zash@zash.se>
parents: 1847
diff changeset
42
2679
5f60dd12dbb8 mod_http_upload/README: Add sub-headings under limits
Kim Alvefur <zash@zash.se>
parents: 2678
diff changeset
43 ### Max size
5f60dd12dbb8 mod_http_upload/README: Add sub-headings under limits
Kim Alvefur <zash@zash.se>
parents: 2678
diff changeset
44
1851
03c5639882a7 mod_http_upload: Add support for a file size limit
Kim Alvefur <zash@zash.se>
parents: 1847
diff changeset
45 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
46
03c5639882a7 mod_http_upload: Add support for a file size limit
Kim Alvefur <zash@zash.se>
parents: 1847
diff changeset
47 ``` {.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
48 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
49 ```
03c5639882a7 mod_http_upload: Add support for a file size limit
Kim Alvefur <zash@zash.se>
parents: 1847
diff changeset
50
2284
1266f5c17c0d mod_http_upload: Mention modules_enabled, but no example
Kim Alvefur <zash@zash.se>
parents: 2215
diff changeset
51 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
52
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
53 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
54 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
55 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
56
2679
5f60dd12dbb8 mod_http_upload/README: Add sub-headings under limits
Kim Alvefur <zash@zash.se>
parents: 2678
diff changeset
57 ### Max age
5f60dd12dbb8 mod_http_upload/README: Add sub-headings under limits
Kim Alvefur <zash@zash.se>
parents: 2678
diff changeset
58
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
59 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
60
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
61 ``` 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
62 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
63 ```
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
64
3439
5912f3bacdb4 mod_http_upload: Clarify when expiry is checked
Kim Alvefur <zash@zash.se>
parents: 2948
diff changeset
65 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
66
3440
64d1af33084f mod_http_upload: Document prosodyctl command for expiring uploads
Kim Alvefur <zash@zash.se>
parents: 3439
diff changeset
67 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
68
64d1af33084f mod_http_upload: Document prosodyctl command for expiring uploads
Kim Alvefur <zash@zash.se>
parents: 3439
diff changeset
69 ```
3963
acd231e2b46f mod_http_upload/README: User/host arguments to command not optional (thanks kaliko)
Kim Alvefur <zash@zash.se>
parents: 3960
diff changeset
70 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
71 ```
64d1af33084f mod_http_upload: Document prosodyctl command for expiring uploads
Kim Alvefur <zash@zash.se>
parents: 3439
diff changeset
72
2679
5f60dd12dbb8 mod_http_upload/README: Add sub-headings under limits
Kim Alvefur <zash@zash.se>
parents: 2678
diff changeset
73 ### User quota
5f60dd12dbb8 mod_http_upload/README: Add sub-headings under limits
Kim Alvefur <zash@zash.se>
parents: 2678
diff changeset
74
2678
2dec7cad9218 mod_http_upload: Implement quota support (closes #823)
Kim Alvefur <zash@zash.se>
parents: 2677
diff changeset
75 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
76
2dec7cad9218 mod_http_upload: Implement quota support (closes #823)
Kim Alvefur <zash@zash.se>
parents: 2677
diff changeset
77 ``` lua
2dec7cad9218 mod_http_upload: Implement quota support (closes #823)
Kim Alvefur <zash@zash.se>
parents: 2677
diff changeset
78 http_upload_quota = 1234 -- bytes
2dec7cad9218 mod_http_upload: Implement quota support (closes #823)
Kim Alvefur <zash@zash.se>
parents: 2677
diff changeset
79 ```
2dec7cad9218 mod_http_upload: Implement quota support (closes #823)
Kim Alvefur <zash@zash.se>
parents: 2677
diff changeset
80
3441
0bff7d5ca81d mod_http_upload: Clarify how quotas affect upload requests
Kim Alvefur <zash@zash.se>
parents: 3440
diff changeset
81 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
82
1967
2ce2b194d501 mod_http_upload: Make file system path configurable
Kim Alvefur <zash@zash.se>
parents: 1913
diff changeset
83 Path
2ce2b194d501 mod_http_upload: Make file system path configurable
Kim Alvefur <zash@zash.se>
parents: 1913
diff changeset
84 ----
2ce2b194d501 mod_http_upload: Make file system path configurable
Kim Alvefur <zash@zash.se>
parents: 1913
diff changeset
85
2ce2b194d501 mod_http_upload: Make file system path configurable
Kim Alvefur <zash@zash.se>
parents: 1913
diff changeset
86 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
87 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
88
2ce2b194d501 mod_http_upload: Make file system path configurable
Kim Alvefur <zash@zash.se>
parents: 1913
diff changeset
89 ``` {.lua}
4070
268fa9d45840 mod_http_upload/README: Fix typo (thanks bjoernb)
Kim Alvefur <zash@zash.se>
parents: 3963
diff changeset
90 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
91 ```
2ce2b194d501 mod_http_upload: Make file system path configurable
Kim Alvefur <zash@zash.se>
parents: 1913
diff changeset
92
1847
cd98a1103ecf mod_http_upload/README: Say it works with 0.9+
Kim Alvefur <zash@zash.se>
parents: 1840
diff changeset
93 Compatibility
cd98a1103ecf mod_http_upload/README: Say it works with 0.9+
Kim Alvefur <zash@zash.se>
parents: 1840
diff changeset
94 =============
cd98a1103ecf mod_http_upload/README: Say it works with 0.9+
Kim Alvefur <zash@zash.se>
parents: 1840
diff changeset
95
cd98a1103ecf mod_http_upload/README: Say it works with 0.9+
Kim Alvefur <zash@zash.se>
parents: 1840
diff changeset
96 Works with Prosody 0.9.x and later.