Network Configuration Guide

Introduction

Having Openfire installed and running is one thing, but for users to make use of its services, they need to be able to connect to the server! This guide describes common network configurations to optimize the deployment of Openfire.

This guide contains the following topics

Terminology

XMPP Domain Name: The name of your Openfire/XMPP service (eg: example.org)). This identifies the service (and is part of the identifiers of the users on the service), but not necessarily the server on which Openfire is installed.
Server Host Name (FQDN): The network hostname of the server on which Openfire is installed (eg: xmpp.example.org)). This identifies the server, but not necessarily the service.

The distinction between XMPP domain name and server host name is important, even when it is a common occurrence for both values to be equal to each-other.

The XMPP domain name identifies the Openfire service, and thus is an important part of all identifiers. This value should be considered immutable, as changing the value would cause references to users or your server to break!

It is relatively easy, on the other hand, to change the address of the server on which Openfire is running. That typically involves updating DNS records.

DNS Settings

Chat clients (and other XMPP entities, such as remote servers) to make use of your XMPP service need a way to determine the address of the server on which Openfire is installed, so that they can initiate a network connection. This process is based on DNS lookups.

Basic configuration: A/AAAA records

An essential class of DNS records in this respect are the A and AAAA records. These are necessary to map the Server Host Name (FQDN) to the IP address on which it is reachable.

When the XMPP Domain Name and Server Host Name are equal to each-other (and Openfire is using standard ports), then having only A/AAAA records may suffice. Generally speaking, clients and remote servers use an A/AAAA lookup of the XMPP domain name as a fallback, when the more elaborate lookup (described below) is not available.

Full configuration: SRV records

If Openfire is running on a server that has a hostname that does not match the XMPP domain name, or if non-standard ports are being used, then additional DNS records are typically required for connectivity to be established. You may consider adding the following records even when you do not strictly require them, to replace an implicit configuration with an explicit one, which has benefits for long-term maintenance of the configuration.

To map between the XMPP Domain Name and Server Host Name (FQDN), DNS SRV records are used. These records allow for a range of configuration options, such as basic load balancing functionality.

In DNS SRV terms, Openfire provides not one, but two 'services':

xmpp-client: Defines the endpoint that is used by clients.
xmpp-server: Defines the endpoint that is used by (other) servers.

Both of these have an equivalent that uses a different method of encryption negotiation (DirectTLS rather than STARTTLS), which adds another two services:

xmpps-client: Defines the endpoint that is used by clients, using DirectTLS.
xmpps-server: Defines the endpoint that is used by (other) servers, using DirectTLS.

In all, four services are typically advertised through DNS SRV records. Following the DNS SRV syntax, one would create the following DNS SRV records, for an Openfire instance that uses example.org as its XMPP Domain Name, which is installed on a server whose Server Host Name (FQDN) is xmpp.example.org:

Example DNS SRV records


_xmpp-client._tcp.example.org. 86400 IN SRV 0 5 5222 xmpp.example.org.
_xmpp-server._tcp.example.org. 86400 IN SRV 0 5 5269 xmpp.example.org.
_xmpps-client._tcp.example.org. 86400 IN SRV 0 5 5223 xmpp.example.org.
_xmpps-server._tcp.example.org. 86400 IN SRV 0 5 5270 xmpp.example.org.

Configuration for additional services

Most Openfire instances expose additional XMPP services, such as the group-chat service typically called 'conference` (which is where chat rooms live) and a pub/sub service, which bears the name 'pubsub'. The full XMPP domain name of these services are subdomains of the XMPP domain name. The XMPP domain name of the default group chat service of Openfire thus is conference.example.org.

Clients connected directly to your Openfire instance will be able to make use of its services directly. Users of federated XMPP domains (those on other Openfire, or even other brand of XMPP servers), cannot. Their 'home' server will need a way to resolve the correct address of these services.

This again is achieved through DNS records. Often, A and AAAA records suffice. Complement the pre-existing A/AAA records for example.org with a records for conference.example.org, for example. Under similar conditions as described above, it is sometimes useful to have SRV records, as shown below.

Example DNS SRV records for a group chat service


_xmpp-server._tcp.conference.example.org. 86400 IN SRV 0 5 5269 xmpp.example.org.
_xmpps-server._tcp.conference.example.org. 86400 IN SRV 0 5 5270 xmpp.example.org.

Note xmpp-client and xmpps-client records are not needed for these server-sided services - the user's server connects to remote services on their behalf.

Admin Console DNS hints

The Openfire admin console performs a basic check of the DNS configuration in your environment, and will warn if it detects potential issues. When issues are detected, a suggested set of DNS SRV records is provided.

