annotate mod_unified_push/README.md @ 6319:04c3273cb81f

mod_auth_cyrus: Add empty 'profile' table to SASL handler objects This is for compatibility with Prosody's built-in util.sasl objects. A SASL profile table usually includes methods supported by the backend, which can be used by SASL mechanism handlers to perform operations (such as testing the password). It also optionally contains a 'cb' field with channel binding method handlers. The Cyrus backend doesn't support channel binding, and doesn't have the same concept of auth backend methods (it handles all that internally, and Prosody has no insight or control over it). Thus, we create an empty profile which informs Prosody that the SASL handler does not support any of the auth or channel binding methods. Some features will not work, but they didn't work anyway. This just makes it explicit. This fixes a traceback in mod_sasl2_fast, which expected SASL handlers to always contain a 'profile' field.
author Matthew Wild <mwild1@gmail.com>
date Thu, 04 Sep 2025 10:14:46 +0100
parents 04d0ab97a678
children
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
6052
9ab0d1c75c26 mod_unified_push: Normalize Markdown
Kim Alvefur <zash@zash.se>
parents: 6045
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
6059
04d0ab97a678 mod_unified_push: add http default path to readme for reverse proxying
Menel <menel@snikket.de>
parents: 6056
diff changeset
75 ## HTTP configuration
5156
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
76
6059
04d0ab97a678 mod_unified_push: add http default path to readme for reverse proxying
Menel <menel@snikket.de>
parents: 6056
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: 6056
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: 6056
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
6055
631415831007 mod_unified_push: update testing time and Chapter size
Menel <menel@snikket.de>
parents: 6052
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
6056
3441cdf73d80 mod_unified_push: typo
Menel <menel@snikket.de>
parents: 6055
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
6052
9ab0d1c75c26 mod_unified_push: Normalize Markdown
Kim Alvefur <zash@zash.se>
parents: 6045
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 = {
6055
631415831007 mod_unified_push: update testing time and Chapter size
Menel <menel@snikket.de>
parents: 6052
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";
6055
631415831007 mod_unified_push: update testing time and Chapter size
Menel <menel@snikket.de>
parents: 6052
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
6045
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
6052
9ab0d1c75c26 mod_unified_push: Normalize Markdown
Kim Alvefur <zash@zash.se>
parents: 6045
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
6052
9ab0d1c75c26 mod_unified_push: Normalize Markdown
Kim Alvefur <zash@zash.se>
parents: 6045
diff changeset
117 Prosody-Version Status
9ab0d1c75c26 mod_unified_push: Normalize Markdown
Kim Alvefur <zash@zash.se>
parents: 6045
diff changeset
118 ----------------- ----------------------
6055
631415831007 mod_unified_push: update testing time and Chapter size
Menel <menel@snikket.de>
parents: 6052
diff changeset
119 trunk Works as of 24-12-08
6052
9ab0d1c75c26 mod_unified_push: Normalize Markdown
Kim Alvefur <zash@zash.se>
parents: 6045
diff changeset
120 0.12 Works