2.3.1. Topic Resolution Across the Gateway

To establish topic resolution in an already-running UM Gateway, the following typically occurs in an example like the above figure.

1. A receiver in topic resolution domain 2 issues a TQR for topic AAA.

2. Portal E2 receives the TQR and requests that portal E1 find a TIR for AAA on topic resolution domain 1. At this point, we can say that interest for topic AAA has been discovered within the gateway.

3. E1 immediately responds with three actions: a) create a proxy receiver for topic AAA, which b) sends a TQR for AAA on domain 1, and c) issues a Topic Interest message for the benefit of any other portals that may exist in this gateway.

4. A source for topic AAA in domain 1 issues a TIR.

5. E1's AAA proxy receiver requests that E2 (and any other portals in the gateway) create a proxy source for AAA.

6. E2 creates proxy source AAA and issues a TIR to domain 2, thus completing topic resolution.

2.3.2. Interest and Use Queries

When a UM Gateway first starts, its endpoint portals issue a brief series of Topic Resolution Request messages to their respective topic resolution domains. This provokes quiescent receivers (and wildcard receivers) into sending TQRs, indicating interest in the various topics. Each portal then records this interest. The gateway uses a periodic purge cycle to detect when there is no longer any interest in the topic (i.e. all receivers for a topic have been deleted), and removes it from the portals.

After a gateway has been running, endpoint portals issue periodic Topic Use Queries and Pattern Use Queries (collectively referred to as simply Use Queries). Use Query Responses from UM contexts confirm that the receivers for these topics indeed still exist, thus maintaining these topics on the interest list. Autonomous TQRs also refresh interest and have the effect of suppressing the generation of Use Queries.

In the case of multi-hop gateway configurations, gateways cannot detect interest for remote contexts via Use Queries or TQRs. They do this instead via Interest Messages. A portal generates periodic interest messages, which are picked up by adjacent gateways (i.e., the next hop over), at which time interest is refreshed.

Intervals, limits, and durations for these topic resolution and interest mechanisms can be adjusted via gateway configuration options (see UM Gateway Configuration).

2.3.3. Gateway Keepalive

To maintain a reliable connection, gateways exchange Gateway Keepalive signals when connected via peer portals. Keepalive intervals and connection timeouts are configurable, and you can also set the gateway to send keepalives only when traffic is idle (default). See <gateway-keepalive>.

2.3.4. Proxy Sources and Receivers

The domain-id is used by Interest Messages and other internal and gateway-to-gateway traffic to ensure forwarding of all messages (payload and topic resolution) to the correct recipients. This also has the effect of not creating proxy sources/receivers where they are not needed. Thus, gateways create proxy sources and receivers based solely on receiver interest.

If more than one source sends on a given topic, the receiving portal's single proxy receiver for that topic receives all messages sent on that topic. The sending portal, however creates a proxy source for every source sending on the topic. The UM Gateway maintains a table of proxy sources, each keyed by an Originating Transport ID (OTID). This enables proxy receiver to forward each message to the correct proxy source.

2.3.5. Multi-Hop Forwarding

Consider a simple example UM Gateway deployment, as shown in Multi-Hop Network Example.

In this diagram, gateway A has two endpoint portals, connected to topic resolution domains 1 and 2. gateway B also has two endpoint portals that bridge domains 2 and 3. (Endpoint portal names reflect the topic resolution domain to which they connect. For example, gateway A endpoint E2 interfaces topic resolution domain 2.)

Topic resolution domain 1 has a source for topic AAA, and domain 3, an AAA receiver. The following sequence of events enables the forwarding of topic messages from source AAA to receiver AAA.

1. Receiver AAA queries (issues a TQR) for a source.

2. Gateway B, endpoint E3 (B-E3) receives the TQR and requests that any other portals in the gateway forward any AAA advertisements.

