prosody-modules
886c985ece61
mod_pubsub_serverinfo/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_pubsub_serverinfo/README.md @ 6195:886c985ece61

mod_lastlog2: Skip initializing internal API (and storage) in prosodyctl Initializing storage in the global context under prosodyctl causes the module.command to fail to execute because the storage module has already been loaded. Introduced in 7b722955c59b
author Kim Alvefur <zash@zash.se>
date Sat, 08 Feb 2025 14:12:18 +0100
parent 6059:25b091cbb471
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
5824
73887dcb2129 mod_pubsub_serverinfo: New module that uses pub/sub to make accessible server info
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents:
diff changeset
1 ---
73887dcb2129 mod_pubsub_serverinfo: New module that uses pub/sub to make accessible server info
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents:
diff changeset
2 labels:
73887dcb2129 mod_pubsub_serverinfo: New module that uses pub/sub to make accessible server info
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents:
diff changeset
3 - 'Statistics'
73887dcb2129 mod_pubsub_serverinfo: New module that uses pub/sub to make accessible server info
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents:
diff changeset
4 ...
73887dcb2129 mod_pubsub_serverinfo: New module that uses pub/sub to make accessible server info
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents:
diff changeset
5
5893
faf1f1c833e8 mod_pubsub_serverinfo: update reference to XEP.
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5865
diff changeset
6 Exposes server information over Pub/Sub per [XEP-0485: PubSub Server Information](https://xmpp.org/extensions/xep-0485.html).
5824
73887dcb2129 mod_pubsub_serverinfo: New module that uses pub/sub to make accessible server info
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents:
diff changeset
7
5830
f08818b8b87d mod_pubsub_serverinfo: Update documentation
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5829
diff changeset
8 The module announces support (used to 'opt-in', per the XEP) and publishes the name of the local domain via a Pub/Sub node. The published data
f08818b8b87d mod_pubsub_serverinfo: Update documentation
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5829
diff changeset
9 will contain a 'remote-domain' element for inbound and outgoing s2s connections. These elements will be named only when the remote domain announces
f08818b8b87d mod_pubsub_serverinfo: Update documentation
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5829
diff changeset
10 support ('opts in') too.
5826
f55e65315ba0 mod_pubsub_serverinfo: implemented all basic features
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5824
diff changeset
11
5865
904b226fddf1 mod_pubsub_serverinfo: Update README to link to known issues
Matthew Wild <mwild1@gmail.com>
parents: 5834
diff changeset
12 **Known issues:**
904b226fddf1 mod_pubsub_serverinfo: Update README to link to known issues
Matthew Wild <mwild1@gmail.com>
parents: 5834
diff changeset
13
5991
c61a82f80e57 mod_pubsub_serverinfo: Reference workaround for issue #1841
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5893
diff changeset
14 - [Issue #1841](https://issues.prosody.im/1841): In Prosody 0.12, this module conflicts with mod_server_contact_info (both will run, but it may affect the ability of some implementations to read the server/contact information provided). To work around this issue, the [mod_server_contact_info](https://modules.prosody.im/mod_server_contact_info) community module can be used.
5865
904b226fddf1 mod_pubsub_serverinfo: Update README to link to known issues
Matthew Wild <mwild1@gmail.com>
parents: 5834
diff changeset
15
5826
f55e65315ba0 mod_pubsub_serverinfo: implemented all basic features
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5824
diff changeset
16 Installation
f55e65315ba0 mod_pubsub_serverinfo: implemented all basic features
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5824
diff changeset
17 ============
f55e65315ba0 mod_pubsub_serverinfo: implemented all basic features
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5824
diff changeset
18
f55e65315ba0 mod_pubsub_serverinfo: implemented all basic features
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5824
diff changeset
19 Enable this module in the global or a virtual host.
f55e65315ba0 mod_pubsub_serverinfo: implemented all basic features
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5824
diff changeset
20
f55e65315ba0 mod_pubsub_serverinfo: implemented all basic features
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5824
diff changeset
21 The default configuration requires the existence of a Pub/Sub component that uses the 'pubsub' subdomain of the host in which the module is enabled:
f55e65315ba0 mod_pubsub_serverinfo: implemented all basic features
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5824
diff changeset
22
f55e65315ba0 mod_pubsub_serverinfo: implemented all basic features
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5824
diff changeset
23 Component "pubsub.example.org" "pubsub"
f55e65315ba0 mod_pubsub_serverinfo: implemented all basic features
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5824
diff changeset
24
f55e65315ba0 mod_pubsub_serverinfo: implemented all basic features
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5824
diff changeset
25 The module will create a node and publish data, using a JID that matches the XMPP domain name of the host. Ensure that this actor is an admin of the
f55e65315ba0 mod_pubsub_serverinfo: implemented all basic features
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5824
diff changeset
26 Pub/Sub service:
f55e65315ba0 mod_pubsub_serverinfo: implemented all basic features
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5824
diff changeset
27
f55e65315ba0 mod_pubsub_serverinfo: implemented all basic features
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5824
diff changeset
28 admins = { "example.org" }
f55e65315ba0 mod_pubsub_serverinfo: implemented all basic features
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5824
diff changeset
29
f55e65315ba0 mod_pubsub_serverinfo: implemented all basic features
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5824
diff changeset
30 Configuration
f55e65315ba0 mod_pubsub_serverinfo: implemented all basic features
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5824
diff changeset
31 =============
f55e65315ba0 mod_pubsub_serverinfo: implemented all basic features
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5824
diff changeset
32
f55e65315ba0 mod_pubsub_serverinfo: implemented all basic features
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5824
diff changeset
33 The Pub/Sub service on which data is published, by default, is a component addressed as the `pubsub` subdomain of the domain of the virtual host that
f55e65315ba0 mod_pubsub_serverinfo: implemented all basic features
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5824
diff changeset
34 the module is loaded under. To change this, apply this configuration setting:
f55e65315ba0 mod_pubsub_serverinfo: implemented all basic features
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5824
diff changeset
35
f55e65315ba0 mod_pubsub_serverinfo: implemented all basic features
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5824
diff changeset
36 pubsub_serverinfo_service = "anotherpubsub.example.org"
f55e65315ba0 mod_pubsub_serverinfo: implemented all basic features
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5824
diff changeset
37
f55e65315ba0 mod_pubsub_serverinfo: implemented all basic features
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5824
diff changeset
38 The Pub/Sub node on which data is published is, by default, a leaf-node named `serverinfo`. To change this, apply this configuration setting:
f55e65315ba0 mod_pubsub_serverinfo: implemented all basic features
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5824
diff changeset
39
f55e65315ba0 mod_pubsub_serverinfo: implemented all basic features
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5824
diff changeset
40 pubsub_serverinfo_node = "foobar"
f55e65315ba0 mod_pubsub_serverinfo: implemented all basic features
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5824
diff changeset
41
f55e65315ba0 mod_pubsub_serverinfo: implemented all basic features
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5824
diff changeset
42 To prevent a surplus of event notifications, this module will only publish new data after a certain period of time has expired. The default duration
f55e65315ba0 mod_pubsub_serverinfo: implemented all basic features
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5824
diff changeset
43 is 300 seconds (5 minutes). To change this simply put in the config:
f55e65315ba0 mod_pubsub_serverinfo: implemented all basic features
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5824
diff changeset
44
f55e65315ba0 mod_pubsub_serverinfo: implemented all basic features
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5824
diff changeset
45 pubsub_serverinfo_publication_interval = 180 -- or any other number of seconds
5828
55b99f593c3a mod_pubsub_serverinfo: Disco/info cache TTL should be configurable
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5826
diff changeset
46
55b99f593c3a mod_pubsub_serverinfo: Disco/info cache TTL should be configurable
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5826
diff changeset
47 To detect if remote domains allow their domain name to be included in the data that this module publishes, this module will perform a service
55b99f593c3a mod_pubsub_serverinfo: Disco/info cache TTL should be configurable
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5826
diff changeset
48 discovery request to each remote domain. To prevent a continuous flood of disco/info requests, the response to these requests is cached. By default,
55b99f593c3a mod_pubsub_serverinfo: Disco/info cache TTL should be configurable
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5826
diff changeset
49 a cached value will remain in cache for one hour. This duration can be modified by adding this configuration option:
55b99f593c3a mod_pubsub_serverinfo: Disco/info cache TTL should be configurable
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5826
diff changeset
50
55b99f593c3a mod_pubsub_serverinfo: Disco/info cache TTL should be configurable
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5826
diff changeset
51 pubsub_serverinfo_cache_ttl = 1800 -- or any other number of seconds
5829
d4612e7f6724 mod_pubsub_serverinfo: Added 'Known Issues' section
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5828
diff changeset
52
6059
25b091cbb471 mod_pubsub_serverinfo: Allow including the count of active users in the published info
Matthew Wild <mwild1@gmail.com>
parents: 6003
diff changeset
53 To include the count of active (within the past 30 days) users:
25b091cbb471 mod_pubsub_serverinfo: Allow including the count of active users in the published info
Matthew Wild <mwild1@gmail.com>
parents: 6003
diff changeset
54
25b091cbb471 mod_pubsub_serverinfo: Allow including the count of active users in the published info
Matthew Wild <mwild1@gmail.com>
parents: 6003
diff changeset
55 pubsub_serverinfo_publish_user_count = true
25b091cbb471 mod_pubsub_serverinfo: Allow including the count of active users in the published info
Matthew Wild <mwild1@gmail.com>
parents: 6003
diff changeset
56
25b091cbb471 mod_pubsub_serverinfo: Allow including the count of active users in the published info
Matthew Wild <mwild1@gmail.com>
parents: 6003
diff changeset
57 Enabling this option will automatically load mod_measure_active_users.
25b091cbb471 mod_pubsub_serverinfo: Allow including the count of active users in the published info
Matthew Wild <mwild1@gmail.com>
parents: 6003
diff changeset
58
5834
ce8f0e458ffa mod_pubsub_serverinfo: Add node on compatibility
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5831
diff changeset
59 Compatibility
ce8f0e458ffa mod_pubsub_serverinfo: Add node on compatibility
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5831
diff changeset
60 =============
ce8f0e458ffa mod_pubsub_serverinfo: Add node on compatibility
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5831
diff changeset
61
ce8f0e458ffa mod_pubsub_serverinfo: Add node on compatibility
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5831
diff changeset
62 Incompatible with 0.11 or lower.
ce8f0e458ffa mod_pubsub_serverinfo: Add node on compatibility
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5831
diff changeset
63
5829
d4612e7f6724 mod_pubsub_serverinfo: Added 'Known Issues' section
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5828
diff changeset
64 Known Issues / TODOs
d4612e7f6724 mod_pubsub_serverinfo: Added 'Known Issues' section
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5828
diff changeset
65 ====================
d4612e7f6724 mod_pubsub_serverinfo: Added 'Known Issues' section
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5828
diff changeset
66
5831
2465d5191ae9 mod_pubsub_serverinfo: Consider sibling vhosts 'connected'
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5830
diff changeset
67 The reported data does not contain the optional 'connection' child elements. These can be used to describe the direction of a connection.
2465d5191ae9 mod_pubsub_serverinfo: Consider sibling vhosts 'connected'
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5830
diff changeset
68
2465d5191ae9 mod_pubsub_serverinfo: Consider sibling vhosts 'connected'
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5830
diff changeset
69 More generic server information (eg: user counts, software version) should be included in the data that is published.