mod_pubsub_serverinfo

Exposes server information over Pub/Sub per XEP-0485: PubSub Server Information.

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 will contain a ‘remote-domain’ element for inbound and outgoing s2s connections. These elements will be named only when the remote domain announces support (‘opts in’) too.

Known issues:

• Issue #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 community module can be used.

Configuration

Loading the module

Simply enable this module on the hosts/components that you want to publish information for. Note that, as with most other modules, adding it to the global modules_enabled will automatically load it on all VirtualHosts on your server:

modules_enabled = {
    ...
    "pubsub_serverinfo";
    ...
}

Note that adding it to the global modules_enabled won’t load it on any Component hosts on your server. If you want to publish info about those, you also need to add it to a modules_enabled setting under that Component, for example:

Component "rooms.example.com" "muc"
    modules_enabled = {
        "pubsub_serverinfo";
    }

Specifying the publish destination

This module publishes information to any XMPP pubsub service, which could be local (i.e. served by the same Prosody instance) or remote (via server-to-server connections).

The destination to publish to is controlled by two settings:

• pubsub_serverinfo_service
• pubsub_serverinfo_node

As usual, these options can be set in the global section (inherited by all hosts/component) or underneath each VirtualHost/Component to apply to that VirtualHost/Component only.

If unset, pubsub_serverinfo_service will default to pubsub.<domain> - that is, it will try to publish to a pubsub service that is on the pubsub subdomain of the host it is publishing about. For example, if you load the module on example.com it will default to publishing to pubsub.example.com. If this is incorrect, you should set pubsub_serverinfo_service to a valid pubsub service address.

The pubsub_serverinfo_node option defaults to "serverinfo". Note that if you have multiple hosts publishing to the same pubsub service, you must set this to something unique for each one, otherwise they will overwrite each other.

Pubsub service configuration

As mentioned, you can publish to a local or remote pubsub service. The publish commands will come from the reporting domain(s) where the module is loaded (e.g. example.com), so those domains must be permitted to publish to the destination pubsub service you have chosen.

If you want to run a local pubsub service in the same Prosody instance, you can use this configuration:

Component "pubsub.example.com" "pubsub"
    -- Grant permission for example.com to publish here, by simply making it
    -- an admin:
    admins = { "example.org" }

Other settings

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 is 300 seconds (5 minutes). To change this simply put in the config:

    pubsub_serverinfo_publication_interval = 180 -- or any other number of seconds

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 discovery request to each remote domain. To prevent a continuous flood of disco/info requests, the response to these requests is cached. By default, a cached value will remain in cache for one hour. This duration can be modified by adding this configuration option:

    pubsub_serverinfo_cache_ttl = 1800 -- or any other number of seconds

To include the count of active (within the past 30 days) users:

    pubsub_serverinfo_publish_user_count = true

Enabling this option will automatically load mod_measure_active_users, which must be installed.

Compatibility

Incompatible with 0.11 or lower.

Known Issues / TODOs

The reported data does not contain the optional ‘connection’ child elements. These can be used to describe the direction of a connection.

Common Configuration Issues

Incorrect permissions on pubsub service

The XMPP domain itself (for example, example.org) must be allowed to publish to the chosen pubsub service, e.g. by making it an admin of that service. Sometimes people mistakenly assume a user JID (e.g., admin@example.org) should be an admin. See the example above for correct configuration.

Enabling the module on the wrong host

mod_pubsub_serverinfo must be enabled globally or within a virtual host, not inside the PubSub component (unless you want to publish info about that component). Generally you are instructing other hosts to publish data to the pubsub service, not extending the pubsub service itself.

Additionally, be aware that adding mod_pubsub_serverinfo to the global modules_enabled will not load it on any Components by default, you must still specify that explicitly (see the earlier configuration example).

Conditional dependency on mod_measure_active_users

Publishing user counts requires mod_measure_active_users. This module will be loaded automatically if user count publication is enabled, but it must be installed on the system for this to succeed.

DNS records for the PubSub service

External servers must be able to connect to the PubSub service. Ensure the hostname of the PubSub service has appropriate A/AAAA and SRV records so remote servers can discover and reach the service. You can use the ‘prosodyctl check’ command to help with this.

sudo prosodyctl install --server=https://modules.prosody.im/rocks/ mod_pubsub_serverinfo