Mercurial > prosody-modules

annotate mod_smacks/README.markdown @ 5160:8474a3b80200

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_firewall: Fix 'is_admin' internal dependency rule #1797 (thanks diane) Looks like the boolean logic was inverted here. Instead, for now, simply check if is_admin is there. It is deprecated in trunk and was briefly removed before being brought back with a 'deprecated' warning as part of the new roles and permissions work. Making this dependency conditioned on the existence of the underlying function should make it work until it actually goes away for real.
author Kim Alvefur <zash@zash.se>
date Fri, 27 Jan 2023 23:06:25 +0100
parents c5b1e9b8ccca
children
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: 1782
diff changeset
1 ---
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
2 labels:
2154
ada71b81425a mod_smacks/README: Too buggy for a "Beta" label
Kim Alvefur <zash@zash.se>
parents: 2063
diff changeset
3 - 'Stage-Alpha'
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
4 summary: 'XEP-0198: Reliability and fast reconnects for XMPP'
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
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: 1782
diff changeset
7 Introduction
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
8 ============
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
9
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
10 By default XMPP is as reliable as your network is. Unfortunately in some
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
11 cases that is not very reliable - in some network conditions disconnects
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
12 can be frequent and message loss can occur.
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
13
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
14 To overcome this, XMPP has an optional extension (XEP-0198: Stream
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
15 Management) which, when supported by both the client and server, can
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
16 allow a client to resume a disconnected session, and prevent message
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
17 loss.
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
18
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
19 Details
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
20 =======
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
21
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
22 When using XEP-0198 both the client and the server keep a queue of the
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
23 most recently sent stanzas - this is cleared when the other end
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
24 acknowledges they have received the stanzas. If the client disconnects,
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
25 instead of marking the user offline the server pretends the client is
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
26 still online for a short (configurable) period of time. If the client
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
27 reconnects within this period, any stanzas in the queue that the client
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
28 did not receive are re-sent.
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
29
3967
0957ba6aeb99 mod_smacks: Update documentation and slightly adjust default values
tmolitor <thilo@eightysoft.de>
parents: 2596
diff changeset
30 If the client fails to reconnect before the timeout it will be marked as
0957ba6aeb99 mod_smacks: Update documentation and slightly adjust default values
tmolitor <thilo@eightysoft.de>
parents: 2596
diff changeset
31 offline like prosody does on disconnect without mod_smacks.
0957ba6aeb99 mod_smacks: Update documentation and slightly adjust default values
tmolitor <thilo@eightysoft.de>
parents: 2596
diff changeset
32 If the client is the last one for this jid, all message stanzas are added to
0957ba6aeb99 mod_smacks: Update documentation and slightly adjust default values
tmolitor <thilo@eightysoft.de>
parents: 2596
diff changeset
33 the offline store and all other stanzas stanzas are returned with an
0957ba6aeb99 mod_smacks: Update documentation and slightly adjust default values
tmolitor <thilo@eightysoft.de>
parents: 2596
diff changeset
34 "recipient-unavailable" error. If the client is not the last one with an
0957ba6aeb99 mod_smacks: Update documentation and slightly adjust default values
tmolitor <thilo@eightysoft.de>
parents: 2596
diff changeset
35 open smacks session, *all* stanzas are returned with an "recipient-unavailable" error.
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
36
3967
0957ba6aeb99 mod_smacks: Update documentation and slightly adjust default values
tmolitor <thilo@eightysoft.de>
parents: 2596
diff changeset
37 If you deliberately disabled [mod_offline], all message stanzas of the last client
0957ba6aeb99 mod_smacks: Update documentation and slightly adjust default values
tmolitor <thilo@eightysoft.de>
parents: 2596
diff changeset
38 are also returned with an "recipient-unavailable" error, because the can not be
0957ba6aeb99 mod_smacks: Update documentation and slightly adjust default values
tmolitor <thilo@eightysoft.de>
parents: 2596
diff changeset
39 added to the offline storage.
0957ba6aeb99 mod_smacks: Update documentation and slightly adjust default values
tmolitor <thilo@eightysoft.de>
parents: 2596
diff changeset
40 If you don't want this behaviour you can use [mod_nooffline_noerror] to suppress the error.
0957ba6aeb99 mod_smacks: Update documentation and slightly adjust default values
tmolitor <thilo@eightysoft.de>
parents: 2596
diff changeset
41 This is generally only advisable, if you are sure that all your clients are using MAM!
2394
4c27ebcf4cbd mod_smacks: added new event "smacks-ack-delayed" used by mod_cloud_notify and extended the readme file accordingly (also mention mod_smacks_offline and mod_smacks_noerror in readme file)
tmolitor <thilo@eightysoft.de>
parents: 2154
diff changeset
42
4c27ebcf4cbd mod_smacks: added new event "smacks-ack-delayed" used by mod_cloud_notify and extended the readme file accordingly (also mention mod_smacks_offline and mod_smacks_noerror in readme file)
tmolitor <thilo@eightysoft.de>
parents: 2154
diff changeset
43 This module also provides some events used by [mod_cloud_notify].
4c27ebcf4cbd mod_smacks: added new event "smacks-ack-delayed" used by mod_cloud_notify and extended the readme file accordingly (also mention mod_smacks_offline and mod_smacks_noerror in readme file)
tmolitor <thilo@eightysoft.de>
parents: 2154
diff changeset
44 These events are: "smacks-ack-delayed", "smacks-hibernation-start" and
4c27ebcf4cbd mod_smacks: added new event "smacks-ack-delayed" used by mod_cloud_notify and extended the readme file accordingly (also mention mod_smacks_offline and mod_smacks_noerror in readme file)
tmolitor <thilo@eightysoft.de>
parents: 2154
diff changeset
45 "smacks-hibernation-end". See [mod_cloud_notify] for details on how this
4c27ebcf4cbd mod_smacks: added new event "smacks-ack-delayed" used by mod_cloud_notify and extended the readme file accordingly (also mention mod_smacks_offline and mod_smacks_noerror in readme file)
tmolitor <thilo@eightysoft.de>
parents: 2154
diff changeset
46 events are used there.
4c27ebcf4cbd mod_smacks: added new event "smacks-ack-delayed" used by mod_cloud_notify and extended the readme file accordingly (also mention mod_smacks_offline and mod_smacks_noerror in readme file)
tmolitor <thilo@eightysoft.de>
parents: 2154
diff changeset
47
2596
ffb6646b4253 Implement XEP-0198 revision 1.5.2 and limit number of hibernated sessions per user
tmolitor <thilo@eightysoft.de>
parents: 2503
diff changeset
48 Use prosody 0.10+ to have per user limits on allowed sessions in hibernation
ffb6646b4253 Implement XEP-0198 revision 1.5.2 and limit number of hibernated sessions per user
tmolitor <thilo@eightysoft.de>
parents: 2503
diff changeset
49 state and allowed sessions for which the h-value is kept even after the
ffb6646b4253 Implement XEP-0198 revision 1.5.2 and limit number of hibernated sessions per user
tmolitor <thilo@eightysoft.de>
parents: 2503
diff changeset
50 hibernation timed out.
ffb6646b4253 Implement XEP-0198 revision 1.5.2 and limit number of hibernated sessions per user
tmolitor <thilo@eightysoft.de>
parents: 2503
diff changeset
51 These are settable using `smacks_max_hibernated_sessions` and `smacks_max_old_sessions`.
ffb6646b4253 Implement XEP-0198 revision 1.5.2 and limit number of hibernated sessions per user
tmolitor <thilo@eightysoft.de>
parents: 2503
diff changeset
52
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
53 Configuration
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
54 =============
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
55
2596
ffb6646b4253 Implement XEP-0198 revision 1.5.2 and limit number of hibernated sessions per user
tmolitor <thilo@eightysoft.de>
parents: 2503
diff changeset
56 Option Default Description
ffb6646b4253 Implement XEP-0198 revision 1.5.2 and limit number of hibernated sessions per user
tmolitor <thilo@eightysoft.de>
parents: 2503
diff changeset
57 ---------------------------------- ----------------- ------------------------------------------------------------------------------------------------------------------
3967
0957ba6aeb99 mod_smacks: Update documentation and slightly adjust default values
tmolitor <thilo@eightysoft.de>
parents: 2596
diff changeset
58 `smacks_hibernation_time` 600 (10 minutes) The number of seconds a disconnected session should stay alive for (to allow reconnect)
4678
0bcbff950f14 mod_smacks: Update README
Martin Dosch <martin@mdosch.de>
parents: 3967
diff changeset
59 `smacks_enabled_s2s` true Enable Stream Management on server connections? *Experimental*
4721
2db804a1c9f0 mod_smacks: Add smacks_s2s_resend to configuration listing
Kim Alvefur <zash@zash.se>
parents: 4678
diff changeset
60 `smacks_s2s_resend` false Attempt to re-send unacked messages on s2s disconnect *Experimental*
2596
ffb6646b4253 Implement XEP-0198 revision 1.5.2 and limit number of hibernated sessions per user
tmolitor <thilo@eightysoft.de>
parents: 2503
diff changeset
61 `smacks_max_unacked_stanzas` 0 How many stanzas to send before requesting acknowledgement
3967
0957ba6aeb99 mod_smacks: Update documentation and slightly adjust default values
tmolitor <thilo@eightysoft.de>
parents: 2596
diff changeset
62 `smacks_max_ack_delay` 30 (1/2 minute) The number of seconds an ack must be unanswered to trigger an "smacks-ack-delayed" event
2596
ffb6646b4253 Implement XEP-0198 revision 1.5.2 and limit number of hibernated sessions per user
tmolitor <thilo@eightysoft.de>
parents: 2503
diff changeset
63 `smacks_max_hibernated_sessions` 10 The number of allowed sessions in hibernated state (limited per user)
ffb6646b4253 Implement XEP-0198 revision 1.5.2 and limit number of hibernated sessions per user
tmolitor <thilo@eightysoft.de>
parents: 2503
diff changeset
64 `smacks_max_old_sessions` 10 The number of allowed sessions with timed out hibernation for which the h-value is still kept (limited per user)
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
65
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
66 Compatibility
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
67 =============
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
68
4722
c5b1e9b8ccca mod_smacks: Remove EOL releases from Compatibility section, add 0.11 & trunk
Kim Alvefur <zash@zash.se>
parents: 4721
diff changeset
69 ------- -------
c5b1e9b8ccca mod_smacks: Remove EOL releases from Compatibility section, add 0.11 & trunk
Kim Alvefur <zash@zash.se>
parents: 4721
diff changeset
70 trunk Works
c5b1e9b8ccca mod_smacks: Remove EOL releases from Compatibility section, add 0.11 & trunk
Kim Alvefur <zash@zash.se>
parents: 4721
diff changeset
71 0.11 Works
c5b1e9b8ccca mod_smacks: Remove EOL releases from Compatibility section, add 0.11 & trunk
Kim Alvefur <zash@zash.se>
parents: 4721
diff changeset
72 ------- -------
1876
9c9397d692aa mod_smacks/README: Update link to 0.8 version
Kim Alvefur <zash@zash.se>
parents: 1803
diff changeset
73
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
74
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
75 Clients
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
76 =======
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
77
2503
7036a6e074d7 mod_smacks/README: Linkify the XEP
Kim Alvefur <zash@zash.se>
parents: 2394
diff changeset
78 Clients that support [XEP-0198]:
1782
29f3d6b7ad16 Import wiki pages
Kim Alvefur <zash@zash.se>
parents:
diff changeset
79
2596
ffb6646b4253 Implement XEP-0198 revision 1.5.2 and limit number of hibernated sessions per user
tmolitor <thilo@eightysoft.de>
parents: 2503
diff changeset
80 - Gajim (Linux, Windows, OS X)
ffb6646b4253 Implement XEP-0198 revision 1.5.2 and limit number of hibernated sessions per user
tmolitor <thilo@eightysoft.de>
parents: 2503
diff changeset
81 - Conversations (Android)
ffb6646b4253 Implement XEP-0198 revision 1.5.2 and limit number of hibernated sessions per user
tmolitor <thilo@eightysoft.de>
parents: 2503
diff changeset
82 - ChatSecure (iOS)
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
83 - Swift (but not resumption, as of version 2.0 and alphas of 3.0)
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1782
diff changeset
84 - Psi (in an unreleased branch)
2596
ffb6646b4253 Implement XEP-0198 revision 1.5.2 and limit number of hibernated sessions per user
tmolitor <thilo@eightysoft.de>
parents: 2503
diff changeset
85 - Yaxim (Android)
ffb6646b4253 Implement XEP-0198 revision 1.5.2 and limit number of hibernated sessions per user
tmolitor <thilo@eightysoft.de>
parents: 2503
diff changeset
86 - Monal (iOS)
1876
9c9397d692aa mod_smacks/README: Update link to 0.8 version
Kim Alvefur <zash@zash.se>
parents: 1803
diff changeset
87
9c9397d692aa mod_smacks/README: Update link to 0.8 version
Kim Alvefur <zash@zash.se>
parents: 1803
diff changeset
88 [7693724881b3]: //hg.prosody.im/prosody-modules/raw-file/7693724881b3/mod_smacks/mod_smacks.lua
3967
0957ba6aeb99 mod_smacks: Update documentation and slightly adjust default values
tmolitor <thilo@eightysoft.de>
parents: 2596
diff changeset
89 [mod_offline]: //modules.prosody.im/mod_offline
0957ba6aeb99 mod_smacks: Update documentation and slightly adjust default values
tmolitor <thilo@eightysoft.de>
parents: 2596
diff changeset
90 [mod_nooffline_noerror]: //modules.prosody.im/mod_nooffline_noerror
2394
4c27ebcf4cbd mod_smacks: added new event "smacks-ack-delayed" used by mod_cloud_notify and extended the readme file accordingly (also mention mod_smacks_offline and mod_smacks_noerror in readme file)
tmolitor <thilo@eightysoft.de>
parents: 2154
diff changeset
91 [mod_cloud_notify]: //modules.prosody.im/mod_cloud_notify