Software `/` code `/` prosody-modules

Annotate

mod_http_upload/README.markdown @ 5931:d194d1012fd3

Updating dox for mod_rest. Ideas expressed / clarified: 1) Making clear that mod_rest isn't to be installed under VirtualHosts AND as a component. 2) Understanding some of the implications of this choice: A) Changes to user authentication B) How it affects subdomains 3) More consistent use of domain names for clarity. 4) Using different heading sizes to show scope of section. Essentially, I added all the tidbits I had to clarify in getting this to work in my own example.

author	Ben Smith <bens@effortlessis.com>
date	Mon, 13 May 2024 13:25:13 -0700
parent	5923:694b62d8a82f

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
5923 694b62d8a82f various/README: Fix 'labels' metadata, should be a list Kim Alvefur <zash@zash.se> parents: 4906 diff changeset	3 labels:
694b62d8a82f various/README: Fix 'labels' metadata, should be a list Kim Alvefur <zash@zash.se> parents: 4906 diff changeset	4 - Stage-Alpha
2284 1266f5c17c0d mod_http_upload: Mention modules_enabled, but no example Kim Alvefur <zash@zash.se> parents: 2215 diff changeset	5 ---
1913 188c38c1a711 mod_http_upload/README: Update with XEP reference, stage, description Kim Alvefur <zash@zash.se> parents: 1862 diff changeset	6
1816 e5d723afd6ba mod_http_upload: Add README Kim Alvefur <zash@zash.se> parents: diff changeset	7 Introduction
e5d723afd6ba mod_http_upload: Add README Kim Alvefur <zash@zash.se> parents: diff changeset	8 ============
e5d723afd6ba mod_http_upload: Add README Kim Alvefur <zash@zash.se> parents: diff changeset	9
2641 2d83e6c8160b mod_http_upload: add support for XEP-0363 version 0.3 Emmanuel Gil Peyrot <linkmauve@linkmauve.fr> parents: 2326 diff changeset	10 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	11 clients upload files over HTTP.
1816 e5d723afd6ba mod_http_upload: Add README Kim Alvefur <zash@zash.se> parents: diff changeset	12
e5d723afd6ba mod_http_upload: Add README Kim Alvefur <zash@zash.se> parents: diff changeset	13 Configuration
e5d723afd6ba mod_http_upload: Add README Kim Alvefur <zash@zash.se> parents: diff changeset	14 =============
e5d723afd6ba mod_http_upload: Add README Kim Alvefur <zash@zash.se> parents: diff changeset	15
1840 3bd265f7a95f mod_http_upload/README: Point to Prosodys HTTP docs Kim Alvefur <zash@zash.se> parents: 1816 diff changeset	16 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	17 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	18 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	19
1266f5c17c0d mod_http_upload: Mention modules_enabled, but no example Kim Alvefur <zash@zash.se> parents: 2215 diff changeset	20 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	21
2284 1266f5c17c0d mod_http_upload: Mention modules_enabled, but no example Kim Alvefur <zash@zash.se> parents: 2215 diff changeset	22 ``` {.lua}
1266f5c17c0d mod_http_upload: Mention modules_enabled, but no example Kim Alvefur <zash@zash.se> parents: 2215 diff changeset	23 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	24 ```
1816 e5d723afd6ba mod_http_upload: Add README Kim Alvefur <zash@zash.se> parents: diff changeset	25
3838 9f0c10bd4633 mod_http_upload: Recommend against adding to modules_enabled Matthew Wild <mwild1@gmail.com> parents: 3441 diff changeset	26 It should not be added to modules_enabled.
1816 e5d723afd6ba mod_http_upload: Add README Kim Alvefur <zash@zash.se> parents: diff changeset	27
3960 c8e4efef5cdb mod_http_upload/README: Add example disco_items use Kim Alvefur <zash@zash.se> parents: 3838 diff changeset	28 ## Discoverability
c8e4efef5cdb mod_http_upload/README: Add example disco_items use Kim Alvefur <zash@zash.se> parents: 3838 diff changeset	29
c8e4efef5cdb mod_http_upload/README: Add example disco_items use Kim Alvefur <zash@zash.se> parents: 3838 diff changeset	30 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	31 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	32 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	33 [`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	34
c8e4efef5cdb mod_http_upload/README: Add example disco_items use Kim Alvefur <zash@zash.se> parents: 3838 diff changeset	35 ``` {.lua}
c8e4efef5cdb mod_http_upload/README: Add example disco_items use Kim Alvefur <zash@zash.se> parents: 3838 diff changeset	36 VirtualHost "foo.example.org"
c8e4efef5cdb mod_http_upload/README: Add example disco_items use Kim Alvefur <zash@zash.se> parents: 3838 diff changeset	37 disco_items = {
c8e4efef5cdb mod_http_upload/README: Add example disco_items use Kim Alvefur <zash@zash.se> parents: 3838 diff changeset	38 { "upload.example.com" },
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 ```
c8e4efef5cdb mod_http_upload/README: Add example disco_items use Kim Alvefur <zash@zash.se> parents: 3838 diff changeset	41
4443 0a56dc6c61af mod_http_upload: Add access config option Nicolas Cedilnik <nicoco@nicoco.fr> parents: 4070 diff changeset	42 ## Access
0a56dc6c61af mod_http_upload: Add access config option Nicolas Cedilnik <nicoco@nicoco.fr> parents: 4070 diff changeset	43
0a56dc6c61af mod_http_upload: Add access config option Nicolas Cedilnik <nicoco@nicoco.fr> parents: 4070 diff changeset	44 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	45 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	46
0a56dc6c61af mod_http_upload: Add access config option Nicolas Cedilnik <nicoco@nicoco.fr> parents: 4070 diff changeset	47 ``` {.lua}
0a56dc6c61af mod_http_upload: Add access config option Nicolas Cedilnik <nicoco@nicoco.fr> parents: 4070 diff changeset	48 http_upload_access = {"gateway.example.com"};
0a56dc6c61af mod_http_upload: Add access config option Nicolas Cedilnik <nicoco@nicoco.fr> parents: 4070 diff changeset	49 ```
0a56dc6c61af mod_http_upload: Add access config option Nicolas Cedilnik <nicoco@nicoco.fr> parents: 4070 diff changeset	50
1851 03c5639882a7 mod_http_upload: Add support for a file size limit Kim Alvefur <zash@zash.se> parents: 1847 diff changeset	51 Limits
03c5639882a7 mod_http_upload: Add support for a file size limit Kim Alvefur <zash@zash.se> parents: 1847 diff changeset	52 ------
03c5639882a7 mod_http_upload: Add support for a file size limit Kim Alvefur <zash@zash.se> parents: 1847 diff changeset	53
2679 5f60dd12dbb8 mod_http_upload/README: Add sub-headings under limits Kim Alvefur <zash@zash.se> parents: 2678 diff changeset	54 ### Max size
5f60dd12dbb8 mod_http_upload/README: Add sub-headings under limits Kim Alvefur <zash@zash.se> parents: 2678 diff changeset	55
1851 03c5639882a7 mod_http_upload: Add support for a file size limit Kim Alvefur <zash@zash.se> parents: 1847 diff changeset	56 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	57
03c5639882a7 mod_http_upload: Add support for a file size limit Kim Alvefur <zash@zash.se> parents: 1847 diff changeset	58 ``` {.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	59 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	60 ```
03c5639882a7 mod_http_upload: Add support for a file size limit Kim Alvefur <zash@zash.se> parents: 1847 diff changeset	61
2284 1266f5c17c0d mod_http_upload: Mention modules_enabled, but no example Kim Alvefur <zash@zash.se> parents: 2215 diff changeset	62 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	63
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	64 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	65 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	66 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	67
2679 5f60dd12dbb8 mod_http_upload/README: Add sub-headings under limits Kim Alvefur <zash@zash.se> parents: 2678 diff changeset	68 ### Max age
5f60dd12dbb8 mod_http_upload/README: Add sub-headings under limits Kim Alvefur <zash@zash.se> parents: 2678 diff changeset	69
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	70 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	71
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 ``` 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	73 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	74 ```
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	75
3439 5912f3bacdb4 mod_http_upload: Clarify when expiry is checked Kim Alvefur <zash@zash.se> parents: 2948 diff changeset	76 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	77
3440 64d1af33084f mod_http_upload: Document prosodyctl command for expiring uploads Kim Alvefur <zash@zash.se> parents: 3439 diff changeset	78 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	79
64d1af33084f mod_http_upload: Document prosodyctl command for expiring uploads Kim Alvefur <zash@zash.se> parents: 3439 diff changeset	80 ```
3963 acd231e2b46f mod_http_upload/README: User/host arguments to command not optional (thanks kaliko) Kim Alvefur <zash@zash.se> parents: 3960 diff changeset	81 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	82 ```
64d1af33084f mod_http_upload: Document prosodyctl command for expiring uploads Kim Alvefur <zash@zash.se> parents: 3439 diff changeset	83
2679 5f60dd12dbb8 mod_http_upload/README: Add sub-headings under limits Kim Alvefur <zash@zash.se> parents: 2678 diff changeset	84 ### User quota
5f60dd12dbb8 mod_http_upload/README: Add sub-headings under limits Kim Alvefur <zash@zash.se> parents: 2678 diff changeset	85
2678 2dec7cad9218 mod_http_upload: Implement quota support (closes #823) Kim Alvefur <zash@zash.se> parents: 2677 diff changeset	86 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	87
2dec7cad9218 mod_http_upload: Implement quota support (closes #823) Kim Alvefur <zash@zash.se> parents: 2677 diff changeset	88 ``` lua
2dec7cad9218 mod_http_upload: Implement quota support (closes #823) Kim Alvefur <zash@zash.se> parents: 2677 diff changeset	89 http_upload_quota = 1234 -- bytes
2dec7cad9218 mod_http_upload: Implement quota support (closes #823) Kim Alvefur <zash@zash.se> parents: 2677 diff changeset	90 ```
2dec7cad9218 mod_http_upload: Implement quota support (closes #823) Kim Alvefur <zash@zash.se> parents: 2677 diff changeset	91
3441 0bff7d5ca81d mod_http_upload: Clarify how quotas affect upload requests Kim Alvefur <zash@zash.se> parents: 3440 diff changeset	92 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	93
1967 2ce2b194d501 mod_http_upload: Make file system path configurable Kim Alvefur <zash@zash.se> parents: 1913 diff changeset	94 Path
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
2ce2b194d501 mod_http_upload: Make file system path configurable Kim Alvefur <zash@zash.se> parents: 1913 diff changeset	97 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	98 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	99
2ce2b194d501 mod_http_upload: Make file system path configurable Kim Alvefur <zash@zash.se> parents: 1913 diff changeset	100 ``` {.lua}
4070 268fa9d45840 mod_http_upload/README: Fix typo (thanks bjoernb) Kim Alvefur <zash@zash.se> parents: 3963 diff changeset	101 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	102 ```
2ce2b194d501 mod_http_upload: Make file system path configurable Kim Alvefur <zash@zash.se> parents: 1913 diff changeset	103
1847 cd98a1103ecf mod_http_upload/README: Say it works with 0.9+ Kim Alvefur <zash@zash.se> parents: 1840 diff changeset	104 Compatibility
cd98a1103ecf mod_http_upload/README: Say it works with 0.9+ Kim Alvefur <zash@zash.se> parents: 1840 diff changeset	105 =============
cd98a1103ecf mod_http_upload/README: Say it works with 0.9+ Kim Alvefur <zash@zash.se> parents: 1840 diff changeset	106
4906 f07c9a6f19b3 mod_http_upload: Update compatibility information Matthew Wild <mwild1@gmail.com> parents: 4617 diff changeset	107 Works with Prosody 0.11.x and later.
f07c9a6f19b3 mod_http_upload: Update compatibility information Matthew Wild <mwild1@gmail.com> parents: 4617 diff changeset	108
f07c9a6f19b3 mod_http_upload: Update compatibility information Matthew Wild <mwild1@gmail.com> parents: 4617 diff changeset	109 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	110 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	111 [mod_migrate_http_upload](https://modules.prosody.im/mod_migrate_http_upload.html).

prosody-modules

d194d1012fd3

mod_http_upload/README.markdown

Software / code / prosody-modules

Annotate

mod_http_upload/README.markdown @ 5931:d194d1012fd3

Software `/` code `/` prosody-modules