Mercurial > prosody-modules

annotate mod_mam/README.markdown @ 2000:b5adfe72709b

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_mam: Improve error messages when failed to open storage
author Kim Alvefur <zash@zash.se>
date Sat, 09 Jan 2016 14:18:07 +0100
parents b91f27f21666
children cdba975e9b6e
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
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1801
diff changeset
36 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
37 ---------------
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
38
1978
b91f27f21666 mod_mam/README: Use autolinks
Kim Alvefur <zash@zash.se>
parents: 1976
diff changeset
39 mod\_mam uses the store "archive2"[\^1]. See [Prosodys data storage
b91f27f21666 mod_mam/README: Use autolinks
Kim Alvefur <zash@zash.se>
parents: 1976
diff changeset
40 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
41
1976
cd36e5bf00b3 Various READMEs: Update to reflect rename of mod_storage_sql2 → mod_storage_sql
Kim Alvefur <zash@zash.se>
parents: 1835
diff changeset
42 For example, to use mod\_storage\_sql:
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
43
1820
8de50be756e5 Various README files: Correct indentation levels, fix syntax and other small fixes
Kim Alvefur <zash@zash.se>
parents: 1804
diff changeset
44 ``` {.lua}
8de50be756e5 Various README files: Correct indentation levels, fix syntax and other small fixes
Kim Alvefur <zash@zash.se>
parents: 1804
diff changeset
45 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
46 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
47 }
8de50be756e5 Various README files: Correct indentation levels, fix syntax and other small fixes
Kim Alvefur <zash@zash.se>
parents: 1804
diff changeset
48 ```
1801
5abf61915ab4 mod_mam/README: Add example of use with mod_storage_sql2
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
49
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
50 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
51 -----------------
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
52
1804
3228fb928a93 mod_mam/README: Minor fixup
Kim Alvefur <zash@zash.se>
parents: 1803
diff changeset
53 max_archive_query_results = 20;
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
54
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1801
diff changeset
55 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
56 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
57 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
58 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
59 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
60 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
61
6234e67ebe7a mod_mam/README: Reorganise config options under sub-headings and rewrite description of options
Kim Alvefur <zash@zash.se>
parents: 1820
diff changeset
62 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
63 -----------------------
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
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 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
66 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
67 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
68 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
69 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
70
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 ``` {.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
72 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
73 ```
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
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 `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
76 ---------------------------- ------------------------------------------------------
6234e67ebe7a mod_mam/README: Reorganise config options under sub-headings and rewrite description of options
Kim Alvefur <zash@zash.se>
parents: 1820
diff changeset
77 `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
78 `"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
79 `true` Store all messages.
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1801
diff changeset
80
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1801
diff changeset
81 Compatibility
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1801
diff changeset
82 =============
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
83
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
84 ------- ---------------
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1801
diff changeset
85 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
86 0.10 Works [^2]
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1801
diff changeset
87 0.9 Unsupported
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1801
diff changeset
88 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
89 ------- ---------------
6234e67ebe7a mod_mam/README: Reorganise config options under sub-headings and rewrite description of options
Kim Alvefur <zash@zash.se>
parents: 1820
diff changeset
90
6234e67ebe7a mod_mam/README: Reorganise config options under sub-headings and rewrite description of options
Kim Alvefur <zash@zash.se>
parents: 1820
diff changeset
91 [^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
92
1976
cd36e5bf00b3 Various READMEs: Update to reflect rename of mod_storage_sql2 → mod_storage_sql
Kim Alvefur <zash@zash.se>
parents: 1835
diff changeset
93 [^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
94 mod\_storage\_sql in 0.10