3. In response, B-E2 creates a proxy receiver for AAA and sends a Topic Interest message for AAA to topic resolution domain 2. (The proxy receiver also issues a TQR.)

4. Gateway A, endpoint E2 (A-E2) receives this Topic Interest message and requests that any other portals in the gateway forward any AAA advertisements.

5. In response, A-E1 creates a proxy receiver for AAA and sends a Topic Interest message (and TQR) for AAA to domain 1.

6. Source AAA responds to the TQR by sending a TIR for topic AAA.

7. The AAA proxy receiver created by A-E1 receives this TIR and requests that all gateway A portals with an interest in topic AAA create a proxy source for AAA.

8. In response, A-E2 creates a proxy source which sends a TIR for topic AAA via domain 2.

9. The AAA proxy receiver created by B-E2 receives this TIR and requests that all gateway B portals with an interest in topic AAA create a proxy source for AAA.

10. In response, B-E3 creates a proxy source, which sends a TIR for topic AAA via domain 3.

11. Topic AAA has now been resolved across both gateways, which forward all topic messages sent by source AAA to receiver AAA.

2.4.1. Hop Count

When the egress portal of a gateway creates a proxy source to forward, in effect, the original source's topic advertisement, it increments the hop count by one. In the Multi-hop example presented earlier, gateway A, endpoint E2 (A-E2) and gateway B, endpoint E3 (B-E3) would each increment the hop count, resulting in receiver AAA receiving a TIR with a hop count = 2.

2.4.2. Portal Costs

The UM Gateway lets you assign a cost to a portal. As with the hop count, when a portal creates a proxy source, it adds the portal's configured cost to the topic cost in the TIR. By default, the cost associated with a portal is 0. Using the Multi-hop example again, setting portal A-E2's cost to 3 increases the topic's cost by that much. If portal B-E3's cost is 2, the topic's cost (and TIR cost), as received by receiver AAA, is now 5. The UM Gateway uses the cost to ensure that proxy receivers connect via the most efficient path to/from their source.

2.4.3. Resolver Cache's Stored Cost Values Prevents Duplicates

The UM Resolver Cache stores TIRs to help receivers find sources. In addition to transport session information, the stored TIR contains the OTID, hop count and cost values. This information can be used by receivers to select the lowest cost source if a source sends over multiple network paths.

In more complex network topologies, messages from the same source may traverse multiple paths and therefore, arrive from different proxy sources and different transport sessions. If a receiver looks up a topic in the cache and finds two TIRs with the same OTID but different transport sessions, it chooses the OTID with the lowest cost and joins that transport to receive messages. This prevents receiving duplicate messages from the same source.

A UM receiver always treats advertisements for the same topic with the same OTID as equivalent transport sessions, and joins only one of them. In the event that the receiver detects an EOS on the joined transport session, one of any remaining equivalent transport sessions can be joined.

For Multicast Immediate Messages (MIM) traffic, UM receivers keep a sequence number map for every OTID they have received messages from and reject any messages that have already been received.

2.4.4. Applications Can Also Set the Topic Cost

Your application can change the cost of a topic in the receiving application's context using a callback ( source_cost_evaluation_function) that the UM Gateway uses in lbm_src_cost_function_cb(). The gateway invokes this function whenever it receives an advertisement containing cost information. With a multiple-path topology, the gateway always forwards advertisements and messages via the least costly path, using lbm_src_cost_function_cb() to determine the cost.

You can supply a callback with source_cost_evaluation_function to affect this cost determination, increasing the cost of less desirable paths or completing filtering out certain paths. The gateway passes the topic name, hop count, and cost to the configured callback, which returns an integral cost value the gateway assigns to the topic. If you do not set source_cost_evaluation_function, a default function returns the cost as passed to it.

2.10.1. Resilience Considerations

You should consider the following issues when developing your approach to gateway resilience.

4.1.1. Setting Individual Endpoint Options

When setting endpoint options, name the context of each endpoint in the gateway's XML configuration file.

