Mercurial > prosody-modules

annotate mod_pubsub_serverinfo/README.markdown @ 5947:22effe87fed2

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_muc_slow_mode: adding more context in the README.
author John Livingston <git@john-livingston.fr>
date Mon, 29 Jul 2024 23:07:09 +0200
parents faf1f1c833e8
children c61a82f80e57
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
5801
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
5869
faf1f1c833e8 mod_pubsub_serverinfo: update reference to XEP.
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5841
diff changeset
6 Exposes server information over Pub/Sub per [XEP-0485: PubSub Server Information](https://xmpp.org/extensions/xep-0485.html).
5801
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
5807
f08818b8b87d mod_pubsub_serverinfo: Update documentation
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5806
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: 5806
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: 5806
diff changeset
10 support ('opts in') too.
5803
f55e65315ba0 mod_pubsub_serverinfo: implemented all basic features
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5801
diff changeset
11
5841
904b226fddf1 mod_pubsub_serverinfo: Update README to link to known issues
Matthew Wild <mwild1@gmail.com>
parents: 5811
diff changeset
12 **Known issues:**
904b226fddf1 mod_pubsub_serverinfo: Update README to link to known issues
Matthew Wild <mwild1@gmail.com>
parents: 5811
diff changeset
13
904b226fddf1 mod_pubsub_serverinfo: Update README to link to known issues
Matthew Wild <mwild1@gmail.com>
parents: 5811
diff changeset
14 - [Issue #1841](https://issues.prosody.im/1841): 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).
904b226fddf1 mod_pubsub_serverinfo: Update README to link to known issues
Matthew Wild <mwild1@gmail.com>
parents: 5811
diff changeset
15
5803
f55e65315ba0 mod_pubsub_serverinfo: implemented all basic features
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5801
diff changeset
16 Installation
f55e65315ba0 mod_pubsub_serverinfo: implemented all basic features
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5801
diff changeset
17 ============
f55e65315ba0 mod_pubsub_serverinfo: implemented all basic features
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5801
diff changeset
18
f55e65315ba0 mod_pubsub_serverinfo: implemented all basic features
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5801
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: 5801
diff changeset
20
f55e65315ba0 mod_pubsub_serverinfo: implemented all basic features
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5801
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: 5801
diff changeset
22
f55e65315ba0 mod_pubsub_serverinfo: implemented all basic features
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5801
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: 5801
diff changeset
24
f55e65315ba0 mod_pubsub_serverinfo: implemented all basic features
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5801
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: 5801
diff changeset
26 Pub/Sub service:
f55e65315ba0 mod_pubsub_serverinfo: implemented all basic features
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5801
diff changeset
27
f55e65315ba0 mod_pubsub_serverinfo: implemented all basic features
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5801
diff changeset
28 admins = { "example.org" }
f55e65315ba0 mod_pubsub_serverinfo: implemented all basic features
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5801
diff changeset
29
f55e65315ba0 mod_pubsub_serverinfo: implemented all basic features
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5801
diff changeset
30 Configuration
f55e65315ba0 mod_pubsub_serverinfo: implemented all basic features
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5801
diff changeset
31 =============
f55e65315ba0 mod_pubsub_serverinfo: implemented all basic features
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5801
diff changeset
32
f55e65315ba0 mod_pubsub_serverinfo: implemented all basic features
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5801
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: 5801
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: 5801
diff changeset
35
f55e65315ba0 mod_pubsub_serverinfo: implemented all basic features
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5801
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: 5801
diff changeset
37
f55e65315ba0 mod_pubsub_serverinfo: implemented all basic features
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5801
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: 5801
diff changeset
39
f55e65315ba0 mod_pubsub_serverinfo: implemented all basic features
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5801
diff changeset
40 pubsub_serverinfo_node = "foobar"
f55e65315ba0 mod_pubsub_serverinfo: implemented all basic features
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5801
diff changeset
41
f55e65315ba0 mod_pubsub_serverinfo: implemented all basic features
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5801
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: 5801
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: 5801
diff changeset
44
f55e65315ba0 mod_pubsub_serverinfo: implemented all basic features
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5801
diff changeset
45 pubsub_serverinfo_publication_interval = 180 -- or any other number of seconds
5805
55b99f593c3a mod_pubsub_serverinfo: Disco/info cache TTL should be configurable
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5803
diff changeset
46
55b99f593c3a mod_pubsub_serverinfo: Disco/info cache TTL should be configurable
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5803
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: 5803
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: 5803
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: 5803
diff changeset
50
55b99f593c3a mod_pubsub_serverinfo: Disco/info cache TTL should be configurable
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5803
diff changeset
51 pubsub_serverinfo_cache_ttl = 1800 -- or any other number of seconds
5806
d4612e7f6724 mod_pubsub_serverinfo: Added 'Known Issues' section
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5805
diff changeset
52
5811
ce8f0e458ffa mod_pubsub_serverinfo: Add node on compatibility
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5808
diff changeset
53 Compatibility
ce8f0e458ffa mod_pubsub_serverinfo: Add node on compatibility
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5808
diff changeset
54 =============
ce8f0e458ffa mod_pubsub_serverinfo: Add node on compatibility
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5808
diff changeset
55
ce8f0e458ffa mod_pubsub_serverinfo: Add node on compatibility
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5808
diff changeset
56 Incompatible with 0.11 or lower.
ce8f0e458ffa mod_pubsub_serverinfo: Add node on compatibility
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5808
diff changeset
57
5806
d4612e7f6724 mod_pubsub_serverinfo: Added 'Known Issues' section
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5805
diff changeset
58 Known Issues / TODOs
d4612e7f6724 mod_pubsub_serverinfo: Added 'Known Issues' section
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5805
diff changeset
59 ====================
d4612e7f6724 mod_pubsub_serverinfo: Added 'Known Issues' section
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5805
diff changeset
60
5808
2465d5191ae9 mod_pubsub_serverinfo: Consider sibling vhosts 'connected'
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5807
diff changeset
61 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: 5807
diff changeset
62
2465d5191ae9 mod_pubsub_serverinfo: Consider sibling vhosts 'connected'
Guus der Kinderen <guus.der.kinderen@gmail.com>
parents: 5807
diff changeset
63 More generic server information (eg: user counts, software version) should be included in the data that is published.