What are components?

Components are extra services on a server which are available to clients, usually on a subdomain of the main server.

Example components might be chatroom servers, file upload services, and so on.

DNS

If a component needs to be accessed from remote servers over s2s, you must have a record for it in DNS (either A or _xmpp-server._tcp SRV records), see DNS configuration in Jabber/XMPP for more information.

For services that are only used by clients on the same Prosody instance (such as file upload services, which are typically restricted to local users) you do not need any DNS record or certificate for the component at the XMPP level.

Some services may need to be accessible outside of XMPP - for example file upload services need to be accessed via HTTP, however you can reconfigure those services to use a different hostname that you already have DNS and certificates for. Check each module’s documentation for configuration details.

Encryption

Similarly to DNS, if you are accepting server-to-server connections then you will also need a valid certificate for your component’s domain. You can obtain a dedicated certificate, use a multi-domain certificate, or a wildcard certificate.

For local-only services, you do not need certificates for your component domain, because traffic to and from the component stays entirely inside Prosody.

See our dedicated documentation on certificates.

Discovery

When clients log in, they need to be able to find which services they can use.

Prosody does not automatically tell every client about every component on the server, as this is often not what you want in a multi-domain setup. So here are the rules about which components are “linked”:

• Prosody will automatically link components to a VirtualHost if the Component is a direct subdomain of the VirtualHost’s domain. For example, groups.example.com will be linked to the VirtualHost example.com, but groups.xmpp.example.com would not be automatically linked.
• Components can be manually linked using the disco_items option. For more info, see the mod_disco documentation.

Notably, it is a common misconception that placement, order or indentation in the configuration file can influence which components “belong” to a VirtualHost. This is not the case.

Since Prosody 13.0+, prosodyctl check config command will warn you if you have any Components that are not linked to a VirtualHost.

Adding an internal component

To add a component, you simply add a line to the config file specifying the hostname, and the plugin you wish to use for the component.

An example of adding the Prosody MUC component would be:

Component "groups.example.com" "muc"

Component "groups.example.com" "muc"
modules_enabled = {
    "muc_mam";
}

Adding an external component

Prosody supports all external components that use the XEP-0114 component protocol (practically all do).

Example external components include Slidge, which we recommend if you wish to bridge your Prosody server to legacy messaging services such as Facebook Messenger, WhatsApp and Telegram and more.

Documentation for the external components you use will typically tell you what configuration you need on the server.

To add an external component, you need to tell Prosody the domain that the component will use, and a password (or 'secret'). The configuration (domain, secret) must be configured the same in both Prosody’s config file, and the external component’s configuration.

If your component software requires a port number, Prosody defaults to port 5347 for component connections.

In Prosody’s config, definition of external components is the same as for internal components, except no internal plugin is specified after the domain:

-- Example Telegram bridge/gateway
Component "telegram.example.org"
         component_secret = "mysecretcomponentpassword"

-- Global config section --
component_ports = { 8888 }
component_interfaces = { "192.168.0.10" }