<portals>
    <endpoint>
        <name>Endpoint_1</name>
        <domain-id>1</domain-id>
        <source-context-name>endpt_1</source-context-name>
        <lbm-attributes>
            <option name="request_tcp_interface" scope="context" value="#.#.#.0/24" />
        </lbm-attributes>
    </endpoint>
    <endpoint>
        <name>Endpoint_2</name>
        <domain-id>2</domain-id>
        <receiver-context-name>endpt_2</source-context-name>
        <lbm-attributes>
            <option name="request_tcp_interface" scope="context" value="#.#.#.0/24" />
        </lbm-attributes>
    </endpoint>
</portals>
       

Then assign configuration templates to those contexts in the UM XML configuration file.

<application name="tnwgd" template="global">
    <contexts>
        <context name="endpoint_1" template="endpt-1-options">
            <sources />
        </context>
        <context name="endpoint_2" template="endpt-2-options">
            <sources />
        </context>
    </contexts>
</application>
       

You specify the unique options for each of this gateway's two endpoints in the UM XML configuration <templates> section used for endpt-1-options and endpt-2-options.

4.1.2. UM Gateway and UM XML Configuration Use Cases

One advantage of using UM XML configuration files with the UM Gateway is the ability to assign unique UM attributes to the topics and contexts used for the proxy sources and proxy receivers the gateway creates. Plain text UM configuration files cannot assign UM attributes to the proxy sources and receivers based on topic. The following example shows how to assign a different LBTRM multicast address to a source based on its topic.

Create a new UM XML configuration template for the desired topic name.

<template name="custom-topic-template">
     <options type="source">
           <option name="transport_lbtrm_multicast_address" default-value="#.#.#.#"/>
     </options>
</template>
           

Then include this template in the <application> element associated with the gateway.

<application name="tnwgd" template="global-options">
     <contexts>
           <context>
                <sources template="source-options">
                     <topic topicname="custom_topic_name" template="custom-topic-template" />
                </sources>
           </context>
     </contexts>
</application>
           

This assigns the specified UM options to sources created on a particular topic.

It is also possible to assign UM attributes directly in the <application> tag. For example, the following specifies that a particular topic should use LBTRU transport and a unicast resolver address.

<application name="tnwgd" template="tnwgd-common">
    <contexts>
        <context>
            <sources template="source-template">
                <topic topicname="LBTRU_TOPIC">
                    <options type="source">
                        <option name="transport" default-value="lbtru" />
                        <option name="resolver_unicast_address" default-value="#.#.#.#" />
                    </options>
                </topic>
            </sources>
        </context>
    </contexts>
</application>
           

<?xml version="1.0" encoding="UTF-8" ?>
<um-configuration version="1.0">
<templates>
<template name="tnwgd-common">
    <options type="source">
        <option name="transport" default-value="tcp" />
    </options>
    <options type="context">
        <option name="request_tcp_interface" default-value="#.#.#.#/#" />
        <option name="transport_tcp_port_low" default-value="#" />
        <option name="transport_tcp_port_high" default-value="#" />
        <option name="resolver_multicast_address" default-value="#.#.#.#"/>
    </options>
</template>
<template name="rm-source">
    <options type="source">
        <option name="transport" default-value="lbtrm" />
        <option name="transport_lbtrm_multicast_address" default-value="#.#.#.#"/>
    </options>
</template>
</templates>
<applications>
    <application name="tnwgd" template="tnwgd-common">
        <contexts>
            <context>
                <sources template="rm-source">
                    <topic topicname="LBTRM_TOPIC" template="rm-source" />
                    <topic topicname="LBTRU_TOPIC">
                        <options type="source">
                            <option name="transport" default-value="lbtru" />
                            <option name="resolver_unicast_address" default-value="#.#.#.#" />
                        </options>
                    </topic>
                </sources>
            </context>
            <context name="endpt_1" template="rm-source">
                <sources template="rm-source"/>
            </context>
        </contexts>
    </application>
