annotate mod_http_upload/README.markdown @ 3512:5fb14ae57b4c

mod_pubsub_github/README: Mark up options as code snippets
author Kim Alvefur <zash@zash.se>
date Sun, 31 Mar 2019 16:59:08 +0200
parents 0bff7d5ca81d
children 9f0c10bd4633
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
2284
1266f5c17c0d mod_http_upload: Mention modules_enabled, but no example
Kim Alvefur <zash@zash.se>
parents: 2215
diff changeset
25 Alternatively it can be added to `modules_enabled` like other modules.
1816
e5d723afd6ba mod_http_upload: Add README
Kim Alvefur <zash@zash.se>
parents:
diff changeset
26
1851
03c5639882a7 mod_http_upload: Add support for a file size limit
Kim Alvefur <zash@zash.se>
parents: 1847
diff changeset
27 Limits
03c5639882a7 mod_http_upload: Add support for a file size limit
Kim Alvefur <zash@zash.se>
parents: 1847
diff changeset
28 ------
03c5639882a7 mod_http_upload: Add support for a file size limit
Kim Alvefur <zash@zash.se>
parents: 1847
diff changeset
29
2679
5f60dd12dbb8 mod_http_upload/README: Add sub-headings under limits
Kim Alvefur <zash@zash.se>
parents: 2678
diff changeset
30 ### Max size
5f60dd12dbb8 mod_http_upload/README: Add sub-headings under limits
Kim Alvefur <zash@zash.se>
parents: 2678
diff changeset
31
1851
03c5639882a7 mod_http_upload: Add support for a file size limit
Kim Alvefur <zash@zash.se>
parents: 1847
diff changeset
32 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
33
03c5639882a7 mod_http_upload: Add support for a file size limit
Kim Alvefur <zash@zash.se>
parents: 1847
diff changeset
34 ``` {.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
35 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
36 ```
03c5639882a7 mod_http_upload: Add support for a file size limit
Kim Alvefur <zash@zash.se>
parents: 1847
diff changeset
37
2284
1266f5c17c0d mod_http_upload: Mention modules_enabled, but no example
Kim Alvefur <zash@zash.se>
parents: 2215
diff changeset
38 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
39
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
40 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
41 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
42 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
43
2679
5f60dd12dbb8 mod_http_upload/README: Add sub-headings under limits
Kim Alvefur <zash@zash.se>
parents: 2678
diff changeset
44 ### Max age
5f60dd12dbb8 mod_http_upload/README: Add sub-headings under limits
Kim Alvefur <zash@zash.se>
parents: 2678
diff changeset
45
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
46 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
47
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
48 ``` 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
49 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
50 ```
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
51
3439
5912f3bacdb4 mod_http_upload: Clarify when expiry is checked
Kim Alvefur <zash@zash.se>
parents: 2948
diff changeset
52 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
53
3440
64d1af33084f mod_http_upload: Document prosodyctl command for expiring uploads
Kim Alvefur <zash@zash.se>
parents: 3439
diff changeset
54 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
55
64d1af33084f mod_http_upload: Document prosodyctl command for expiring uploads
Kim Alvefur <zash@zash.se>
parents: 3439
diff changeset
56 ```
64d1af33084f mod_http_upload: Document prosodyctl command for expiring uploads
Kim Alvefur <zash@zash.se>
parents: 3439
diff changeset
57 prosodyctl mod_http_upload expire [optional list of users]
64d1af33084f mod_http_upload: Document prosodyctl command for expiring uploads
Kim Alvefur <zash@zash.se>
parents: 3439
diff changeset
58 ```
64d1af33084f mod_http_upload: Document prosodyctl command for expiring uploads
Kim Alvefur <zash@zash.se>
parents: 3439
diff changeset
59
2679
5f60dd12dbb8 mod_http_upload/README: Add sub-headings under limits
Kim Alvefur <zash@zash.se>
parents: 2678
diff changeset
60 ### User quota
5f60dd12dbb8 mod_http_upload/README: Add sub-headings under limits
Kim Alvefur <zash@zash.se>
parents: 2678
diff changeset
61
2678
2dec7cad9218 mod_http_upload: Implement quota support (closes #823)
Kim Alvefur <zash@zash.se>
parents: 2677
diff changeset
62 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
63
2dec7cad9218 mod_http_upload: Implement quota support (closes #823)
Kim Alvefur <zash@zash.se>
parents: 2677
diff changeset
64 ``` lua
2dec7cad9218 mod_http_upload: Implement quota support (closes #823)
Kim Alvefur <zash@zash.se>
parents: 2677
diff changeset
65 http_upload_quota = 1234 -- bytes
2dec7cad9218 mod_http_upload: Implement quota support (closes #823)
Kim Alvefur <zash@zash.se>
parents: 2677
diff changeset
66 ```
2dec7cad9218 mod_http_upload: Implement quota support (closes #823)
Kim Alvefur <zash@zash.se>
parents: 2677
diff changeset
67
3441
0bff7d5ca81d mod_http_upload: Clarify how quotas affect upload requests
Kim Alvefur <zash@zash.se>
parents: 3440
diff changeset
68 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
69
1967
2ce2b194d501 mod_http_upload: Make file system path configurable
Kim Alvefur <zash@zash.se>
parents: 1913
diff changeset
70 Path
2ce2b194d501 mod_http_upload: Make file system path configurable
Kim Alvefur <zash@zash.se>
parents: 1913
diff changeset
71 ----
2ce2b194d501 mod_http_upload: Make file system path configurable
Kim Alvefur <zash@zash.se>
parents: 1913
diff changeset
72
2ce2b194d501 mod_http_upload: Make file system path configurable
Kim Alvefur <zash@zash.se>
parents: 1913
diff changeset
73 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
74 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
75
2ce2b194d501 mod_http_upload: Make file system path configurable
Kim Alvefur <zash@zash.se>
parents: 1913
diff changeset
76 ``` {.lua}
2ce2b194d501 mod_http_upload: Make file system path configurable
Kim Alvefur <zash@zash.se>
parents: 1913
diff changeset
77 http_upload_path = "/path/to/uploded/files"
2ce2b194d501 mod_http_upload: Make file system path configurable
Kim Alvefur <zash@zash.se>
parents: 1913
diff changeset
78 ```
2ce2b194d501 mod_http_upload: Make file system path configurable
Kim Alvefur <zash@zash.se>
parents: 1913
diff changeset
79
1847
cd98a1103ecf mod_http_upload/README: Say it works with 0.9+
Kim Alvefur <zash@zash.se>
parents: 1840
diff changeset
80 Compatibility
cd98a1103ecf mod_http_upload/README: Say it works with 0.9+
Kim Alvefur <zash@zash.se>
parents: 1840
diff changeset
81 =============
cd98a1103ecf mod_http_upload/README: Say it works with 0.9+
Kim Alvefur <zash@zash.se>
parents: 1840
diff changeset
82
cd98a1103ecf mod_http_upload/README: Say it works with 0.9+
Kim Alvefur <zash@zash.se>
parents: 1840
diff changeset
83 Works with Prosody 0.9.x and later.