Admin console DNS SRV verification page, warning about missing records.

It is important to realize that DNS resolution might be affected by a number of factors, that can affect the Admin Console's capability to detect the correct state of an environment. This can lead to both false positive and false negative results, in regard to these DNS hints.

IPv6 support

Network connectivity is based on the Internet Protocol. Traditionally IPv4 support is widespread. Openfire fully supports the newer IPv6 protocol, although some specific configuration may be required.

This section assumes that IPv6 is available on your network, and support is provided by your Operating System.

The most straightforward difference between IPv4 and IPv6 is its addressing. IPv4 addresses typically are displayed in the form of four numbers (eg: 203.0.113.81). IPv6 addresses are larger. They are typically displayed as eight groups of four hexadecimal digits (eg: 2001:0db8:0000:0000:0000:2b3e:3d80:61a1).

Network Interfaces

By default, Openfire will bind to all network interfaces, including IPv6 interfaces. When Openfire has been configured to bind to a specific interface, this may exclude IPv6 connectivity. The configuration can be found in the openfire.xml configuration file.

Example openfire.xml configuration for XMPP binding interface


<!-- Network settings. By default, Openfire will bind to all network interfaces.
     Alternatively, you can specify a specific network interfaces that the server
     will listen on. For example, 127.0.0.1. This setting is generally only useful
     on multi-homed servers. -->
<!--
<network>
    <interface></interface>
</network>
-->

The openfire.xml configuration file can contain a similar element to define on what interface the Admin Console is accessible.

Example openfire.xml configuration for admin console binding interface


<adminConsole>
    <!-- Disable either port by setting the value to -1 -->
    <port>9090</port>
    <securePort>9091</securePort>
    <interface>127.0.0.1</interface>
</adminConsole>

Both can be used to bind to an IPv6 network interface.

DNS records

If the server on which Openfire is running can be connected to using IPv6, it will have an IPv6 address. When that's the case, then a DNS AAAA record must be created to map the hostname of the server to its address. This is analogous to an A record, that maps an IPv4 address to the hostname.

Java Networking Configuration

Openfire is an application that runs in a Java virtual machine. Openfire's IPv6 support is primarily controlled by standard Java Networking Properties. The following properties are typically provided. Please refer to the documentation of your version of Java for details.

java.net.preferIPv4Stack: If IPv6 is available on the operating system then sockets used by Openfire will, by default, be IPv6 capable. This lets Openfire connect to, and accept connections from, both IPv4 and IPv6 hosts. In case that you would rather use IPv4 only sockets, then this property can be set to true. The implication is that it will not be possible for Openfire to communicate with IPv6 only clients and servers. Openfire's startup script does not include this property. It thus follows Java's default.
java.net.preferIPv6Addresses: When dealing with a host which has both IPv4 and IPv6 addresses, this property defines the preferred behavior. When set to false, Openfire is configured to prefer using IPv4 addresses over IPv6 ones. This property can be set to true to change that preference and use IPv6 addresses over IPv4 ones where possible, or system to preserve the order of the addresses as returned by the operating system. Openfire's startup script by default sets the value for this property to system, thus following the operating system.

Happy Eyeballs

Most of the network connections over which XMPP data is transmitted are initiated by remote entities, typically clients. There is, however, one particular type of connection that is initiated by Openfire itself: an (outbound) server-to-server connection. These connections are established when users of the local server wish to connect with those on another domain. This is commonly referred to as 'federating'.

When Openfire establishes an outbound connection to another XMPP server, it makes use of the Happy Eyeballs approach. This approach aims to reduce any user-visible delay when establishing server-to-server connections. It does so by starting multiple connections in parallel, preferring IPv6 connectivity over IPv4 connectivity, and interleaving IPv4 and IPv6 connection attempts.

The following properties are used to configure the behavior or the 'Happy Eyeballs' implementation:

xmpp.server.connection-attempt-delay: A fixed delay for how long to wait before starting the next connection attempt. Defaults to 250ms.
xmpp.server.resolution-delay: The time to wait for a response for the 'preferred IP family' after receiving a response for another family. Defaults to 50ms.
xmpp.server.resolution-timeout: The maximum amount of time to wait for successful resolution of a host of a target domain. Defaults to 5 minutes.
xmpp.server.connection-max-workers: The maximum amount of worker threads attempting to set up a socket connection to a target remote XMPP domain. A value of '1' will effectively make 'Happy Eyeballs' impossible (as that requires concurrent connection attempts). Defaults to 8.

Lastly, the family (IPv4 or IPv6) preferred by the Happy Eyeballs algorithm is based on Java Networking Configuration, and follows the preferences configured through those settings.