prosody-modules
8ecd53452af8
mod_unified_push/README.md

Find changesets by keywords by author, files, the commit message, revision number or hash, or revset expression.

Software / code / prosody-modules

Annotate

mod_unified_push/README.md @ 6217:8ecd53452af8

mod_push2: LMC stanzas are not important
author Stephen Paul Weber <singpolyma@singpolyma.net>
date Tue, 25 Mar 2025 15:20:35 -0500
parent 6087:04d0ab97a678
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
5128
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
1 ---
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
2 labels:
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
3 - Stage-Alpha
6080
9ab0d1c75c26 mod_unified_push: Normalize Markdown
Kim Alvefur <zash@zash.se>
parents: 6073
diff changeset
4 summary: Unified Push provider
5128
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
5 ---
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
6
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
7 This module implements a [Unified Push](https://unifiedpush.org/) Provider
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
8 that uses XMPP to talk to a Push Distributor (e.g. [Conversations](http://codeberg.org/iNPUTmice/Conversations)).
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
9
5138
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
10 It allows push notifications to be delivered to apps on your device over XMPP.
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
11 This means notifications can be delivered quickly and efficiently (apps don't
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
12 need to repeatedly poll for new notifications).
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
13
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
14 For a list of compatible apps, see the [UnifiedPush apps list](https://unifiedpush.org/users/apps/).
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
15
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
16 A server-independent external component is also available - see [the 'up'
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
17 project](https://codeberg.org/inputmice/up). That project also contains a
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
18 description of the protocol between the XMPP server and the client.
5128
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
19
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
20 This module and the protocol it implements is at an experimental prototype
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
21 stage.
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
22
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
23 Note that this module is **not related** to XEP-0357 push notifications for
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
24 XMPP. It does not send push notifications to disconnected XMPP clients. For
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
25 that, see [mod_cloud_notify](https://modules.prosody.im/mod_cloud_notify).
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
26
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
27 ## Configuration
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
28
5156
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
29 | Name | Description | Default |
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
30 |-------------------------------|---------------------------------------------------------|---------------------------------------------|
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
31 | unified_push_acl | A list of domains or users permitted to use the service | current host, or parent host if a component |
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
32 | unified_push_backend | Backend to use: "paseto", "storage" or "jwt" | "paseto" (trunk), "storage" (0.12) |
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
33 | unified_push_registration_ttl | Maximum lifetime of a push registration (seconds) | `86400` (1 day) |
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
34
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
35 ### Backends
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
36
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
37 The module needs to track registrations, and be able to associate tokens with
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
38 users. There are multiple ways to do this, but not every method is supported
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
39 on every Prosody version.
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
40
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
41 By default the module will automatically select the best backend that is
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
42 supported on the current Prosody version you are using.
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
43
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
44 #### storage backend
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
45
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
46 This is the default backend on Prosody 0.12 and earlier. It stores tokens and
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
47 their associated data in Prosody's configured data store.
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
48
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
49 Supported by all Prosody versions.
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
50
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
51 #### paseto backend
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
52
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
53 This is a stateless (i.e. no storage required) backend that uses encrypted
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
54 [PASETO tokens](https://paseto.io/) to store registration info. It is the
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
55 default backend on Prosody trunk, as PASETO support is not available in
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
56 Prosody 0.12 and earlier.
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
57
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
58 #### jwt backend
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
59
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
60 This is a stateless backend that uses [JWT tokens](https://jwt.io/) to store
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
61 registration info. It is supported in Prosody 0.12 and higher.
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
62
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
63 **Note:** The JWT tokens are **not encrypted**, which means the JID
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
64 associated with a registration is visible to apps and services that send you
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
65 push notifications. This can have privacy implications. If in doubt, do not
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
66 use this backend.
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
67
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
68 This backend requires you to set a secure random string in the config file,
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
69 using the `unified_push_secret` option.
5128
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
70
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
71 A random push secret can be generated with the command
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
72 `openssl rand -base64 32`. Changing the secret will invalidate all existing
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
73 push registrations.
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
74
6087
04d0ab97a678 mod_unified_push: add http default path to readme for reverse proxying
Menel <menel@snikket.de>
parents: 6084
diff changeset
75 ## HTTP configuration
5156
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
76
6087
04d0ab97a678 mod_unified_push: add http default path to readme for reverse proxying
Menel <menel@snikket.de>
parents: 6084
diff changeset
77 This module exposes a HTTP endpoint, by default at the path `/push` (to receive push notifications from app
04d0ab97a678 mod_unified_push: add http default path to readme for reverse proxying
Menel <menel@snikket.de>
parents: 6084
diff changeset
78 servers). **If you use a reverse proxy, make sure you proxy this path too.**
04d0ab97a678 mod_unified_push: add http default path to readme for reverse proxying
Menel <menel@snikket.de>
parents: 6084
diff changeset
79 For more information on configuring HTTP services and reverse proxying in Prosody, see
5138
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
80 [Prosody HTTP documentation](https://prosody.im/doc/http).
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
81
6083
631415831007 mod_unified_push: update testing time and Chapter size
Menel <menel@snikket.de>
parents: 6080
diff changeset
82 ## Example configuration
5157
9032143bad08 mod_unified_push: Update docs to recommend loading on normal hosts
Matthew Wild <mwild1@gmail.com>
parents: 5156
diff changeset
83
6084
3441cdf73d80 mod_unified_push: typo
Menel <menel@snikket.de>
parents: 6083
diff changeset
84 ### Recommended: load on Virtualhost(s)
5157
9032143bad08 mod_unified_push: Update docs to recommend loading on normal hosts
Matthew Wild <mwild1@gmail.com>
parents: 5156
diff changeset
85
9032143bad08 mod_unified_push: Update docs to recommend loading on normal hosts
Matthew Wild <mwild1@gmail.com>
parents: 5156
diff changeset
86 Just add just add `"unified_push"` to your `modules_enabled` option.
9032143bad08 mod_unified_push: Update docs to recommend loading on normal hosts
Matthew Wild <mwild1@gmail.com>
parents: 5156
diff changeset
87 This is the easiest and **recommended** configuration.
9032143bad08 mod_unified_push: Update docs to recommend loading on normal hosts
Matthew Wild <mwild1@gmail.com>
parents: 5156
diff changeset
88
6080
9ab0d1c75c26 mod_unified_push: Normalize Markdown
Kim Alvefur <zash@zash.se>
parents: 6073
diff changeset
89 ``` lua
5157
9032143bad08 mod_unified_push: Update docs to recommend loading on normal hosts
Matthew Wild <mwild1@gmail.com>
parents: 5156
diff changeset
90 modules_enabled = {
6083
631415831007 mod_unified_push: update testing time and Chapter size
Menel <menel@snikket.de>
parents: 6080
diff changeset
91 -- ...
5157
9032143bad08 mod_unified_push: Update docs to recommend loading on normal hosts
Matthew Wild <mwild1@gmail.com>
parents: 5156
diff changeset
92 "unified_push";
6083
631415831007 mod_unified_push: update testing time and Chapter size
Menel <menel@snikket.de>
parents: 6080
diff changeset
93 -- ...
5157
9032143bad08 mod_unified_push: Update docs to recommend loading on normal hosts
Matthew Wild <mwild1@gmail.com>
parents: 5156
diff changeset
94 }
9032143bad08 mod_unified_push: Update docs to recommend loading on normal hosts
Matthew Wild <mwild1@gmail.com>
parents: 5156
diff changeset
95 ```
9032143bad08 mod_unified_push: Update docs to recommend loading on normal hosts
Matthew Wild <mwild1@gmail.com>
parents: 5156
diff changeset
96
6073
045d557fc8c9 mod_unified_push: fix Compability sextion and improve Layout
Menel <menel@snikket.de>
parents: 5157
diff changeset
97 #### Component method
5157
9032143bad08 mod_unified_push: Update docs to recommend loading on normal hosts
Matthew Wild <mwild1@gmail.com>
parents: 5156
diff changeset
98
9032143bad08 mod_unified_push: Update docs to recommend loading on normal hosts
Matthew Wild <mwild1@gmail.com>
parents: 5156
diff changeset
99 This is an example of how to configure the module as an internal component,
9032143bad08 mod_unified_push: Update docs to recommend loading on normal hosts
Matthew Wild <mwild1@gmail.com>
parents: 5156
diff changeset
100 e.g. on a subdomain or other non-user domain.
5138
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
101
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
102 This example creates a push notification component called
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
103 'notify.example.com'.
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
104
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
105 The 'http_host' line instructs Prosody to expose this module's HTTP services
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
106 on the 'example.com' host, which avoids needing to create/update DNS records
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
107 and HTTPS certificates if example.com is already set up.
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
108
6080
9ab0d1c75c26 mod_unified_push: Normalize Markdown
Kim Alvefur <zash@zash.se>
parents: 6073
diff changeset
109 ``` lua
5138
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
110 Component "notify.example.com" "unified_push"
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
111 unified_push_secret = "<secret string here>"
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
112 http_host = "example.com"
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
113 ```
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
114
5128
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
115 ## Compatibility
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
116
6080
9ab0d1c75c26 mod_unified_push: Normalize Markdown
Kim Alvefur <zash@zash.se>
parents: 6073
diff changeset
117 Prosody-Version Status
9ab0d1c75c26 mod_unified_push: Normalize Markdown
Kim Alvefur <zash@zash.se>
parents: 6073
diff changeset
118 ----------------- ----------------------
6083
631415831007 mod_unified_push: update testing time and Chapter size
Menel <menel@snikket.de>
parents: 6080
diff changeset
119 trunk Works as of 24-12-08
6080
9ab0d1c75c26 mod_unified_push: Normalize Markdown
Kim Alvefur <zash@zash.se>
parents: 6073
diff changeset
120 0.12 Works