<commit_before><!DOCTYPE html>
<html lang="en">
<head>
    <title>Openfire: Trunking Guide</title>
    <link href="style.css" rel="stylesheet" type="text/css">
</head>
<body>
    <div id="pageContainer">
        <a name="top"></a>
        <div id="pageHeader">
            <div id="logo"></div>
            <h1>Trunking Guide</h1>
        </div>
        <div class="navigation">
            <a href="index.html">&laquo; Back to documentation index</a>
        </div>
    
        <div id="pageBody">
            <h2 id="introduction">Introduction</h2>
            <p>Openfire can be configured to act as a gateway to transfer data between other XMPP domains. This document covers what the use-cases for such a setup, how to configure this functionality, and what known caveats with this approach are.</p>

            <h2 id="use-cases">Use cases</h2>
            <p>The trunking functionality of Openfire is typically used in one of two scenarios:</p>
            <ol>
                <li>Connection Mediation (allow data to flow between remote XMPP domains)</li>
                <li>Data Monitoring / Filtering (ensure that only allowable data enters or leaves an XMPP domain</li>
            </ol>

            <h3 id="use-case-connection-mediation">Use Case: Connection Mediation</h3>
            <p>
                The architecture of an XMPP network is similar to email; anyone can run their own XMPP domain and there is no central master domain. This federated open system approach allows users to interoperate with others on any domain. When users of
                one domain address data to users of another domain, servers of each domain will establish point-to-point connections between each-other, over which the data is exchanged. Multiple domains connecting to each other in a point-to-point manner
                creates a mesh-style network, as illustrated in <a href="#figure-1">figure 1</a>.
            </p>

            <div style="text-align: center;">
                <figure id="figure-1" style="display: inline-block;">
                    <img src="images/network-mesh.svg" alt="Mesh-style Network" style="width:30em;">
                    <figcaption>Figure 1 - Mesh-style Network.</figcaption>
                </figure>

                <figure id="figure-2" style="display: inline-block;">
                    <img src="images/network-hub-and-spoke.svg" alt="Hub-and-Spoke Network" style="width:30em;">
                    <figcaption>Figure 2 - Hub-and-Spoke Network.</figcaption>
                </figure>
            </div>

            <p>
                In certain environments, it is undesirable to have a mesh-style network. When, for example, it is hard or undesirable to create and maintain many technical connections, or when central auditing of data is desirable
                (see <a href="#use-case-data-monitoring-and-filtering">Use Case: Data Monitoring / Filtering</a>), then a Hub-and-Spoke network model, as shown in <a href="#figure-2">figure 2</a> is often a better fit than a mesh-style network. The main advantage
                of this style is that all domains only need to create and maintain a single connection to a single entity: the central hub. This central hub manages and passes through connections between all domains.
            </p>

            <p>
                To facilitate a Hub-and-Spoke approach with XMPP domains, the Trunking functionality of Openfire can be used. With this functionality enabled, an Openfire instance can act as the central 'hub' in such a network. In this mode, it can create and accept
                server-to-server connections with each individual XMPP domain in the network, passing stanzas from one domain to another, and vice versa.
            </p>

            <h3 id="use-case-data-monitoring-and-filtering">Use Case: Data Monitoring / Filtering</h3>
            <p>
                Openfire, in trunking mode, can be deployed as a border filtering device, to check the releasability of data that is exposed from within one network to another.
            </p>
            <p>
                A common scenario is one where a trusted network labels messages that are exchanged with a security label (as defined in <a href="https://xmpp.org/extensions/xep-0258.html">XEP-0258: Security Labels in XMPP</a> for example) that define the confidentiality
                of the content of the message. An Openfire trunk can be placed between two networks of domains that each have a different security clearance. The trunking Openfire server can filter data (through a <a href="plugin-dev-guide.html">plugin</a>), ensuring that
                only appropriately labelled messages are exchanged between the XMPP domains, rejecting, for example, messages labelled 'TOP SECRET' sent from an internal XMPP domain to an unrecognized or untrusted XMPP domain.
            </p>

            <h2 id="setup">Setup</h2>
            <p>
                The essence in getting an Openfire instance to act as a Trunking entity in your network is to have all other XMPP domains connect to this server, when they intend to connect to another remote domain. The Trunking entity needs to be configured to accept
                stanzas for the target domain. This is typically achieved through DNS manipulation. It will then process the data, and pass it on to the target domain.
            </p>

            <p>
                The server that is sending the message will attempt to establish a server-to-server connection with the target server. The sending server perform DNS lookups based on the domain name of the target server. The results of this lookup must be manipulated
                in such a way that the resulting IP address is that of the trunking server. Openfire can facilitate such DNS manipulation, as it allows DNS lookups to be skipped in favor of preconfigured hard-coded values. To configure such values, the
                property <tt>dnsutil.dnsOverride</tt> can be used. Note that these changes are needed only on the server(s) that send data through the trunking server. The trunking server itself should not need them.
            </p>
            <p>
                The expected format of the value of the <tt>dnsutil.dnsOverride</tt> property is a comma-sparated list of <code>{HOST,IP:PORT}</code>. Note that whitespace is not allowed, as shown in <a href="#example-dnsutil-propvalue">example 1</a>:
            </p>

            <div style="text-align: center;">
                <figure id="example-dnsutil-propvalue" style="margin: 2em;">
                    <code style="padding: 10px; border: 3px solid #e7eaee; border-radius: 5px">{saturn.example.org,198.51.100.4:5269},{jupiter.example.com,198.51.100.4:5269}</code>
                    <figcaption style="margin-top: 1.5em;">Example 1: <tt>dnsutil.dnsOverride</tt> property value, mapping two hostnames to the same IP address and port.</figcaption>
                </figure>
            </div>

            <p>
                To enable the trunking functionality in Openfire, the property <tt>xmpp.gateway.domains</tt> needs to be populated with a (comma-separated) list of XMPP domain names of remote XMPP domains that the Openfire server will forward data to.
            </p>

            <h3 id="setup-example">Full example</h3>

            <p>
                Let us imagine three XMPP domains, each domain consisting of one Openfire server. For simplicity's sake, we assume that the fully qualified domain name of each server is equal to the XMPP domain name that it serves:
            </p>

            <ul>
                <li><tt>saturn.example.org</tt> (<code>203.0.113.2</code>)</li>
                <li><tt>trunk.example.com</tt> (<code>198.51.100.4</code>)</li>
                <li><tt>mercury.example.net</tt> (<code>233.252.0.6</code>)</li>
            </ul>

            <p>
                The objective of this example is to allow users of the domains <tt>saturn.example.org</tt> and <tt>mercury.example.net</tt> to exchange XMPP stanzas without their servers creating direct connections to each-other, instead using <tt>trunk.example.com</tt> as a gateway.
                To achieve this, the following three steps are needed:
            </p>

            <ol>
                <li>
                    <p>
                        Openfire at <tt>trunk.example.com</tt> needs to be configured to allow trunking to both XMPP domains. To achieve this, it's property <tt>xmpp.gateway.domains</tt> is configured to use this value: <code>saturn.example.org,mercury.example.net</code>
                    </p>
                </li>
                <li>
                    <p><commit_msg>Update documentation/trunking-guide.html<commit_after><!DOCTYPE html>
<html lang="en">
<head>
    <title>Openfire: Trunking Guide</title>
    <link href="style.css" rel="stylesheet" type="text/css">
</head>
<body>
    <div id="pageContainer">
        <a name="top"></a>
        <div id="pageHeader">
            <div id="logo"></div>
            <h1>Trunking Guide</h1>
        </div>
        <div class="navigation">
            <a href="index.html">&laquo; Back to documentation index</a>
        </div>
    
        <div id="pageBody">
            <h2 id="introduction">Introduction</h2>
            <p>Openfire can be configured to act as a gateway to transfer data between other XMPP domains. This document covers what the use-cases for such a setup, how to configure this functionality, and what known caveats with this approach are.</p>

            <h2 id="use-cases">Use cases</h2>
            <p>The trunking functionality of Openfire is typically used in one of two scenarios:</p>
            <ol>
                <li>Connection Mediation (allow data to flow between remote XMPP domains)</li>
                <li>Data Monitoring / Filtering (ensure that only allowable data enters or leaves an XMPP domain</li>
            </ol>

            <h3 id="use-case-connection-mediation">Use Case: Connection Mediation</h3>
            <p>
                The architecture of an XMPP network is similar to email; anyone can run their own XMPP domain and there is no central master domain. This federated open system approach allows users to interoperate with others on any domain. When users of
                one domain address data to users of another domain, servers of each domain will establish point-to-point connections between each-other, over which the data is exchanged. Multiple domains connecting to each other in a point-to-point manner
                creates a mesh-style network, as illustrated in <a href="#figure-1">figure 1</a>.
            </p>

            <div style="text-align: center;">
                <figure id="figure-1" style="display: inline-block;">
                    <img src="images/network-mesh.svg" alt="Mesh-style Network" style="width:30em;">
                    <figcaption>Figure 1 - Mesh-style Network.</figcaption>
                </figure>

                <figure id="figure-2" style="display: inline-block;">
                    <img src="images/network-hub-and-spoke.svg" alt="Hub-and-Spoke Network" style="width:30em;">
                    <figcaption>Figure 2 - Hub-and-Spoke Network.</figcaption>
                </figure>
            </div>

            <p>
                In certain environments, it is undesirable to have a mesh-style network. When, for example, it is hard or undesirable to create and maintain many technical connections, or when central auditing of data is desirable
                (see <a href="#use-case-data-monitoring-and-filtering">Use Case: Data Monitoring / Filtering</a>), then a Hub-and-Spoke network model, as shown in <a href="#figure-2">figure 2</a> is often a better fit than a mesh-style network. The main advantage
                of this style is that all domains only need to create and maintain a single connection to a single entity: the central hub. This central hub manages and passes through connections between all domains.
            </p>

            <p>
                To facilitate a Hub-and-Spoke approach with XMPP domains, the Trunking functionality of Openfire can be used. With this functionality enabled, an Openfire instance can act as the central 'hub' in such a network. In this mode, it can create and accept
                server-to-server connections with each individual XMPP domain in the network, passing stanzas from one domain to another, and vice versa.
            </p>

            <h3 id="use-case-data-monitoring-and-filtering">Use Case: Data Monitoring / Filtering</h3>
            <p>
                Openfire, in trunking mode, can be deployed as a border filtering device, to check the releasability of data that is exposed from within one network to another.
            </p>
            <p>
                A common scenario is one where a trusted network labels messages that are exchanged with a security label (as defined in <a href="https://xmpp.org/extensions/xep-0258.html">XEP-0258: Security Labels in XMPP</a> for example) that define the confidentiality
                of the content of the message. An Openfire trunk can be placed between two networks of domains that each have a different security clearance. The trunking Openfire server can filter data (through a <a href="plugin-dev-guide.html">plugin</a>), ensuring that
                only appropriately labelled messages are exchanged between the XMPP domains, rejecting, for example, messages labelled 'TOP SECRET' sent from an internal XMPP domain to an unrecognized or untrusted XMPP domain.
            </p>

            <h2 id="setup">Setup</h2>
            <p>
                The essence in getting an Openfire instance to act as a Trunking entity in your network is to have all other XMPP domains connect to this server, when they intend to connect to another remote domain. The Trunking entity needs to be configured to accept
                stanzas for the target domain. This is typically achieved through DNS manipulation. It will then process the data, and pass it on to the target domain.
            </p>

            <p>
                The server that is sending the message will attempt to establish a server-to-server connection with the target server. The sending server perform DNS lookups based on the domain name of the target server. The results of this lookup must be manipulated
                in such a way that the resulting IP address is that of the trunking server. Openfire can facilitate such DNS manipulation, as it allows DNS lookups to be skipped in favor of preconfigured hard-coded values. To configure such values, the
                property <tt>dnsutil.dnsOverride</tt> can be used. Note that these changes are needed only on the server(s) that send data through the trunking server. The trunking server itself should not need them.
            </p>
            <p>
                The expected format of the value of the <tt>dnsutil.dnsOverride</tt> property is a comma-sparated list of <code>{HOST,IP:PORT}</code>. Note that whitespace is not allowed, as shown in <a href="#example-dnsutil-propvalue">example 1</a>:
            </p>

            <div style="text-align: center;">
                <figure id="example-dnsutil-propvalue" style="margin: 2em;">
                    <code style="padding: 10px; border: 3px solid #e7eaee; border-radius: 5px">{saturn.example.org,198.51.100.4:5269},{jupiter.example.com,198.51.100.4:5269}</code>
                    <figcaption style="margin-top: 1.5em;">Example 1: <tt>dnsutil.dnsOverride</tt> property value, mapping two hostnames to the same IP address and port.</figcaption>
                </figure>
            </div>

            <p>
                To enable the trunking functionality in Openfire, the property <tt>xmpp.gateway.enabled</tt> needs to be set to <code>true</code>, and the property <tt>xmpp.gateway.domains</tt> needs to be populated with a (comma-separated) list of XMPP domain names of remote XMPP domains that the Openfire server will forward data to.
            </p>

            <h3 id="setup-example">Full example</h3>

            <p>
                Let us imagine three XMPP domains, each domain consisting of one Openfire server. For simplicity's sake, we assume that the fully qualified domain name of each server is equal to the XMPP domain name that it serves:
            </p>

            <ul>
                <li><tt>saturn.example.org</tt> (<code>203.0.113.2</code>)</li>
                <li><tt>trunk.example.com</tt> (<code>198.51.100.4</code>)</li>
                <li><tt>mercury.example.net</tt> (<code>172.16.31.10</code>)</li>
            </ul>

            <p>
                The objective of this example is to allow users of the domains <tt>saturn.example.org</tt> and <tt>mercury.example.net</tt> to exchange XMPP stanzas without their servers creating direct connections to each-other, instead using <tt>trunk.example.com</tt> as a gateway.
                To achieve this, the following three steps are needed:
            </p>

            <ol>
                <li>
                    <p>
                        Openfire at <tt>trunk.example.com</tt> needs to be configured to allow trunking to both XMPP domains. To achieve this, it's property <tt>xmpp.gateway.domains</tt> is configured to use this value: <code>saturn.example.org,mercury.example.net</code>
                    </p>
                </li>
                <li>
                    <p>
{'fraction_non_alphanumeric': 0.08815962494997427, 'fraction_numerical': 0.010919901663712766, 'mean_word_length': 2.4011277464514875, 'pattern_counts': {'":': 0, '<': 301, '<?xml version=': 0, '>': 301, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 10, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6323854', 'n_tokens_mistral': 4772, 'n_tokens_neox': 4443, 'n_words': 1932}