</applications>
</um-configuration> 
               

<?xml version="1.0" encoding="UTF-8" ?>
<tnw-gateway version="1.0">
    <daemon>
        <log type="console"/>
        <xml-config>sample-config.xml</xml-config>
    </daemon>
    <portals>
      <endpoint>
         <name>Endpoint_1</name>
         <domain-id>1</domain-id>
         <lbm-attributes>
            <option name="context_name" scope="context" value="endpt_1" />
            <option name="request_tcp_interface" scope="context" value="#.#.#.0/24" />
         </lbm-attributes>
      </endpoint>
      <endpoint>
         <name>Endpoint_2</name>
         <domain-id>2</domain-id>
         <lbm-attributes>
            <option name="request_tcp_interface" scope="context" value="#.#.#.0/24" />
         </lbm-attributes>
      </endpoint>
      <endpoint>
         <name>Endpoint_3</name>
         <domain-id>3</domain-id>
         <lbm-attributes>
            <option name="request_tcp_interface" scope="context" value="#.#.#.0/24" />
         </lbm-attributes>
      </endpoint>
    </portals>
</tnw-gateway> 
               

5.1.1. UM Configuration Files

Sources in LAN1 use lan1.cfg and the receivers in LAN2 use lan2.cfg.

## Major Options##
source transport lbtrm

## Multicast Resolver Network Options##
context resolver_multicast_interface 10.29.2.0/24
context resolver_multicast_address 225.7.32.85
context resolver_multicast_port 13965

##Transport LBT-RM Network Options##
context transport_lbtrm_multicast_address_low 225.7.33.85
context transport_lbtrm_multicast_address_high 225.7.33.89
context transport_lbtrm_source_port_low 24000
context transport_lbtrm_source_port_high 24999

##Transport LBT-RM Operation Options##
context transport_lbtrm_data_rate_limit 100000000
context transport_lbtrm_retransmit_rate_limit 500000
receiver transport_lbtrm_activity_timeout 10000

##Transport LBT-RU Network Options##
receiver transport_lbtru_interface 10.29.2.0/24
source transport_lbtru_interface 10.29.2.0/24

##Transport LBT_RU Operation Options##
context transport_lbtru_data_rate_limit 1000000
context transport_lbtru_retransmit_rate_limit 500000
receiver transport_lbtru_activity_timeout 10000

##Multicast Immediate Messaging Network Options##
context mim_address 225.7.32.100

##Request Network Options##
context request_tcp_interface 10.29.2.0/24

##Transport TCP Network Options##
receiver transport_tcp_interface 10.29.2.0/24
source transport_tcp_interface 10.29.2.0/24
context transport_tcp_port_low 18000
context transport_tcp_port_high 18999
         

## Major Options##
source transport lbtrm

## Multicast Resolver Network Options##
context resolver_multicast_interface 10.29.3.0/24
context resolver_multicast_address 225.8.32.85
context resolver_multicast_port 13965

##Transport LBT-RM Network Options##
context transport_lbtrm_multicast_address_low 225.8.33.85
context transport_lbtrm_multicast_address_high 225.8.33.89
context transport_lbtrm_source_port_low 25000
context transport_lbtrm_source_port_high 25999

##Transport LBT-RM Operation Options##
context transport_lbtrm_data_rate_limit 100000000
context transport_lbtrm_retransmit_rate_limit 500000
receiver transport_lbtrm_activity_timeout 10000

##Transport LBT-RU Network Options##
receiver transport_lbtru_interface 10.29.3.0/24
source transport_lbtru_interface 10.29.3.0/24

##Transport LBT_RU Operation Options##
context transport_lbtru_data_rate_limit 1000000
context transport_lbtru_retransmit_rate_limit 500000
receiver transport_lbtru_activity_timeout 10000

