Configuration Guide

Transport LBT-RU Network Options

# LBT-RU Transport Session Management <-

The image below illustrates the relationship between the primary LBT-RU network options.

When a source is created, the application can explicitly map it to a transport session by setting the transport_lbtru_port (source) option. If a previous source was created on the same context with the same port, this new source will be mapped to the same transport session. However, two different contexts on the same host may not share the same port number. If a source is created with a port number that is already in use, UM will return an error. This behavior can be changed using transport_lbtru_allow_ephemeral (source). See Flexible LBT-RU Topic Assignment for more information.

Alternatively, if the application does not explicitly specify a source port, UM will implicitly assign the new source to a pool of transport sessions defined when the context was created. The pool is defined as a range of port numbers specified by the options transport_lbtru_port_low (context) and transport_lbtru_port_high (context). In addition, the option transport_lbtru_maximum_ports (context) defines the number of transport sessions in the pool.

When a new source is created and the source port is not explicitly defined, UM will check to see how many transport sessions are currently active from the pool within the context. If it is less than the number in the pool, then UM will activate the next transport session in the range. However, if the context already has activated all transport sessions in the pool, then the new topic is mapped to one of the existing transport sessions, in round-robin fashion.

Notice that the default range of ports, 14380 to 14389, is 10 ports. But the default number of transport sessions in the pool is 5. This allows two contexts to be created on the same host and use the same configuration. If more than 2 contexts are intended to co-exist on the same host, the port range and number of transport session per context must be managed to give a unique port number to every transport session.

The option transport_lbtru_interface (source) may be used on LBT-RU sources to choose particular interface, overriding the default INADDR_ANY which accepts connections on all interfaces. Similarly, transport_lbtru_interface (receiver) may be used on receivers to choose a particular interface for outgoing connections.

Attention
  The interaction between explicitly specified ports and the round-robin pool changed in UM version 6.17.1. See LBT-RU Explicit Port Use.

# Reference <-

## transport_lbtru_allow_ephemeral (source) <-

  When set to 1 and the configured transport_lbtru_port cannot be bound, then use an ephemeral port.

  When transport_lbtru_allow_ephemeral is 1 and transport_lbtru_port (source) has been specified, failure to bind to the transport_lbtru_port does not result in a failure. Instead, UM binds to an ephemeral port and uses that port for any other source that is configured with the same specified transport_lbtru_port. See Flexible LBT-RU Topic Assignment.

  Scope: | source
  Type: | lbm_uint16_t
  Default value: | 0
  Byte order: | Network
  When to Set: | Can only be set during object initialization.
  Version: | This option was implemented in UM 6.17

## transport_lbtru_interface (receiver) <-

  Specifies the network interface over which UM LBT-RU receivers read application data messages.

  Can specify full IP address of interface, or just network part (see Specifying Interfaces for details).

  Default is set to default_interface (context), if specified. Otherwise, it is set to INADDR_ANY, meaning that it will accept incoming connection requests from any interface.

  Note: if specifying an interface name in an XML-format file, see Interface Device Names and XML.

  Scope: | receiver
  Type: | lbm_ipv4_address_mask_t
  Default value: | 0.0.0.0 (INADDR_ANY)
  When to Set: | Can only be set during object initialization.

## transport_lbtru_interface (source) <-

  Specifies the network interface over which UM LBT-RU sources receive connection requests from topic receivers.

  Can specify full IP address of interface, or just network part (see Specifying Interfaces for details).

  Be aware that this option is applied to the transport session when the first topic is created on that session. Thus, setting a different interface for a subsequent topic that maps onto the same transport session will have no effect.

  Default is set to default_interface (context), if specified. Otherwise, it is set to INADDR_ANY, meaning that it will accept incoming connection requests from any interface.

  Note: if specifying an interface name in an XML-format file, see Interface Device Names and XML.

  Scope: | source
  Type: | lbm_ipv4_address_mask_t
  Default value: | 0.0.0.0 (INADDR_ANY)
  When to Set: | Can only be set during object initialization.

