Mercurial > prosody-modules

annotate mod_mam/README.markdown @ 2904:788f3616e6a0

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
luacheckrc: Rearrange options to be closer to the order used in main prosody repo
author Kim Alvefur <zash@zash.se>
date Wed, 07 Mar 2018 18:11:08 +0100
parents b8805ab1d470
children 637d63b7398e
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1801
diff changeset
1 ---
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1801
diff changeset
2 labels:
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1801
diff changeset
3 - 'Stage-Beta'
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1801
diff changeset
4 summary: 'XEP-0313: Message Archive Management'
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1801
diff changeset
5 ...
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
6
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1801
diff changeset
7 Introduction
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1801
diff changeset
8 ============
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
9
1978
b91f27f21666 mod_mam/README: Use autolinks
Kim Alvefur <zash@zash.se>
parents: 1976
diff changeset
10 Implementation of [XEP-0313: Message Archive Management].
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1801
diff changeset
11
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1801
diff changeset
12 Details
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1801
diff changeset
13 =======
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
14
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1801
diff changeset
15 This module will archive all messages that match the simple rules setup
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1801
diff changeset
16 by the user, and allow the user to access this archive.
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
17
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1801
diff changeset
18 Usage
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1801
diff changeset
19 =====
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
20
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
21 First copy the module to the prosody plugins directory.
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
22
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1801
diff changeset
23 Then add "mam" to your modules\_enabled list:
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
24
1820
8de50be756e5 Various README files: Correct indentation levels, fix syntax and other small fixes
Kim Alvefur <zash@zash.se>
parents: 1804
diff changeset
25 ``` {.lua}
8de50be756e5 Various README files: Correct indentation levels, fix syntax and other small fixes
Kim Alvefur <zash@zash.se>
parents: 1804
diff changeset
26 modules_enabled = {
8de50be756e5 Various README files: Correct indentation levels, fix syntax and other small fixes
Kim Alvefur <zash@zash.se>
parents: 1804
diff changeset
27 -- ...
8de50be756e5 Various README files: Correct indentation levels, fix syntax and other small fixes
Kim Alvefur <zash@zash.se>
parents: 1804
diff changeset
28 "mam",
8de50be756e5 Various README files: Correct indentation levels, fix syntax and other small fixes
Kim Alvefur <zash@zash.se>
parents: 1804
diff changeset
29 -- ...
8de50be756e5 Various README files: Correct indentation levels, fix syntax and other small fixes
Kim Alvefur <zash@zash.se>
parents: 1804
diff changeset
30 }
8de50be756e5 Various README files: Correct indentation levels, fix syntax and other small fixes
Kim Alvefur <zash@zash.se>
parents: 1804
diff changeset
31 ```
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1801
diff changeset
32
1835
6234e67ebe7a mod_mam/README: Reorganise config options under sub-headings and rewrite description of options
Kim Alvefur <zash@zash.se>
parents: 1820
diff changeset
33 Configuration
6234e67ebe7a mod_mam/README: Reorganise config options under sub-headings and rewrite description of options
Kim Alvefur <zash@zash.se>
parents: 1820
diff changeset
34 =============
6234e67ebe7a mod_mam/README: Reorganise config options under sub-headings and rewrite description of options
Kim Alvefur <zash@zash.se>
parents: 1820
diff changeset
35
2012
cdba975e9b6e mod_mam/README: Add a summary of options
Kim Alvefur <zash@zash.se>
parents: 1978
diff changeset
36 Option summary
cdba975e9b6e mod_mam/README: Add a summary of options
Kim Alvefur <zash@zash.se>
parents: 1978
diff changeset
37 --------------
cdba975e9b6e mod_mam/README: Add a summary of options
Kim Alvefur <zash@zash.se>
parents: 1978
diff changeset
38
cdba975e9b6e mod_mam/README: Add a summary of options
Kim Alvefur <zash@zash.se>
parents: 1978
diff changeset
39 option type default
2022
77b9c7e5fd63 mod_mam: Allow interval between archive cleanup to be changed
Kim Alvefur <zash@zash.se>
parents: 2017
diff changeset
40 ------------------------------ ----------------------- -----------
2012
cdba975e9b6e mod_mam/README: Add a summary of options
Kim Alvefur <zash@zash.se>
parents: 1978
diff changeset
41 max\_archive\_query\_results number `50`
2017
d44ac0756c46 mod_mam: Enable archiving by default, less of a privacy issue if messages expire
Kim Alvefur <zash@zash.se>
parents: 2016
diff changeset
42 default\_archive\_policy boolean or `"roster"` `true`
2016
279885fd9728 mod_mam: Add support for trimming old archived messages
Kim Alvefur <zash@zash.se>
parents: 2015
diff changeset
43 archive\_expires\_after string `"1w"`
2022
77b9c7e5fd63 mod_mam: Allow interval between archive cleanup to be changed
Kim Alvefur <zash@zash.se>
parents: 2017
diff changeset
44 archive\_cleanup\_interval number `4*60*60`
77b9c7e5fd63 mod_mam: Allow interval between archive cleanup to be changed
Kim Alvefur <zash@zash.se>
parents: 2017
diff changeset
45
2012
cdba975e9b6e mod_mam/README: Add a summary of options
Kim Alvefur <zash@zash.se>
parents: 1978
diff changeset
46
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1801
diff changeset
47 Storage backend
1835
6234e67ebe7a mod_mam/README: Reorganise config options under sub-headings and rewrite description of options
Kim Alvefur <zash@zash.se>
parents: 1820
diff changeset
48 ---------------
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
49
2015
7f90692bbd23 mod_mam/README: Fix footnote
Kim Alvefur <zash@zash.se>
parents: 2013
diff changeset
50 mod\_mam uses the store "archive2"[^1]. See [Prosodys data storage
1978
b91f27f21666 mod_mam/README: Use autolinks
Kim Alvefur <zash@zash.se>
parents: 1976
diff changeset
51 documentation][doc:storage] for information on how to configure storage.
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1801
diff changeset
52
2013
a8ec8491fdee mod_mam/README: Point out that mod_storage_sql only supports archives in 0.10
Kim Alvefur <zash@zash.se>
parents: 2012
diff changeset
53 For example, to use mod\_storage\_sql (requires Prosody 0.10 or later):
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
54
1820
8de50be756e5 Various README files: Correct indentation levels, fix syntax and other small fixes
Kim Alvefur <zash@zash.se>
parents: 1804
diff changeset
55 ``` {.lua}
8de50be756e5 Various README files: Correct indentation levels, fix syntax and other small fixes
Kim Alvefur <zash@zash.se>
parents: 1804
diff changeset
56 storage = {
1976
cd36e5bf00b3 Various READMEs: Update to reflect rename of mod_storage_sql2 → mod_storage_sql
Kim Alvefur <zash@zash.se>
parents: 1835
diff changeset
57 archive2 = "sql";
1820
8de50be756e5 Various README files: Correct indentation levels, fix syntax and other small fixes
Kim Alvefur <zash@zash.se>
parents: 1804
diff changeset
58 }
8de50be756e5 Various README files: Correct indentation levels, fix syntax and other small fixes
Kim Alvefur <zash@zash.se>
parents: 1804
diff changeset
59 ```
1801
5abf61915ab4 mod_mam/README: Add example of use with mod_storage_sql2
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
60
2023
98b4794b72e4 mod_mam: Include an in-memory fallback driver
Kim Alvefur <zash@zash.se>
parents: 2022
diff changeset
61 If no archive-capable storage backend can be opened then an in-memory
98b4794b72e4 mod_mam: Include an in-memory fallback driver
Kim Alvefur <zash@zash.se>
parents: 2022
diff changeset
62 one will be used as fallback.
98b4794b72e4 mod_mam: Include an in-memory fallback driver
Kim Alvefur <zash@zash.se>
parents: 2022
diff changeset
63
1835
6234e67ebe7a mod_mam/README: Reorganise config options under sub-headings and rewrite description of options
Kim Alvefur <zash@zash.se>
parents: 1820
diff changeset
64 Query size limits
6234e67ebe7a mod_mam/README: Reorganise config options under sub-headings and rewrite description of options
Kim Alvefur <zash@zash.se>
parents: 1820
diff changeset
65 -----------------
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
66
1804
3228fb928a93 mod_mam/README: Minor fixup
Kim Alvefur <zash@zash.se>
parents: 1803
diff changeset
67 max_archive_query_results = 20;
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
68
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1801
diff changeset
69 This is the largest number of messages that are allowed to be retrieved
1835
6234e67ebe7a mod_mam/README: Reorganise config options under sub-headings and rewrite description of options
Kim Alvefur <zash@zash.se>
parents: 1820
diff changeset
70 in one request *page*. A query that does not fit in one page will
6234e67ebe7a mod_mam/README: Reorganise config options under sub-headings and rewrite description of options
Kim Alvefur <zash@zash.se>
parents: 1820
diff changeset
71 include a reference to the next page, letting clients page through the
2463
e2d955f6167f mod_mam/README: Fix typo
Kim Alvefur <zash@zash.se>
parents: 2037
diff changeset
72 result set. Setting large number is not recommended, as Prosody will be
1835
6234e67ebe7a mod_mam/README: Reorganise config options under sub-headings and rewrite description of options
Kim Alvefur <zash@zash.se>
parents: 1820
diff changeset
73 blocked while processing the request and will not be able to do anything
6234e67ebe7a mod_mam/README: Reorganise config options under sub-headings and rewrite description of options
Kim Alvefur <zash@zash.se>
parents: 1820
diff changeset
74 else.
6234e67ebe7a mod_mam/README: Reorganise config options under sub-headings and rewrite description of options
Kim Alvefur <zash@zash.se>
parents: 1820
diff changeset
75
2016
279885fd9728 mod_mam: Add support for trimming old archived messages
Kim Alvefur <zash@zash.se>
parents: 2015
diff changeset
76 Archive expiry
279885fd9728 mod_mam: Add support for trimming old archived messages
Kim Alvefur <zash@zash.se>
parents: 2015
diff changeset
77 --------------
279885fd9728 mod_mam: Add support for trimming old archived messages
Kim Alvefur <zash@zash.se>
parents: 2015
diff changeset
78
279885fd9728 mod_mam: Add support for trimming old archived messages
Kim Alvefur <zash@zash.se>
parents: 2015
diff changeset
79 Messages in the archive will expire after some time, by default one
279885fd9728 mod_mam: Add support for trimming old archived messages
Kim Alvefur <zash@zash.se>
parents: 2015
diff changeset
80 week. This can be changed by setting `archive_expires_after`:
279885fd9728 mod_mam: Add support for trimming old archived messages
Kim Alvefur <zash@zash.se>
parents: 2015
diff changeset
81
279885fd9728 mod_mam: Add support for trimming old archived messages
Kim Alvefur <zash@zash.se>
parents: 2015
diff changeset
82 ``` {.lua}
279885fd9728 mod_mam: Add support for trimming old archived messages
Kim Alvefur <zash@zash.se>
parents: 2015
diff changeset
83 archive_expires_after = "1d" -- one day
279885fd9728 mod_mam: Add support for trimming old archived messages
Kim Alvefur <zash@zash.se>
parents: 2015
diff changeset
84
279885fd9728 mod_mam: Add support for trimming old archived messages
Kim Alvefur <zash@zash.se>
parents: 2015
diff changeset
85 archive_expires_after = "1w" -- one week, the default
279885fd9728 mod_mam: Add support for trimming old archived messages
Kim Alvefur <zash@zash.se>
parents: 2015
diff changeset
86
279885fd9728 mod_mam: Add support for trimming old archived messages
Kim Alvefur <zash@zash.se>
parents: 2015
diff changeset
87 archive_expires_after = "2m" -- two months
279885fd9728 mod_mam: Add support for trimming old archived messages
Kim Alvefur <zash@zash.se>
parents: 2015
diff changeset
88
279885fd9728 mod_mam: Add support for trimming old archived messages
Kim Alvefur <zash@zash.se>
parents: 2015
diff changeset
89 archive_expires_after = "1y" -- one year
279885fd9728 mod_mam: Add support for trimming old archived messages
Kim Alvefur <zash@zash.se>
parents: 2015
diff changeset
90
279885fd9728 mod_mam: Add support for trimming old archived messages
Kim Alvefur <zash@zash.se>
parents: 2015
diff changeset
91 archive_expires_after = 60 * 60 -- one hour
279885fd9728 mod_mam: Add support for trimming old archived messages
Kim Alvefur <zash@zash.se>
parents: 2015
diff changeset
92
279885fd9728 mod_mam: Add support for trimming old archived messages
Kim Alvefur <zash@zash.se>
parents: 2015
diff changeset
93 archive_expires_after = "never" -- forever
279885fd9728 mod_mam: Add support for trimming old archived messages
Kim Alvefur <zash@zash.se>
parents: 2015
diff changeset
94 ```
279885fd9728 mod_mam: Add support for trimming old archived messages
Kim Alvefur <zash@zash.se>
parents: 2015
diff changeset
95
279885fd9728 mod_mam: Add support for trimming old archived messages
Kim Alvefur <zash@zash.se>
parents: 2015
diff changeset
96 The format is an integer number of seconds or a multiple of a period
279885fd9728 mod_mam: Add support for trimming old archived messages
Kim Alvefur <zash@zash.se>
parents: 2015
diff changeset
97 given by a suffix that can be one of `d` (day), `w` (week), `m` (month)
279885fd9728 mod_mam: Add support for trimming old archived messages
Kim Alvefur <zash@zash.se>
parents: 2015
diff changeset
98 or `y` (year). No multiplier means seconds.
279885fd9728 mod_mam: Add support for trimming old archived messages
Kim Alvefur <zash@zash.se>
parents: 2015
diff changeset
99
1835
6234e67ebe7a mod_mam/README: Reorganise config options under sub-headings and rewrite description of options
Kim Alvefur <zash@zash.se>
parents: 1820
diff changeset
100 Message matching policy
6234e67ebe7a mod_mam/README: Reorganise config options under sub-headings and rewrite description of options
Kim Alvefur <zash@zash.se>
parents: 1820
diff changeset
101 -----------------------
6234e67ebe7a mod_mam/README: Reorganise config options under sub-headings and rewrite description of options
Kim Alvefur <zash@zash.se>
parents: 1820
diff changeset
102
6234e67ebe7a mod_mam/README: Reorganise config options under sub-headings and rewrite description of options
Kim Alvefur <zash@zash.se>
parents: 1820
diff changeset
103 The MAM protocol includes a way for clients to control what messages
6234e67ebe7a mod_mam/README: Reorganise config options under sub-headings and rewrite description of options
Kim Alvefur <zash@zash.se>
parents: 1820
diff changeset
104 should be stored. This allows users to enable or disable archiving by
2017
d44ac0756c46 mod_mam: Enable archiving by default, less of a privacy issue if messages expire
Kim Alvefur <zash@zash.se>
parents: 2016
diff changeset
105 default or for specific contacts.
1835
6234e67ebe7a mod_mam/README: Reorganise config options under sub-headings and rewrite description of options
Kim Alvefur <zash@zash.se>
parents: 1820
diff changeset
106
6234e67ebe7a mod_mam/README: Reorganise config options under sub-headings and rewrite description of options
Kim Alvefur <zash@zash.se>
parents: 1820
diff changeset
107 ``` {.lua}
2017
d44ac0756c46 mod_mam: Enable archiving by default, less of a privacy issue if messages expire
Kim Alvefur <zash@zash.se>
parents: 2016
diff changeset
108 default_archive_policy = true
1835
6234e67ebe7a mod_mam/README: Reorganise config options under sub-headings and rewrite description of options
Kim Alvefur <zash@zash.se>
parents: 1820
diff changeset
109 ```
6234e67ebe7a mod_mam/README: Reorganise config options under sub-headings and rewrite description of options
Kim Alvefur <zash@zash.se>
parents: 1820
diff changeset
110
6234e67ebe7a mod_mam/README: Reorganise config options under sub-headings and rewrite description of options
Kim Alvefur <zash@zash.se>
parents: 1820
diff changeset
111 `default_archive_policy =` Meaning
6234e67ebe7a mod_mam/README: Reorganise config options under sub-headings and rewrite description of options
Kim Alvefur <zash@zash.se>
parents: 1820
diff changeset
112 ---------------------------- ------------------------------------------------------
2037
632aa9f49aed mod_mam/README: Update default_archive_policy table for new default (thanks xnyhps)
Kim Alvefur <zash@zash.se>
parents: 2023
diff changeset
113 `false` Store no messages.
1835
6234e67ebe7a mod_mam/README: Reorganise config options under sub-headings and rewrite description of options
Kim Alvefur <zash@zash.se>
parents: 1820
diff changeset
114 `"roster"` Store messages to/from contacts in the users roster.
2037
632aa9f49aed mod_mam/README: Update default_archive_policy table for new default (thanks xnyhps)
Kim Alvefur <zash@zash.se>
parents: 2023
diff changeset
115 `true` Store all messages. This is the default.
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1801
diff changeset
116
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1801
diff changeset
117 Compatibility
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1801
diff changeset
118 =============
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
119
2499
b8805ab1d470 mod_mam/README: Note that mod_mam is included with prosody 0.10+
Kim Alvefur <zash@zash.se>
parents: 2463
diff changeset
120 ------- -----------------------
b8805ab1d470 mod_mam/README: Note that mod_mam is included with prosody 0.10+
Kim Alvefur <zash@zash.se>
parents: 2463
diff changeset
121 trunk Included with Prosody
b8805ab1d470 mod_mam/README: Note that mod_mam is included with prosody 0.10+
Kim Alvefur <zash@zash.se>
parents: 2463
diff changeset
122 0.10 Included with Prosody
2023
98b4794b72e4 mod_mam: Include an in-memory fallback driver
Kim Alvefur <zash@zash.se>
parents: 2022
diff changeset
123 0.9 Works
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1801
diff changeset
124 0.8 Does not work
2499
b8805ab1d470 mod_mam/README: Note that mod_mam is included with prosody 0.10+
Kim Alvefur <zash@zash.se>
parents: 2463
diff changeset
125 ------- -----------------------
b8805ab1d470 mod_mam/README: Note that mod_mam is included with prosody 0.10+
Kim Alvefur <zash@zash.se>
parents: 2463
diff changeset
126
1835
6234e67ebe7a mod_mam/README: Reorganise config options under sub-headings and rewrite description of options
Kim Alvefur <zash@zash.se>
parents: 1820
diff changeset
127
6234e67ebe7a mod_mam/README: Reorganise config options under sub-headings and rewrite description of options
Kim Alvefur <zash@zash.se>
parents: 1820
diff changeset
128 [^1]: Might be changed to "mam" at some point
6234e67ebe7a mod_mam/README: Reorganise config options under sub-headings and rewrite description of options
Kim Alvefur <zash@zash.se>
parents: 1820
diff changeset
129