Mercurial > prosody-modules

annotate mod_mam/README.markdown @ 2016:279885fd9728

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_mam: Add support for trimming old archived messages
author Kim Alvefur <zash@zash.se>
date Tue, 19 Jan 2016 13:34:16 +0100
parents 7f90692bbd23
children d44ac0756c46
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
cdba975e9b6e mod_mam/README: Add a summary of options
Kim Alvefur <zash@zash.se>
parents: 1978
diff changeset
40 ------------------------------ ----------------------- ---------
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`
cdba975e9b6e mod_mam/README: Add a summary of options
Kim Alvefur <zash@zash.se>
parents: 1978
diff changeset
42 default\_archive\_policy boolean or `"roster"` `false`
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"`
2012
cdba975e9b6e mod_mam/README: Add a summary of options
Kim Alvefur <zash@zash.se>
parents: 1978
diff changeset
44
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1801
diff changeset
45 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
46 ---------------
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
47
2015
7f90692bbd23 mod_mam/README: Fix footnote
Kim Alvefur <zash@zash.se>
parents: 2013
diff changeset
48 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
49 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
50
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
51 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
52
1820
8de50be756e5 Various README files: Correct indentation levels, fix syntax and other small fixes
Kim Alvefur <zash@zash.se>
parents: 1804
diff changeset
53 ``` {.lua}
8de50be756e5 Various README files: Correct indentation levels, fix syntax and other small fixes
Kim Alvefur <zash@zash.se>
parents: 1804
diff changeset
54 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
55 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
56 }
8de50be756e5 Various README files: Correct indentation levels, fix syntax and other small fixes
Kim Alvefur <zash@zash.se>
parents: 1804
diff changeset
57 ```
1801
5abf61915ab4 mod_mam/README: Add example of use with mod_storage_sql2
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
58
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
59 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
60 -----------------
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
61
1804
3228fb928a93 mod_mam/README: Minor fixup
Kim Alvefur <zash@zash.se>
parents: 1803
diff changeset
62 max_archive_query_results = 20;
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
63
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1801
diff changeset
64 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
65 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
66 include a reference to the next page, letting clients page through the
6234e67ebe7a mod_mam/README: Reorganise config options under sub-headings and rewrite description of options
Kim Alvefur <zash@zash.se>
parents: 1820
diff changeset
67 result set. Setting large number is not recomended, as Prosody will be
6234e67ebe7a mod_mam/README: Reorganise config options under sub-headings and rewrite description of options
Kim Alvefur <zash@zash.se>
parents: 1820
diff changeset
68 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
69 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
70
2016
279885fd9728 mod_mam: Add support for trimming old archived messages
Kim Alvefur <zash@zash.se>
parents: 2015
diff changeset
71 Archive expiry
279885fd9728 mod_mam: Add support for trimming old archived messages
Kim Alvefur <zash@zash.se>
parents: 2015
diff changeset
72 --------------
279885fd9728 mod_mam: Add support for trimming old archived messages
Kim Alvefur <zash@zash.se>
parents: 2015
diff changeset
73
279885fd9728 mod_mam: Add support for trimming old archived messages
Kim Alvefur <zash@zash.se>
parents: 2015
diff changeset
74 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
75 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
76
279885fd9728 mod_mam: Add support for trimming old archived messages
Kim Alvefur <zash@zash.se>
parents: 2015
diff changeset
77 ``` {.lua}
279885fd9728 mod_mam: Add support for trimming old archived messages
Kim Alvefur <zash@zash.se>
parents: 2015
diff changeset
78 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
79
279885fd9728 mod_mam: Add support for trimming old archived messages
Kim Alvefur <zash@zash.se>
parents: 2015
diff changeset
80 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
81
279885fd9728 mod_mam: Add support for trimming old archived messages
Kim Alvefur <zash@zash.se>
parents: 2015
diff changeset
82 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
83
279885fd9728 mod_mam: Add support for trimming old archived messages
Kim Alvefur <zash@zash.se>
parents: 2015
diff changeset
84 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
85
279885fd9728 mod_mam: Add support for trimming old archived messages
Kim Alvefur <zash@zash.se>
parents: 2015
diff changeset
86 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
87
279885fd9728 mod_mam: Add support for trimming old archived messages
Kim Alvefur <zash@zash.se>
parents: 2015
diff changeset
88 archive_expires_after = "never" -- forever
279885fd9728 mod_mam: Add support for trimming old archived messages
Kim Alvefur <zash@zash.se>
parents: 2015
diff changeset
89 ```
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 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
92 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
93 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
94
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
95 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
96 -----------------------
6234e67ebe7a mod_mam/README: Reorganise config options under sub-headings and rewrite description of options
Kim Alvefur <zash@zash.se>
parents: 1820
diff changeset
97
6234e67ebe7a mod_mam/README: Reorganise config options under sub-headings and rewrite description of options
Kim Alvefur <zash@zash.se>
parents: 1820
diff changeset
98 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
99 should be stored. This allows users to enable or disable archiving by
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 default or for specific contacts. This module will log no messages by
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 default, for privacy concerns. If you decide to change this, you should
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 inform your users.
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
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 ``` {.lua}
6234e67ebe7a mod_mam/README: Reorganise config options under sub-headings and rewrite description of options
Kim Alvefur <zash@zash.se>
parents: 1820
diff changeset
105 default_archive_policy = false
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
6234e67ebe7a mod_mam/README: Reorganise config options under sub-headings and rewrite description of options
Kim Alvefur <zash@zash.se>
parents: 1820
diff changeset
108 `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
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 `false` Store no messages. This is the default.
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 `"roster"` Store messages to/from contacts in the users roster.
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 `true` Store all messages.
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1801
diff changeset
113
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1801
diff changeset
114 Compatibility
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1801
diff changeset
115 =============
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
116
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
117 ------- ---------------
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1801
diff changeset
118 trunk Works
1976
cd36e5bf00b3 Various READMEs: Update to reflect rename of mod_storage_sql2 → mod_storage_sql
Kim Alvefur <zash@zash.se>
parents: 1835
diff changeset
119 0.10 Works [^2]
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1801
diff changeset
120 0.9 Unsupported
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1801
diff changeset
121 0.8 Does not work
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
122 ------- ---------------
6234e67ebe7a mod_mam/README: Reorganise config options under sub-headings and rewrite description of options
Kim Alvefur <zash@zash.se>
parents: 1820
diff changeset
123
6234e67ebe7a mod_mam/README: Reorganise config options under sub-headings and rewrite description of options
Kim Alvefur <zash@zash.se>
parents: 1820
diff changeset
124 [^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
125
1976
cd36e5bf00b3 Various READMEs: Update to reflect rename of mod_storage_sql2 → mod_storage_sql
Kim Alvefur <zash@zash.se>
parents: 1835
diff changeset
126 [^2]: requires a storage driver with archive support, eg
cd36e5bf00b3 Various READMEs: Update to reflect rename of mod_storage_sql2 → mod_storage_sql
Kim Alvefur <zash@zash.se>
parents: 1835
diff changeset
127 mod\_storage\_sql in 0.10