## transport_lbtru_maximum_ports (context) <-

  Maximum size of LBT-RU source transport session default pool.

  See LBT-RU Transport Session Management for how LBT-RU source transport sessions are managed.

  Scope: | context
  Type: | lbm_uint16_t
  Units: | number of ports
  Default value: | 5
  When to Set: | Can only be set during object initialization.

## transport_lbtru_port (source) <-

  The UDP port to be used for the source transport session.

  This is the source-side option. For receive-side ports, see transport_lbtru_port_low (receiver).

  Setting this option to non-zero overrides the use of the default pool of LBT-RU source transport sessions.

  See LBT-RU Transport Session Management for how LBT-RU source transport sessions are managed.

  See Port Assignments for more information about configuring ports.

  Note that this port is only used by LBT-RU sources, not receivers.

Attention
  If a source is configured for a port that is not currently part of the transport session default pool, UM will create a new transport session for this port and add it to the default pool. See Transport Session Differences.

  Scope: | source
  Type: | lbm_uint16_t
  Default value: | 0 (use open port)
  Byte order: | Network
  When to Set: | Can only be set during object initialization.

## transport_lbtru_port_high (context) <-

  High UDP port number of range for default pool of LBT-RU source transport sessions.

  When transport_lbtru_port (source) is not specified, a newly-created transport session will use an unused port from this range. Receivers that join the source's transport session send connection requests, acknowledgements, and NAKs to the source port.

  See also transport_lbtru_port_high (context).

  This is the source-side option. For the corresponding receiver option, see transport_lbtru_port_high (receiver).

  See LBT-RU Transport Session Management for how LBT-RU source transport sessions are managed.

  See Port Assignments for more information about configuring ports.

  Scope: | context
  Type: | lbm_uint16_t
  Default value: | 14389
  Byte order: | Host
  When to Set: | Can only be set during object initialization.

## transport_lbtru_port_high (receiver) <-

  High port number to use for receiving LBT-RU data.

  This is the receive-side option. For the corresponding source option, see transport_lbtru_port_high (context).

  When a newly-created receiver joins a source's transport session, it finds a free port from this range, binds to it, and informs the source of the receiver's IP and port. The UM source will send message data to that IP and port.

  Unlike most UM port ranges, if the library is not able to find an unused port in this range, it will log a warning (Core-5688-3300), but instead of failing the receiver creation, it will allocate a port from the host's ephemeral pool and operate normally. Thus, it is possible for a receiver to get messages on a port outside of the configured range.

  See Port Assignments for more information about configuring ports.

  Scope: | receiver
  Type: | lbm_uint16_t
  Default value: | 14379
  Byte order: | Host
  When to Set: | Can only be set during object initialization.

## transport_lbtru_port_low (context) <-

  Low UDP port number of range for default pool of LBT-RU source transport sessions.

  When transport_lbtru_port (source) is not specified, a newly-created transport session will use an unused port from this range. Receivers that join the source's transport session send connection requests, acknowledgements, and NAKs to the source port.

  See also transport_lbtru_port_high (context).

  This is the source-side option. For the corresponding receiver option, see transport_lbtru_port_low (receiver).

  See LBT-RU Transport Session Management for how LBT-RU source transport sessions are managed.

  See Port Assignments for more information about configuring ports.

  Scope: | context
  Type: | lbm_uint16_t
  Default value: | 14380
  Byte order: | Host
  When to Set: | Can only be set during object initialization.

## transport_lbtru_port_low (receiver) <-

  Low port number to use for receiving LBT-RU data.

  This is the receive-side option. For the corresponding source option, see transport_lbtru_port_low (context).

  When a newly-created receiver joins a source's transport session, it finds a free port from this range, binds to it, and informs the source of the receiver's IP and port. The UM source will send message data to that IP and port.

  Unlike most UM port ranges, if the library is not able to find an unused port in this range, it will log a warning (Core-5688-3300), but instead of failing the receiver creation, it will allocate a port from the host's ephemeral pool and operate normally. Thus, it is possible for a receiver to get messages on a port outside of the configured range.

  See Port Assignments for more information about configuring ports.

  Scope: | receiver
  Type: | lbm_uint16_t
  Default value: | 14360
  Byte order: | Host
  When to Set: | Can only be set during object initialization.