view mod_mam/README.markdown @ 3609:0d4598dacc87

mod_statistics_statsman: Map 'cpu.clock' from mod_measure_cpu to 'cpu_total' of mod_statistics_cputotal
author Kim Alvefur <>
date Tue, 28 May 2019 21:26:13 +0200
parents b8805ab1d470
children 637d63b7398e
line wrap: on
line source

- 'Stage-Beta'
summary: 'XEP-0313: Message Archive Management'


Implementation of [XEP-0313: Message Archive Management].


This module will archive all messages that match the simple rules setup
by the user, and allow the user to access this archive.


First copy the module to the prosody plugins directory.

Then add "mam" to your modules\_enabled list:

``` {.lua}
modules_enabled = {
    -- ...
    -- ...


Option summary

  option                         type                    default
  ------------------------------ ----------------------- -----------
  max\_archive\_query\_results   number                  `50`
  default\_archive\_policy       boolean or `"roster"`   `true`
  archive\_expires\_after        string                  `"1w"`
  archive\_cleanup\_interval     number                  `4*60*60`

Storage backend

mod\_mam uses the store "archive2"[^1]. See [Prosodys data storage
documentation][doc:storage] for information on how to configure storage.

For example, to use mod\_storage\_sql (requires Prosody 0.10 or later):

``` {.lua}
storage = {
  archive2 = "sql";

If no archive-capable storage backend can be opened then an in-memory
one will be used as fallback.

Query size limits

    max_archive_query_results = 20;

This is the largest number of messages that are allowed to be retrieved
in one request *page*. A query that does not fit in one page will
include a reference to the next page, letting clients page through the
result set. Setting large number is not recommended, as Prosody will be
blocked while processing the request and will not be able to do anything

Archive expiry

Messages in the archive will expire after some time, by default one
week. This can be changed by setting `archive_expires_after`:

``` {.lua}
archive_expires_after = "1d" -- one day

archive_expires_after = "1w" -- one week, the default

archive_expires_after = "2m" -- two months

archive_expires_after = "1y" -- one year

archive_expires_after = 60 * 60 -- one hour

archive_expires_after = "never" -- forever

The format is an integer number of seconds or a multiple of a period
given by a suffix that can be one of `d` (day), `w` (week), `m` (month)
or `y` (year). No multiplier means seconds.

Message matching policy

The MAM protocol includes a way for clients to control what messages
should be stored. This allows users to enable or disable archiving by
default or for specific contacts.

``` {.lua}
default_archive_policy = true

  `default_archive_policy =`   Meaning
  ---------------------------- ------------------------------------------------------
  `false`                      Store no messages.
  `"roster"`                   Store messages to/from contacts in the users roster.
  `true`                       Store all messages. This is the default.


  ------- -----------------------
  trunk   Included with Prosody
  0.10    Included with Prosody
  0.9     Works
  0.8     Does not work
  ------- -----------------------

[^1]: Might be changed to "mam" at some point