Case Sensitivity <-

All Ultra Messaging scope, option, and value strings are case-insensitive. Thus, the following are identical:

context fd_management_type wincompport
Context Fd_Management_Type WinCompPort
CONTEXT FD_MANAGEMENT_TYPE WINCOMPPORT

Specifying Interfaces <-

The *_interface options require a network interface, usually supplied as a string (from a configuration file or in source code via *_attr_str_setopt()), the syntax used for network interface specifications is CIDR notation:

a.b.c.d/num

where '/num' is the optional "prefix length", the number of leading 1 bits in the netmask. If the prefix length is omitted, it defaults to 32 (netmask 255.255.255.255), which means that it must be an exact match for the interface's IP address. However, if the prefix length '/num' is supplied, it tells Ultra Messaging to select the first interface that starts with that network number. This makes it easier to share a configuration file between many (possibly multi-homed) machines on the same network.

For example:

context resolver_unicast_interface 192.168.0.0/24

specifies a netmask of 255.255.255.0 and would match the interface 192.168.0.3 on one host, and 192.168.0.251 on another host. But would not match 192.168.1.3.

The prefix length ("/num") does not need to match the actual network mask used by the host. For example, you have many hosts on different internal IP networks, but if they all start with "10", you can specify the interface as "10.0.0.0/8". UM will scan the list of interfaces and select the first one it finds that starts with 10. This is useful for selecting any network-connected interface, omitting the loopback 127.0.0.1.

You can also set network interfaces by device name. When setting a configuration option's interface by device name, you must use double quotes, as illustrated below.

context resolver_unicast_interface "en0"

Finally, you can also set network interfaces by DNS host name. When setting a configuration option's interface by DNS name, simply replace the dotted IP address with the host name, as illustrated below.

context resolver_unicast_interface myhost.mydomain.com/24

Notice the use of the optional netmask even though the host name will typically resolve to a specific host IP address. In this case, UM will zero out the host bits of myhost's address and find any interface within that network. If the netmask is omitted, an exact match to myhost's address is needed.

Interface Device Names and XML <-

As mentioned above, when a device name is supplied as an interface specification, the device name must be enclosed in double quotes. This presents a problem when the configuration option is specified within an XML file. In XML files, the values for all options must be enclosed in double quotes, but those quotes are only used by the XML parser to delimit the value. The quote characters themselves are not passed to the UM configuration parser. But the UM configuration parser needs the double quotes to indicate that the device name is being used.

The solution is to use the """ escape when specifying device names for interfaces within an XML file. The XML parser will convert those to actual double quote characters as part of the value passed to UM.

For example:

<options type="context">
  <option name="resolver_multicast_interface" default-value="&quot;en0&quot;">
  </option>
</options>

Another example:

<options type="context">
  <option name="monitor_transport_opts"
    default-value="context|resolver_multicast_interface=&quot;en0&quot;;source|transport=lbt-rm">
  </option>
</options>

(The repeated semicolon looks strange; the first one closes the """, and the second one separates the resolver_multicast_interface option from the transport option.)

Socket Buffer Sizes <-

When specifying send or receive socket buffer sizes, keep the following platform-specific information in mind.

Linux: The kernel value net.core.rmem_max dictates the highest value allowed for a receive socket. The kernel value net.core.wmem_max dictates the highest value allowed for a sending socket. Increase these values to increase the amount of buffering allowed.

Windows: Windows should allow socket buffer sizes to be set very high if needed without requiring registry changes.

See our whitepaper Topics in High Performance Messaging for background and guidelines on UDP buffer sizing.

Port Assignments <-

There are a large number of configuration options which are network port numbers. In many cases, ranges of ports are specified so that multiple instances of UM-based programs can be run on the same machine without interference. Each instance will find a free port in the configured range. However, if the range is not large enough, an instance of UM can fail to initialize due to ports not being available.

Port range exhaustion can also happen if other software packages assign to ports in the range configured for UM. Users should be careful to configure all their networking packages to use non-overlapping port numbers.

Ephemeral Ports <-

The operating system allocates a range of ports for ephemeral ports. These ports are allocated dynamically as-needed by networking packages, including UM, for sockets that don't need a well-known, predictable port number. See Wikipedia's article Ephemeral port for ephemeral port ranges used by popular operating systems.

UM port configurations should avoid the host's ephemeral port range. Since these ports are allocated dynamically by the operating system, these allocations can interfere with UM by exhausting UM port ranges.

Network VS Host Order <-

When the UM C API is used to set configuration options programmatically, port numbers can be specified as a string or as a binary value. For example, here is an option being set by binary value:

unsigned short int optval = 4901;  /* host byte order required */
size_t optlen = sizeof(optval);
rc = lbm_context_attr_setopt(attrib, "transport_tcp_port_low", &optval, optlen);

See Setting an Option from a Binary Value.

There are some port options whose binary values must be supplied in network order. For example:

unsigned short int optval = htons(4901);  /* network byte order required */
size_t optlen = sizeof(optval);
rc = lbm_source_attr_setopt(attrib, "transport_tcp_port", &optval, optlen);

It is generally the case where setting a port to a specific value (i.e. not setting up a range) requires network order. Whereas setting the high and low port values of a range are done in host order.

The reference documentation for each port option specifies the byte order required when binary values are being specified. For example, transport_tcp_port (source) has a table row that says:

Byte order:

Network

Reference Entry Format <-

This section describes the format of each option reference entry.

Each entry begins with a brief description of the option. Following the description is a series of items that defines permissible usage and describes the values for the option.

Scope: Defines the scope to which the option applies.

Type: Defines the data type of the option. The type is required for calls to the *_setopt() and *_getopt() API functions.

Units: Defines the units in which the option value is expressed. This item is optional.

Default value: For range-valued options, indicates the base default value for the option.

Byte order: For options whose value is an IP address or port, defines the byte ordering (Host or Network) expected by the API for *_setopt() calls, and returned by the API for *_getopt() calls.

May be set during operation: If an option may be set after the UM object is created, it is so indicated here.

Next, for enumerated-valued options with limited specific choices, a table details the permissible String Value (configuration file), Integer Value (programmatic attribute setting), and a Description of each choice that includes default value designations.

Alternately, for switch-valued options (0 or 1), a table describes the meaning of each of the two possible values. The default value is noted within the description.