##Multicast Immediate Messaging Network Options##
context mim_address 225.8.32.100

##Request Network Options##
context request_tcp_interface 10.29.3.0/24

##Transport TCP Network Options##
receiver transport_tcp_interface 10.29.3.0/24
source transport_tcp_interface 10.29.3.0/24
context transport_tcp_port_low 17000
context transport_tcp_port_high 17999
         

5.1.2. UM Gateway Configuration

This example uses the two-lans.xml configuration file, which essentially consists of two endpoint portal configurations. If you notice in the daemon section, we have turned on monitoring for the all endpoint portals in the gateway. The configuration specifies that all statistics be collected every 5 seconds and uses the lbm transport module to send statistics to your monitoring application, that runs in LAN 1. See also Monitoring LBM. The Web Monitor has also been turned on to monitor the performance of the gateway.

<?xml version="1.0" encoding="UTF-8" ?>
<!-- UM GW xml file- 2 endpoint portals -->
<tnw-gateway version="1.0">
  <daemon>
    <log type="console"/>
    <lbm-license-file>lic0014.txt</lbm-license-file>
    <monitor interval="5">
      <transport-module module="lbm" options="config=lan1.cfg"/>
    </monitor>
    <web-monitor>*:15304</web-monitor>
  </daemon>
  <portals>
    <endpoint>
      <name>LAN1</name>
      <domain-id>1</domain-id>
      <lbm-config>lan1.cfg</lbm-config>
    </endpoint>
    <endpoint>
      <name>LAN2</name>
      <domain-id>2</domain-id>
      <lbm-config>lan2.cfg</lbm-config>
    </endpoint>
  </portals>
</tnw-gateway>
         

5.2.1. UM Configuration Files

Sources in LAN1 use lan1.cfg and the receivers in LAN2 and LAN3 use lan2.cfg and lan3.cfg, respectively.

## Major Options##
source transport lbtrm

## Multicast Resolver Network Options##
context resolver_multicast_interface 10.29.2.0/24
context resolver_multicast_address 225.7.32.85
context resolver_multicast_port 13965

##Transport LBT-RM Network Options##
context transport_lbtrm_multicast_address_low 225.7.33.85
context transport_lbtrm_multicast_address_high 225.7.33.89
context transport_lbtrm_source_port_low 24000
context transport_lbtrm_source_port_high 24999

##Transport LBT-RM Operation Options##
context transport_lbtrm_data_rate_limit 100000000
context transport_lbtrm_retransmit_rate_limit 500000
receiver transport_lbtrm_activity_timeout 10000

##Transport LBT-RU Network Options##
receiver transport_lbtru_interface 10.29.2.0/24
source transport_lbtru_interface 10.29.2.0/24

##Transport LBT_RU Operation Options##
context transport_lbtru_data_rate_limit 1000000
context transport_lbtru_retransmit_rate_limit 500000
receiver transport_lbtru_activity_timeout 10000

##Multicast Immediate Messaging Network Options##
context mim_address 225.7.32.100

##Request Network Options##
context request_tcp_interface 10.29.2.0/24

##Transport TCP Network Options##
receiver transport_tcp_interface 10.29.2.0/24
source transport_tcp_interface 10.29.2.0/24
context transport_tcp_port_low 18000
context transport_tcp_port_high 18999
         

## Major Options##
source transport lbtrm

## Multicast Resolver Network Options##
context resolver_multicast_interface 10.29.3.0/24
context resolver_multicast_address 225.8.32.85
context resolver_multicast_port 13965

##Transport LBT-RM Network Options##
context transport_lbtrm_multicast_address_low 225.8.33.85
context transport_lbtrm_multicast_address_high 225.8.33.89
context transport_lbtrm_source_port_low 25000
context transport_lbtrm_source_port_high 25999

