DNS configuration in Jabber/XMPP
XMPP is a decentralized network, and relies heavily on DNS to achieve this. Any Jabber/XMPP user is identified by their address (JID) in the form 'username@domain', where the domain identifies the server that their account exists on.
In order for clients to connect and log in, they need to find the IP address of the server associated with their JID. Similarly remote servers which need to forward a message to a user also need to contact that user's server to pass that message on.
This is achieved by looking up the domain in DNS, and most domains will need no extra configuration for XMPP. There are cases however that you will want or need to add/update your DNS records - this page explains when, why and how. None of this documentation is specific to Prosody, and applies to any XMPP service in general.
Note: How you configure your DNS records is dependent on your provider - many have web-based control panels to allow it. Unfortunately some have limited support for the different record types. If yours is missing support for configuring anything described on this page, we encourage you to email your provider and ask them to update set your records for you, and even better to fix their control panel!
Tip: Prosody comes with a tool to perform basic sanity checks. To check if your DNS records look correct, run:
prosodyctl check dnsA records
A records are the standard record type, and are used in XMPP when there are no XMPP SRV records for a domain. This allows simple setups to work with no extra DNS configuration.
SRV records
SRV records essentially allow transparent DNS-level redirects of XMPP services to another domain or port. A simple example is when you want users to have addresses like username@example.com, but your XMPP server is really installed on xmpp.example.com. In principle they work the same way as MX records do for email.
SRV records are not XMPP-specific, but are defined for a number of protocols. XMPP actually has 2 different types of SRV records, those for clients to use (client-to-server, or 'c2s'), and those for other XMPP servers to use when they look up your domain (server-to-server, or 's2s').
Following the previous example of a server 'example.com' wanting to delegate its XMPP services to the server at 'xmpp.example.com', here are some example records:
| record name | TTL | class | type | priority | weight | port | target |
|---|---|---|---|---|---|---|---|
| _xmpp-client._tcp.example.com. | 3600 | IN | SRV | 0 | 5 | 5222 | xmpp.example.com. |
| _xmpp-server._tcp.example.com. | 3600 | IN | SRV | 0 | 5 | 5269 | xmpp.example.com. |
The bold text indicates parts of the record that you can change. The underlined bold text indicates parts of the record that you must replace with your domain (in this case example.com), and your target domain (in this case xmpp.example.com), respectively.
The target domain MUST be an existing A record of the target server, it cannot be an IP address, and cannot be a CNAME record.
The 3600 in this example is the TTL (time-to-live), it tells other servers how long they should cache your record for - a higher number will reduce DNS traffic, and result in slightly faster connections (since DNS info will be more likely to be cached, and won't need to be re-fetched). A lower TTL is more useful if you are going to be changing your record, since you have to wait for the TTL until all caches have expired your old record.
The 0 and 5 are the record's priority and weight. These values are specific to SRV records, and allow you to have multiple targets with different priorities (e.g. for load balancing or fallback in case of a down server) - lower priority targets are tried first. The weight is used to bias resolvers towards certain targets in case of a priority tie. Most services will not need to change these values, and 0 and 5 are sensible defaults.
Next is the port the service is running on. Clients will typically connect to 5222, and servers will connect to 5269, and these are Prosody's defaults. You are free to change them if you wish (for example to run multiple XMPP servers on a single machine), if you do this then be sure to inform Prosody of the port numbers in the configuration file.
Note about certificates: When requesting/generating certificates for your domain, you need your certificates to be valid for the virtual host name, not the domain that your SRV records point to. For more information see 'Which domain?' in our certificate documentation.
Direct TLS SRV records
XEP-0368 describes SRV records for XMPP over TLS, which uses records like this:
| record name | TTL | class | type | priority | weight | port | target |
|---|---|---|---|---|---|---|---|
| _xmpps-client._tcp.example.com. | 3600 | IN | SRV | 0 | 5 | 5223 | xmpp.example.com. |
| _xmpps-server._tcp.example.com. | 3600 | IN | SRV | 0 | 5 | 5270 | xmpp.example.com. |
Note the s in _xmpps and the alternate ports, which need explicit configuration. Search for direct_tls_ports in the port numbers in the configuration file.
TXT records
Use of _xmppconnect TXT records to advertise BOSH and WebSockets is insecure, their use is not recommended. Instead use the https lookup method.
Subdomains
If you provide services on subdomains, such as MUC chatrooms and other components, that you wish to be accessible from other servers, these will require DNS entries too. If you are using the standard server-to-server port (5269), an A record is enough. If you are using custom ports, or need to run Prosody on another hostname (e.g. xmpp.example.com) then you will need to specify SRV records, for _xmpp-server only. For example:
| record name | TTL | class | type | priority | weight | port | target |
|---|---|---|---|---|---|---|---|
| _xmpp-server._tcp.conference.example.com. | 3600 | IN | SRV | 0 | 5 | 5269 | xmpp.example.com. |
An explanation of each of these fields is given in the SRV records section above.