##Transport LBT-RM Operation Options##
context transport_lbtrm_data_rate_limit 100000000
context transport_lbtrm_retransmit_rate_limit 500000
receiver transport_lbtrm_activity_timeout 10000

##Transport LBT-RU Network Options##
receiver transport_lbtru_interface 10.29.3.0/24
source transport_lbtru_interface 10.29.3.0/24

##Transport LBT_RU Operation Options##
context transport_lbtru_data_rate_limit 1000000
context transport_lbtru_retransmit_rate_limit 500000
receiver transport_lbtru_activity_timeout 10000

##Multicast Immediate Messaging Network Options##
context mim_address 225.8.32.100

##Request Network Options##
context request_tcp_interface 10.29.3.0/24

##Transport TCP Network Options##
receiver transport_tcp_interface 10.29.3.0/24
source transport_tcp_interface 10.29.3.0/24
context transport_tcp_port_low 17000
context transport_tcp_port_high 17999
         

## Major Options##
source transport lbtrm

## Multicast Resolver Network Options##
context resolver_multicast_interface 10.29.3.0/24
context resolver_multicast_address 225.9.32.85
context resolver_multicast_port 13965

##Transport LBT-RM Network Options##
context transport_lbtrm_multicast_address_low 225.9.33.85
context transport_lbtrm_multicast_address_high 225.9.33.89
context transport_lbtrm_source_port_low 25000
context transport_lbtrm_source_port_high 25999

##Transport LBT-RM Operation Options##
context transport_lbtrm_data_rate_limit 100000000
context transport_lbtrm_retransmit_rate_limit 500000
receiver transport_lbtrm_activity_timeout 10000

##Transport LBT-RU Network Options##
receiver transport_lbtru_interface 10.29.6.0/24
source transport_lbtru_interface 10.29.6.0/24

##Transport LBT_RU Operation Options##
context transport_lbtru_data_rate_limit 1000000
context transport_lbtru_retransmit_rate_limit 500000
receiver transport_lbtru_activity_timeout 10000

##Multicast Immediate Messaging Network Options##
context mim_address 225.9.32.100

##Request Network Options##
context request_tcp_interface 10.29.6.0/24

##Transport TCP Network Options##
receiver transport_tcp_interface 10.29.6.0/24
source transport_tcp_interface 10.29.6.0/24
context transport_tcp_port_low 17000
context transport_tcp_port_high 17999
         

5.2.2. UM Gateway Configuration

The configuration for this gateway, expressed in multiple-lans.xml also has transport statistics monitoring and the WebMonitor turned on. In addition, Late Join has been activated primarily for any receivers in LAN2 or LAN 3 that start up late. The configuration specifies that all proxy sources (pSRC) always provide Late Join service even if the original source does not. It also specifies that the pSRC forward retransmissions from the original source if the pSRC cannot fill the retransmission request itself. See also Using Late Join.

<?xml version="1.0" encoding="UTF-8" ?>
<!-- UM GW xml file- 3 endpoint portals -->
<tnw-gateway version="1.0">
  <daemon>
    <log type="console"/>
    <lbm-license-file>lic0014.txt</lbm-license-file>
    <monitor interval="5">
      <transport-module module="lbm" options="config=lan1.cfg"/>
    </monitor>
    <web-monitor>*:15304</web-monitor>
  </daemon>
  <portals>
    <endpoint>
      <name>LAN1</name>
      <domain-id>1</domain-id>
      <lbm-config>lan1.cfg</lbm-config>
    </endpoint>
    <endpoint>
      <name>LAN2</name>
      <domain-id>2</domain-id>
      <lbm-config>lan2.cfg</lbm-config>
      <late-join provide="always" forward="yes"/>
    </endpoint>
    <endpoint>
      <name>LAN3</name>
      <domain-id>3</domain-id>
      <lbm-config>lan3.cfg</lbm-config>
      <late-join provide="always" forward="yes"/>
    </endpoint>
  </portals>
</tnw-gateway>