Configuration Guide

XML Configuration Files

XML configuration files let you address many different applications and operating requirements, removing the need to programmatically set and reset options for them. A single XML file can contain options for multiple applications. Moreover, for a single application, you can configure multiple named contexts, event queues, etc., with different values for the same options.

See Example Configuration Scenarios for example configuration files.

# XML Configuration Concepts <-

The primary motivation for using XML-based configuration is to be able to configure different instances of the same object in different ways. For example, with a single XML configuration file, you can specify different options for different applications. Or, within a given application, you can specify different options for different context objects. Or within a given context, you can specify different options for different topic-based objects (sources and/or receivers). You can do this without the necessity of writing special application code to do it.

Users often have large sets of configuration options that apply to multiple applications or objects. Rather than having to reproduce the entire set for each application or object, templates can be used to give common sets a name that can be referenced in applications or objects in the XML file.

Applications may also override configuration options specified in an XML configuration file, either by using a plain text configuration file, or by using UM's API.

However, it is also possible for the XML configuration file to impose restrictions on the application's ability to override options. Using <allow> and <deny> elements, and the `order` attribute, XML files can constrain application to using specific values for desired options.

# XML Reference Names <-

Given that XML configuration files are intended to allow different objects to be configured differently, there needs to be a way to identify which object should have which configuration. This is done with application and object names, which the XML file references.

Context and Event Queue names are case-sensitive and can consist of only alpha-numeric ASCII characters, dash (-), and underscore (_). They must be 127 characters or less.

Valid examples:

- abc
- 123-abc
- XYZ_xyz

Invalid examples:

- abc xyz (no spaces allowed)
- 123.abc (no period allowed)
- XYZ,xyz (no comma allowed)

Template and application names are case-sensitive and can consist of any printable ASCII characters. They must be 99 characters or less.

## XML Object Names <-

The simplest apps create UM objects without using attribute objects. For example:

err = lbm_context_create(&ctx, NULL, NULL, NULL);

Passing NULL for the context attribute object causes UM to simply use the defaults (as possibly modified by a configuration file).

However, if there is a chance that you will want to be able to configure the objects differently, you should create an attribute object using the appropriate "*_attr_create_from_xml()" API, giving it a descriptive name. For example:

lbm_context_attr_t *ctx_attr;
...
err = lbm_context_attr_create_from_xml(&ctx_attr, "main_ctx");
err = lbm_context_create(&ctx, ctx_attr, NULL, NULL);

You can do this even if you do not yet make use of an XML file. If no XML file has been read, that lbm_context_attr_create_from_xml() does the same thing as lbm_context_attr_create().

However, if an XML file is supplied and it specifies a configuration for a context named "main_ctx", the "*_attr_create_from_xml()" API will first load the attribute object with the default values and will then apply the proper XML defaults to the attribute object. Desired options can then be overridden using the appropriate "*_attr_setopt()" or "*_attr_str_setopt()" APIs.

The full set of XML-enabled attribute creation APIs are: lbm_context_attr_create_from_xml(), lbm_src_topic_attr_create_from_xml(), lbm_rcv_topic_attr_create_from_xml(), lbm_event_queue_attr_create_from_xml(), lbm_wildcard_rcv_attr_create_from_xml(), lbm_hfx_attr_create_from_xml().

Note
  It is also possible to call lbm_context_attr_create_from_xml() passing NULL as the context name. This matches a XML <context> element that has no `name` attribute. An unnamed "<context>" element only matches unnamed contexts.

## XML Application Names <-

An XML configuration file groups configurations into one or more <application> elements. Normally, each `<application>` is given a unique name, using the "name" attribute. It is also permissible to include an `<application>` element without a name attribute (the "unnamed" application element).

When an application starts and attempts to use an XML configuration file, the application normally gives UM its name, which UM will match to one of the XML file's <application> elements. It is also permissible that the application does not give itself a name, in which case UM will match the unnamed `<application>` element.

Unlike most XML elements, the <applications> element does not have a way to allow applications with names that have no matching application element. For example, let's say the XML file contains:

<?xml version="1.0" ?>
<um-configuration version="1.0">
<applications>
<application name="app1">
...
</application>
<application name="app2">
...
</application>
<application>
...
</application>
</applications>
</um-configuration>

If an application starts up and is named "app3", it will fail to initialize. The above file only allows applications named "app1", "app2", and applications that do not set a name. Note that if the unnamed application element is removed from that XML file, then an unnamed application will fail to initialize.

There are several ways to give an application the name that can be referenced by an XML configuration file:

- RECOMMENDED: Read the XML configuration file using the lbm_config_xml_file() API.
- Set the environment variable LBM_XML_CONFIG_APPNAME. (But be aware that it is ignored if the lbm_config() API is used to read the XML configuration file.)
- Deprecated: invoke the UMM feature using the lbm_set_umm_info() API or using the `LBM_UMM_INFO` environment variable. Note that UMM is deprecated as of UM version 6.17 and will be removed in a future release. See UM Manager Overview for more information on UMM.

Note that the application name is not related to the executable file name of the program, or the operating system process name. The application name is assigned via one of the above methods only.

Unfortunately, the UM example applications were not written to any of the above three methods. They all use lbm_config(), which means they ignore the LBM_XML_CONFIG_APPNAME environment variable. The solution for UM example applications is to not use the "-c" flag, but instead to supply both environment variables:

- LBM_XML_CONFIG_APPNAME
- LBM_XML_CONFIG_FILENAME

In this way, UM will correctly set the example application's name and will properly load the XML configuration file.

# xml:space Attribute <-

Many XML elements throughout UM's configuration files include an attribute named "xml:space". This attribute instructs the XML parser how to deal with whitespace (spaces, tabs, newlines) in the element's value. The attribute defaults to the value "default", which tells the XML parser to trim leading and trailing whitespace, and to compress multiple whitespace into a single space.

For example:

<log>
my_logfile.log
</log>

Note that the value for the "<log>" element contains a leading newline, followed by two spaces, followed by the file name, followed by another newline. Those whitespace characters should be trimmed, which is the default behavior. It is equivalent to:

<log xml:space="default">
my_logfile.log
</log>

However, let's say you really want a space as the first character of the file name. While unusual, it can be done as follows:

<log xml:space="preserve"> my_logfile.log</log>

Note that it had to be combined into a single line to get rid of the newlines.

# Order and Rule Specifications <-

An XML configuration file can constrain how an application may override the values supplied in the XML configuration file. It can also restrict which topics the application may publish and subscribe to. These two use cases are handled slightly differently.

## Constraining Configuration Values <-

The way to think of the `order` attribute in the <option> element is as follows:

- For order `"allow,deny"` the XML should contain zero or more values that are allowed. If a user-supplied value doesn't match any of them, it is denied.
- For order `"deny,allow"` the XML should contain zero or more values that are denied. If a user-supplied value doesn't match any of them, it is allowed.

Consider the following fragment of XML:

<receivers>
<topic>
<options type="receiver">
<option name="ordered_delivery" order="deny,allow">
<deny>0</deny>
</option>
</options>
</topic>
</receivers>

This prevents the user from setting ordered_delivery (receiver) to 0, but allows values 1 and -1. But the values 1 and -1 are not explicitly allowed. The `order` attribute is set to `"deny,allow"`, has "allow" as the default behavior if the user-supplied value doesn't match one of "<allow>" or "<deny>" values.

Contrast with this fragment:

<receivers>
<topic>
<options type="receiver">
<option name="ordered_delivery" order="allow,deny">
<allow>1</allow>
</option>
</options>
</topic>
</receivers>

This allows the value 1 but denies all others. The `order` attribute is set to `"allow,deny"`, has "deny" as the default behavior if the user-supplied value doesn't match one of "<allow>" or "<deny>" values.

## Restricting Topics <-

Consider the following fragment of XML:

<receivers order="allow,deny">
<topic topicname="general_info" rule="allow"/>
<topic topicname="alerts" rule="allow"/>
</receivers>

This allows the application to create receivers for topics "general_info" and "alerts" and disallows all others. The `order` attribute is set to `"allow,deny"`, has "deny" as the default behavior if the user-supplied topic doesn't match one of "<allow>" or "<deny>" values.

Contrast with this fragment:

<receivers order="deny,allow">
<topic topicname="authorize" rule="deny"/>
</receivers>

This allows the application to subscribe to any topic except "authorize". The `order` attribute is set to `"deny,allow"`, has "allow" as the default behavior if the user-supplied value doesn't match one of "<allow>" or "<deny>" values.

Warning
  With the above `<topic>` elements, an application can bypass the intended restrictions by using a wildcard receiver, perhaps with the pattern ".*". This allows the application to effectively subscribe to all topics. The `<topic>` elements do not restrict wildcard receivers.

Since wildcard patterns can be complex, users who wish to restrict applications should either disallow wildcard receivers, or carefully constrain them. For example:

<receivers order="deny,allow">
<topic topicname="authorize" rule="deny"/>
</receivers>
<wildcard-receivers order="allow,deny">
<wildcard-receiver pattern="^abc.*$" rule="allow"/>
<wildcard-receiver pattern="^xyz.*$" rule="allow"/>
</wildcard-receivers>

This allows the application to create any single-topic receiver except for the topic "authorize", and it allows two patterns for wildcard receivers (neither of which will match the topic "authorize").

Another, more-restrictive example:

<receivers order="allow,deny">
<topic topicname="general_info" rule="allow"/>
<topic topicname="alerts" rule="allow"/>
</receivers>
<wildcard-receivers order="allow,deny"/>

This only allows the application to subscribe to the two topics "general_info" and "alerts", and it completely disallows any wildcard receivers.

## Overlapping Topics <-

There are some use cases where a special property of the `order` attribute is useful: the order in which `allow` and `deny` rules are applied. When multiple <topic> elements match a given topic name due to overlapping wildcard patterns, the order of applying the rules can be important to obtain the desired behavior.

Consider this example:

<receivers order="deny,allow">
<topic pattern="^trade" rule="deny"/>
<topic pattern="^trade\.NASD" rule="allow"/>
</receivers>

Let's assume that the application subscribes to "trade.NASD.xyz". This matches both patterns. By ordering the patterns as deny first, followed by allow, the last match is allow, which allows the topic to be created. The last rule to match determines the permission.

Whereas subscribing to "trade.abc.xyz" will only match the deny, and will be prevented.

Also note that subscribing to "quote", which does not match either topic, follows the default rule, which is allow.

So the above XML allows all non-trade subscriptions, but only allows NASD trade subscriptions.

Contrast with this example:

<receivers order="allow,deny">
<topic pattern="^trade" rule="allow"/>
<topic pattern="^trade\.NASD" rule="deny"/>
</receivers>

Let's again assume that the application subscribes to "trade.NASD.xyz". This also matches both patterns, but in this case the allows are first and the denies are last. Thus, "trade.NASD.xyz" is prevented.

So while the previous example only allowed NASD trades, this example allows any trades except NASD.

Also note that subscribing to "quote", which does not match either topic, follows the default rule, which is deny.

# UM Default Values <-

The following examples will help to illustrate how UM defaults work. In the code fragments shown, the UM API calls shown are assumed to be the first UM API calls made since the process started.

No Attribute Object, No Config File

test.c:

err = lbm_context_create(&ctx, NULL, NULL, NULL);
/* The context has request_tcp_port_low = 14393 (factory default) */

1. When UM initializes, the "factory defaults" are copied to the process-global internal attribute objects.
2. In the call to lbm_context_create(), setting the `"attr"` parameter to NULL causes UM to use the process-global internal context attribute object to create the context.

No Attribute Object, Plain Text Configuration File

test.cfg:

    context request_tcp_port_low 12000

test.c:

err = lbm_config("test.cfg");
err = lbm_context_create(&ctx, NULL, NULL, NULL);
/* The context has request_tcp_port_low = 12000 */

1. When UM initializes, the "factory defaults" are copied to the process-global internal attribute objects.
2. The call to lbm_config() reads the options in the file "test.cfg" and applies them to the process-global internal attribute objects. This overrides the factory default for request_tcp_port_low (context).
3. In the call to lbm_context_create(), setting the `"attr"` parameter to NULL causes UM to use the process-global internal context attribute object to create the context.

Attribute Object, Plain Text Configuration File

test.cfg:

    context request_tcp_port_low 12000

test.c:

err = lbm_config("test.cfg");
err = lbm_context_attr_create(&ctx_attr);
err = lbm_context_create(&ctx, ctx_attr, NULL, NULL);
/* The context has request_tcp_port_low = 12000 */

1. When UM initializes, the "factory defaults" are copied to the process-global internal attribute objects.
2. The call to lbm_config() reads the options in the file "test.cfg" and applies them to the process-global internal attribute objects. This overrides the factory default for request_tcp_port_low (context).
3. The lbm_context_attr_create() API copies the process-global internal context attribute object, with the overridden request_tcp_port_low (context).
4. The call to lbm_context_create() passes the attribute object with the overridden request_tcp_port_low (context).

Note
  The use of lbm_context_attr_create() is not recommended. See next example.

Attribute Object, Plain Text and XML Configuration Files

In this example, the user intends the default for request_tcp_port_low (context) to be overridden to 13000, but there's a problem.

test.xml:

<?xml version="1.0" ?>
<um-configuration version="1.0">
<applications>
<application>
<contexts>
<context>
<options type="context">
<option name="request_tcp_port_low" default-value="13000">
</option>
</options>
</context>
</contexts>
</application>
</applications>
</um-configuration>

test.cfg:

      context request_tcp_port_low 12000

test.c:

err = lbm_config_xml_file("test.xml", NULL);
err = lbm_config("test.cfg");
err = lbm_context_attr_create(&ctx_attr);
err = lbm_context_create(&ctx, ctx_attr, NULL, NULL);
/* The context has request_tcp_port_low = 12000!! */

1. When UM initializes, the "factory defaults" are copied to the process-global internal attribute objects.
2. The call to lbm_config_xml_file() reads the elements in the file "test.xml" and stores them internally. Note that lbm_config_xml_file() does not modify the process-global internal attribute objects.
3. The call to lbm_config() reads the options in the file "test.cfg" and applies them to the process-global internal attribute objects. This overrides the factory default for request_tcp_port_low (context) with 12000.
4. The lbm_context_attr_create() API copies the process-global internal context attribute object, with the overridden request_tcp_port_low (context). Note that the XML default is not applied when the attribute object is created using lbm_context_attr_create().
5. The call to lbm_context_create() passes the attribute object with the overridden request_tcp_port_low (context) of 12000.

In this example, the use of lbm_context_attr_create() resulted in the XML file's default being ignored. However, see the next example.

Attribute Object, Plain Text and XML Configuration Files, Plus Restriction

In this example, the application is constrained to only allow 12000.

test.xml:

<?xml version="1.0" ?>
<um-configuration version="1.0">
<applications>
<application>
<contexts>
<context>
<options type="context">
<option name="request_tcp_port_low" default-value="13000"
order="allow,deny">
<allow>13000</allow>
</option>
</options>
</context>
</contexts>
</application>
</applications>
</um-configuration>

test.cfg:

context request_tcp_port_low 12000

test.c:

err = lbm_config_xml_file("test.xml", NULL);
err = lbm_config("test.cfg");
err = lbm_context_attr_create(&ctx_attr);
err = lbm_context_create(&ctx, ctx_attr, NULL, NULL);
/* ERROR RETURNED! */

As with the previous example, the default value supplied in the XML configuration file is ignored due to the use of lbm_context_attr_create(). However, the XML file's restrictions applied by `order="allow,deny"` and `<allow>13000</allow>` are applied at object creation time. Since only 13000 is allowed, but 12000 was attempted, the lbm_context_create() API fails.

Attribute Object From XML, Plain Text and XML Configuration Files, Plus Restriction

test.xml:

<?xml version="1.0" ?>
<um-configuration version="1.0">
<applications>
<application>
<contexts>
<context>
<options type="context">
<option name="request_tcp_port_low" default-value="13000"
order="allow,deny">
<allow>13000</allow>
</option>
</options>
</context>
</contexts>
</application>
</applications>
</um-configuration>

test.cfg:

      context request_tcp_port_low 12000

test.c:

err = lbm_config_xml_file("test.xml", NULL);
err = lbm_config("test.cfg");
err = lbm_context_attr_create_from_xml(&ctx_attr, NULL);
err = lbm_context_create(&ctx, ctx_attr, NULL, NULL);
/* The context has request_tcp_port_low = 13000 */

In this example, the attribute object is created using the lbm_context_attr_create_from_xml() API. It is created without a name, and therefore matches the "<context>" option that has no `name` attribute. This allows the `default-value` attribute to override the default present in the internal process-global context attribute object. So the call to lbm_context_create() succeeds.

Note that if the plain text configuration file "test.cfg" had other UM options set, those overridden defaults would have appeared in the attribute object created by lbm_context_attr_create_from_xml().

Named Attribute Object, XML Configuration File

In this example, the context is named.

test.xml:

<?xml version="1.0" ?>
<um-configuration version="1.0">
<applications>
<application name="App1">
<contexts>
<context name="MainCtx">
<options type="context">
<option name="request_tcp_port_low" default-value="13000"
order="allow,deny">
<allow>13000</allow>
</option>
</options>
</context>
</contexts>
</application>
</applications>
</um-configuration>

test.c:

err = lbm_config_xml_file("test.xml", "App1");
err = lbm_context_attr_create_from_xml(&ctx_attr, "MainCtx");
err = lbm_context_create(&ctx, ctx_attr, NULL, NULL);

In this example, the application and context names are specified and matched in the XML file. This is the recommended way of using UM. In fact, even if no XML file is used at all, the `*_attr_create_from_xml()` APIs are recommended to be used, and descriptive names supplied. This "future-proofs" your code so that flexible XML configurations can be added later on without needing to change your source code.

# Reading XML Configuration Files <-

There are multiple ways to read an XML configuration file to assign values while creating a primitive object.

API function lbm_config_xml_file()
  Reads an XML configuration file into XML config table. Call this before the primitive create API. This does not change the current default attributes. Use a file path, or a URL beginning with http:// or ftp://.

API function lbm_config_xml_string()
  Populates the XML config table directly from your application. Call this before the primitive create API. This does not change the current default attributes.

API function lbm_*_attr_create_from_XML()
  Creates a custom attributes object containing the values from an XML configuration file. The values can then be applied to a primitive object being created by calling API "lbm_*_create()" and specifying this custom attributes object in the second parameter.

Environment variable LBM_XML_CONFIG_FILENAME
  Reads the file into the XML config table. These settings are then available to all applications when they start. Use a file path, or a URL beginning with http:// or ftp://.

Environment variable LBM_XML_CONFIG_APPNAME
  Reads options for a specific application from the LBM_XML_CONFIG_FILENAME variable's filename. This initiates the specified application's configuration; set this environment variable for every application. Note that this variable is ignored if the XML configuration file is read using the lbm_config() API.

API function lbm_set_umm_info()
  Initiates the application to read options for an application and user from the UMM daemon (deprecated). The Java API and .NET API is com::latencybusters::lbm::LBM::setUmmInfo().

Environment variable LBM_UMM_INFO
  Initiates the application to read options for an application and user from the UMM daemon (deprecated). Set this variable for every application/user combination, in the following format:

    export LBM_UMM_INFO=application_name:user_name:password@ip:port

# Using XML Configuration Files With a UM Application <-

The following procedure describes a general approach to implementing XML configuration files.

1. Create an XML configuration file using an XML editor or text editor. Just for this example, name the file, UM_CONFIG.XML.

2. Insert desired templates in the <templates> element. Each template holds configuration options shared by multiple applications or primitive UM objects. You can apply multiple templates to an application and its primitive UM objects, however if the same option appears in multiple templates, the option value in the last template overrides the option value in any previous templates. See <templates>.

3. Insert an <application> element for your UM application in the <applications> element and reference any relevant templates created in the previous step. Just for this example, name the application, SENDAPP. See <applications>.

4. Within the <contexts> element, configure the application's <context> element and context options. And since our example application, SENDAPP is a sending application, also configure its Source options. (If this was a receiving application, you would configure Receiver or Wildcard Receiver options. Note that most real-world applications both send and receive messages, and would therefore have both.) If your application creates multiple Contexts, enter multiple <context> elements within the <contexts> element, inserting the appropriate source, receiver or wildcard receiver options. See <contexts>.

5. Configure the applications Event Queue options. See <event-queues>.

6. Save the XML configuration file, UM_CONFIG.XML, and load it onto the machine where the application (SENDAPP) runs.

7. Have the application (SENDAPP) read the XML file. The preferred way to do this is the lbm_config_xml_file() API. However, if it is not possible to modify the application's code, set the following environment variables:

   - Set LBM_XML_CONFIG_FILENAME to UM_CONFIG.XML.
   - Set LBM_XML_CONFIG_APPNAME to SENDAPP.

8. Start SENDAPP.

# XML Configuration File Format <-

A UM XML Configuration File follows standard XML conventions. The first line should be:

<?xml version="1.0" encoding="UTF-8" ?>

followed by UM elements.

An XML configuration file generally comprises two primary elements: templates and applications. Organized and contained within these are option value assignments. Applications containers let you set options for specific applications. To provide more global control over applications, or to simply reduce repetition, you can create templates to hold option settings that are to be used in one or more different applications.

XML configuration files use the high-level structure shown in the following example. This example includes only some container elements, and no options.

<?xml version="1.0" encoding="UTF-8" ?>
<um-configuration version="1.0">
<templates>
<template name="Sending">
<options type="source">
</options>
<options type="context">
</options>
</template>
</templates>
<applications>
<application name="Sending-Topic1">
<contexts>
<context name="Sending-LBTRM">
<sources>
<topic topicname="Topic1">
<options type="source">
</options>
</topic>
</sources>
</context>
</contexts>
<event-queues>
<event-queue/>
<event-queue name="EQ-1"/>
</event-queues>
</application>
</applications>
</um-configuration>

# Share/Merge XML Files with XInclude <-

The XInclude mechanism can be used to merge or share XML files for UM library configuration, Store configuration, and DRO configuration. This is typically done to avoid duplicating groups of configuration options in multiple places.

To include an external file from a UM library configuration file, use the following syntax:

<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="FILEPATH" />

Where FILEPATH can be a local file name, or a network path starting with "http:" or "ftp:". For example:

<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="/um/conf/TRD1.xml" />
<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="http://myweb.mydomain.com/umconf/TRD1.xml" />
<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="ftp://myftp.mydomain.com/umconf/TRD1.xml" />

Note that secure forms of network paths ("https:" or "sftp:") are not supported.

Files to be included must be formatted such that all elements are enclosed in a single container element.

Example of an invalid file:

<option name="transport_lbtrm_multicast_address" default-value="239.101.3.101"/>
<option name="transport_lbtrm_destination_port" default-value="14488"/>

Example of valid file:

<options type="source">
<option name="transport_lbtrm_multicast_address" default-value="239.101.3.101"/>
<option name="transport_lbtrm_destination_port" default-value="14488"/>
</options>

## Common XInclude Use Case <-

UM library configuration files do not support the use of the UM Element "<topic>" inside of a template. Let's say you want to define the source LBT-RM multicast address/port combinations on a per-topic basis. This must be done in the UM Element "<application>", and must be repeated for each application.

For example consider the UM library configuration file "um_conf.xml":

...
<application name="fix01" template="common">
<contexts>
<context>
<sources>
<topic topicname="matching/A">
<options type="source">
<option name="transport_lbtrm_multicast_address" default-value="239.101.3.101"/>
<option name="transport_lbtrm_destination_port" default-value="14488"/>
</options>
</topic>
<topic topicname="matching/B">
<options type="source">
<option name="transport_lbtrm_multicast_address" default-value="239.101.3.102"/>
<option name="transport_lbtrm_destination_port" default-value="14488"/>
</options>
</topic>
... (same pattern for matching/C - matching/Y)
<topic topicname="matching/Z">
<options type="source">
<option name="transport_lbtrm_multicast_address" default-value="239.101.3.126"/>
<option name="transport_lbtrm_destination_port" default-value="14488"/>
</options>
</topic>
</sources>
</context>
</contexts>
</application>
<application name="fix02" template="common">
<contexts>
<context>
<sources>
<topic topicname="matching/A">
<options type="source">
<option name="transport_lbtrm_multicast_address" default-value="239.101.3.101"/>
<option name="transport_lbtrm_destination_port" default-value="14488"/>
</options>
</topic>
<topic topicname="matching/B">
<options type="source">
<option name="transport_lbtrm_multicast_address" default-value="239.101.3.102"/>
<option name="transport_lbtrm_destination_port" default-value="14488"/>
</options>
</topic>
... (same pattern for matching/C - matching/Y)
<topic topicname="matching/Z">
<options type="source">
<option name="transport_lbtrm_multicast_address" default-value="239.101.3.126"/>
<option name="transport_lbtrm_destination_port" default-value="14488"/>
</options>
</topic>
</sources>
</context>
</contexts>
</application>
...

This is a lot of repeated content for the 26 source options under each application.

The XInclude feature can be used to reduce duplicate content by creating a second file "um_sources.xml":

<sources>
<topic topicname="matching/A">
<options type="source">
<option name="transport_lbtrm_multicast_address" default-value="239.101.3.101"/>
<option name="transport_lbtrm_destination_port" default-value="14488"/>
</options>
</topic>
<topic topicname="matching/B">
<options type="source">
<option name="transport_lbtrm_multicast_address" default-value="239.101.3.102"/>
<option name="transport_lbtrm_destination_port" default-value="14488"/>
</options>
</topic>
... (same pattern for matching/C - matching/Y)
<topic topicname="matching/Z">
<options type="source">
<option name="transport_lbtrm_multicast_address" default-value="239.101.3.126"/>
<option name="transport_lbtrm_destination_port" default-value="14488"/>
</options>
</topic>
</sources>

Now "um_conf.xml" can be coded as:

...
<application name="fix01" template="common">
<contexts>
<context>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="./um_sources.xml" />
</context>
</contexts>
</application>
<application name="fix02" template="common">
<contexts>
<context>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="./um_sources.xml" />
</context>
</contexts>
</application>
<application name="fix03" template="common">
...

# XML Configuration File Elements <-

Here's a "cheat sheet" showing all of the XML elements.

<um-configuration>
<license format="...">...</license>
<templates>
<template name="...">
<options type="...">
<option name="..." default-value="..." order="...">
<allow>...</allow>
<deny>...</deny>
</option>
</options>
</template>
</templates>
<applications>
<application name="..." template="...">
<contexts order="..." template="...">
<context name="..." template="..." rule="...">
<options ...>...</options> (see templates for expansion)
<sources template="..." order="...">
<topic template="..." rule="..." topicname="..." pattern="...">
<options ...>...</options> (see templates for expansion)
</topic>
</sources>
<receivers order="..." template="...">
<topic template="..." rule="..." topicname="..." pattern="...">
<options ...>...</options> (see templates for expansion)
</topic>
</receivers>
<wildcard-receivers template="..." order="...">
<wildcard-receiver template="..." rule="..." pattern="..." pattern-type="...">
<options ...>...</options> (see templates for expansion)
</wildcard-receiver>
</wildcard-receivers>
</context> </contexts>
<hfxs template="..." order="...">
<topic template="..." rule="..." topicname="..." pattern="...">
<options ...>...</options> (see templates for expansion)
</topic>
</hfxs>
<event-queues template="..." order="...">
<event-queue name="..." template="..." rule="...">
<options ...>...</options> (see templates for expansion)
</event-queue>
</event-queues>
</application>
</applications>
</um-configuration>

## UM Element "<um-configuration>" <-

Container element that holds the UM configuration. Also defines the version of the configuration format used by the file.

- Children: <license>, <templates>, <applications>

XML Attributes:

Attribute | Description | Valid Values | Default Value
--- | --- | --- | ---
version | Version number of user's configuration file. | string | 1.0

Example:

<?xml version="1.0" encoding="UTF-8" ?>
<um-configuration version="1.0">
...
</um-configuration>

## UM Element "<applications>" <-

Container element that holds the configurations for different applications.

- Parent: <um-configuration>
- Children: <application>

Example:

<?xml version="1.0" encoding="UTF-8" ?>
<um-configuration version="1.0">
<applications>
...
</applications>
...
</um-configuration>

## UM Element "<application>" <-

Container element that holds the configuration for a specific application.

Note
  Applications that set a name which is not included by any `<application>` element will fail. There is no "default" `<application>` element that allows and configures applications with non-matching names.

- Cardinality (number of times element can be supplied): 0 .. unbounded
- Parent: <applications>
- Children: <contexts>, <event-queues>, <hfxs>, <application-data>

XML Attributes:

Attribute | Description | Valid Values | Default Value
--- | --- | --- | ---
name | A case-sensitive label which UM matches to an application's assigned name. An application is typically assigned a name via API, e.g. lbm_config_xml_file(), or by environment variable, LBM_XML_CONFIG_APPNAME. See XML Reference Names for more information. Names are case-sensitive and can consist of any printable ASCII characters. They must be 99 characters or less. | string | (If omitted, matches applications that don't set a name.)
template | A case-sensitive label which UM matches to a template's assigned name. Can be a comma-separated list of template names, which are applied in order. | string | (If omitted, no template is applied.)

Example:

<?xml version="1.0" encoding="UTF-8" ?>
<um-configuration version="1.0">
<templates>
<template name="FIX_Config.Prod">
...
</template>
...
</templates>
<applications>
<application name="FIX.01" template="FIX_Config.Prod">
...
</application>
...
</applications>
...
</um-configuration>

## UM Element "<application-data>" <-

Free-form text comment field. Deprecated; do not use.

- Parent: <options>, <application>
- Default Value: Deprecated; do not use.

XML Attributes:

Attribute | Description | Valid Values | Default Value
--- | --- | --- | ---
xml:space | Specifies how whitespace (tabs, spaces, linefeeds) are handled in the element content. See xml:space Attribute. | `"default"` - Trim whitespace. `"preserve"` - Retain whitespace exactly as entered. | default

Deprecated; do not use.

## UM Element "<hfxs>" <-

Container element that holds the configuration for HFX objects. The contained <topic> elements are matched by topic to the HFX objects created by the application. The `order="..."` attribute is used to constrain the application's access to topics. See Order and Rule Specifications for details.

See UM Hot Failover Across Contexts Objects (HFX) for more information on HFX.

- Parent: <application>
- Children: <topic>

XML Attributes:

Attribute | Description | Valid Values | Default Value
--- | --- | --- | ---
template | A case-sensitive label which UM matches to a template's assigned name. Can be a comma-separated list of template names, which are applied in order. | string | (If omitted, no template is applied.)
order | Valid values are "deny,allow" and "allow,deny". Used to control how HFX usage is restricted. See Order and Rule Specifications and Overlapping Topics. | string | "deny,allow"

Example:

<?xml version="1.0" encoding="UTF-8" ?>
<um-configuration version="1.0">
<templates>
<template name="FIX_Config.Prod">
...
</template>
...
</templates>
<applications>
<application name="FIX.01" template="FIX_Config.Prod">
<hfxs template="FIX_Config.Prod" order="deny,allow">
...
</hfxs>
...
</application>
...
</applications>
...
</um-configuration>

## UM Element "<topic>" <-

Used to match UM objects (sources, receivers, HFX receivers) by their topic names, and control their use and configuration. The attributes `topicname` and `pattern` are mutually exclusive; you may not supply both.

Warning
  If the `rule` attribute is being used to restrict the application's receivers, remember that wildcard receivers must also be restricted. For example, if the application must be prevented from subscribing to the "authorize" topic, it is not enough to use:
  <topic topicname="authorize" rule="deny"/>
  Wildcards must also be limited or forbidden. For example, to forbid all wildcard receivers:
  <wildcard-receivers order="allow,deny"/>

- Cardinality (number of times element can be supplied): 0 .. unbounded
- Parent: <hfxs>, <sources>, <receivers>
- Children: <options>

XML Attributes:

Attribute | Description | Valid Values | Default Value
--- | --- | --- | ---
template | A case-sensitive label which UM matches to a template's assigned name. Can be a comma-separated list of template names, which are applied in order. | string | (If omitted, no template is applied.)
rule | Used to restrict the usage of topics. See Order and Rule Specifications. Note that a particular object might match more than one `<topic>` element due to overlapping pattern matching. See Overlapping Topics. | `"allow"` - Permit the matching topic. `"deny"` - Prevent the matching topic. | `allow`
pattern | Regular expression to match against the topic name of the application object being created. | string | (no default; either `topicname` or `pattern` must be specified)
topicname | Name of topic to match against the application object being created. Requires exact match. | string | (no default; either `topicname` or `pattern` must be specified)

Example:

<?xml version="1.0" encoding="UTF-8" ?>
<um-configuration version="1.0">
<templates>
<template name="FIX_Config.Prod">
...
</template>
...
</templates>
<applications>
<application name="FIX.01" template="FIX_Config.Prod">
<hfxs order="deny,allow">
<topic template="FIX_Config.Prod" topicname="Orders" rule="deny"\>
...
</hfxs>
...
</application>
...
</applications>
...
</hfxs>
...
</um-configuration>

## UM Element "<options>" <-

Container element that holds a set of UM options of a specific scope (context, source, etc.).

- Cardinality (number of times element can be supplied): 0 .. unbounded
- Parent: <template>, <event-queue>, <context>, <topic>, <wildcard-receiver>
- Children: <option>, <application-data>

XML Attributes:

Attribute | Description | Valid Values | Default Value
--- | --- | --- | ---
type | UM configuration scope of the `<option>` elements contained within this `<options>` element. | `"event-queue"` - Event queue scope options. `"context"` - Context scope options. `"source"` - Source scope options. `"receiver"` - Receiver scope options. `"wildcard-receiver"` - Wildcard receiver scope options. `"hfx"` - HFX scope options. | (no default; must be specified)

Example:

The `<options>` element can be contained within many other elements. This example only shows it used within the <template> element, but its syntax and usage is the same when used elsewhere.

<?xml version="1.0" encoding="UTF-8" ?>
<um-configuration version="1.0">
<templates>
<template name="FIX_Config.Prod">
<options type="context">
...
</options>
...
</template>
...
</templates>
...
</um-configuration>

## UM Element "<option>" <-

Configure a specific configuration option. The contained `<allow>` and `<deny>` elements are used to allow the XML file to constrain how the application may override the option's value. See Order and Rule Specifications for details.

- Parent: <options>
- Children: <allow>, <deny>

XML Attributes:

Attribute | Description | Valid Values | Default Value
--- | --- | --- | ---
name | Option name. | string | (no default; must be specified)
default-value | Value to set the option. | string | (if omitted, the option's default value is not changed.)
order | Valid values are "deny,allow" and "allow,deny". Used to control how option values are restricted. See Order and Rule Specifications. | string | "deny,allow"

Example:

The `<options>` element can be contained within many other elements. This example only shows it used within the <template> element, but its syntax and usage is the same when used elsewhere.

<?xml version="1.0" encoding="UTF-8" ?>
<um-configuration version="1.0">
<templates>
<template name="FIX_Config.Prod">
<options type="context">
<option name="default_interface" default-value="10.1.2.3" order="deny,allow">
...
</option>
...
</options>
...
</template>
...
</templates>
...
</um-configuration>

## UM Element "<deny>" <-

Contains an option value that the application is explicitly prevented from using. See Order and Rule Specifications.

- Parent: <option>

XML Attributes:

Attribute | Description | Valid Values | Default Value
--- | --- | --- | ---
xml:space | Specifies how whitespace (tabs, spaces, linefeeds) are handled in the element content. See xml:space Attribute. | `"default"` - Trim whitespace. `"preserve"` - Retain whitespace exactly as entered. | default

Example:

The `<options>` element can be contained within many other elements. This example only shows it used within the <template> element, but its syntax and usage is the same when used elsewhere.

In this example, the application may configure any interface except loopback (127.0.0.1).

<?xml version="1.0" encoding="UTF-8" ?>
<um-configuration version="1.0">
<templates>
<template name="FIX_Config.Prod">
<options type="context">
<option name="default_interface">
<deny>127.0.0.1</deny>
...
</option>
...
</options>
...
</template>
...
</templates>
...
</um-configuration>

## UM Element "<allow>" <-

Contains an option value that the application is explicitly allowed to use. See Order and Rule Specifications.

- Parent: <option>

XML Attributes:

Attribute | Description | Valid Values | Default Value
--- | --- | --- | ---
xml:space | Specifies how whitespace (tabs, spaces, linefeeds) are handled in the element content. See xml:space Attribute. | `"default"` - Trim whitespace. `"preserve"` - Retain whitespace exactly as entered. | default

Example:

The `<options>` element can be contained within many other elements. This example only shows it used within the <template> element, but its syntax and usage is the same when used elsewhere.

This example also demonstrates a specific case where the `<option>` element has `order="allow,deny"` which sets the default behavior for overriding the option to `deny`. This effectively constrains the application's ability to override the default value to only those values explicitly allowed. Importantly, the value specified in `default-value="..."` must be explicitly allowed, as shown in this example.

<?xml version="1.0" encoding="UTF-8" ?>
<um-configuration version="1.0">
<templates>
<template name="FIX_Config.Prod">
<options type="context">
<option name="default_interface" default-value="10.1.2.3" order="allow,deny">
<allow>10.1.2.3</allow>
...
</option>
...
</options>
...
</template>
...
</templates>
...
</um-configuration>

## UM Element "<event-queues>" <-

Container element that holds the configuration for event queues. The <event-queue> elements contained within `<event-queues>` are matched to the event queue objects created by the application. The `order="..."` attribute is used to constrain the application's use of event queues. See Order and Rule Specifications for details.

- Parent: <application>
- Children: <event-queue>

XML Attributes:

Attribute | Description | Valid Values | Default Value
--- | --- | --- | ---
template | A case-sensitive label which UM matches to a template's assigned name. | string | (If omitted, no template is applied.)
order | Valid values are "deny,allow" and "allow,deny". Used to control how event queue usage is restricted. See Order and Rule Specifications. | string | `"deny,allow"`

Example:

<?xml version="1.0" encoding="UTF-8" ?>
<um-configuration version="1.0">
<templates>
<template name="EVQ_FIX_Config.Prod">
...
</template>
...
</templates>
<applications>
<application name="FIX.01">
<event-queues template="EVQ_FIX_Config.Prod" order="deny,allow">
...
</event-queues>
...
</application>
...
</applications>
...
</um-configuration>

## UM Element "<event-queue>" <-

Container of configuration for a single event queue.

- Cardinality (number of times element can be supplied): 0 .. unbounded
- Parent: <event-queues>
- Children: <options>

XML Attributes:

Attribute | Description | Valid Values | Default Value
--- | --- | --- | ---
name | Name of the event queue. Supplied as a parameter to lbm_event_queue_attr_create_from_xml() and lbm_event_queue_attr_set_from_xml(). Names are case-sensitive and can consist of only alpha-numeric ASCII characters, dash (-), and underscore (_). They must be 127 characters or less. | string | (If omitted, matches applications that don't set an event queue name.)
template | A case-sensitive label which UM matches to a template's assigned name. | string | (If omitted, matches applications that don't set a name.)
rule | Used to restrict the usage of event queues. See Order and Rule Specifications. | `"allow"` - Permit the matching object. `"deny"` - Prevent the matching object. | `allow`

Example:

<?xml version="1.0" encoding="UTF-8" ?>
<um-configuration version="1.0">
<templates>
<template name="EVQ_FIX_Config.Prod">
...
</template>
...
</templates>
<applications>
<application name="FIX.01">
<event-queues template="EVQ_FIX_Config.Prod" order="deny,allow">
<event-queue name="EVQ_FIX" rule="allow">
...
</event-queue>
...
</event-queues>
...
</application>
...
</applications>
...
</um-configuration>

## UM Element "<contexts>" <-

Container element that holds the configurations for context objects. The <context> elements contained within `<contexts>` are matched to the context objects created by the application. For contexts that do not match any of the contained <context> elements, the default permission is determined by the `order="..."` attribute.

- Parent: <application>
- Children: <context>

XML Attributes:

Attribute | Description | Valid Values | Default Value
--- | --- | --- | ---
template | A case-sensitive label which UM matches to a template's assigned name. Can be a comma-separated list of template names, which are applied in order. | string | (If omitted, no template is applied.)
order | Valid values are "deny,allow" and "allow,deny". Used to control how context usage is restricted. See Order and Rule Specifications. | string | `"deny,allow"`

Example:

<?xml version="1.0" encoding="UTF-8" ?>
<um-configuration version="1.0">
<templates>
<template name="CTX_FIX_Config.Prod">
...
</template>
...
</templates>
<applications>
<application name="FIX.01">
<contexts template="CTX_FIX_Config.Prod" order="deny,allow">
...
</contexts>
...
</application>
...
</applications>
...
</um-configuration>

## UM Element "<context>" <-

Container of configuration for a single context.

- Cardinality (number of times element can be supplied): 0 .. unbounded
- Parent: <contexts>
- Children: <sources>, <receivers>, <wildcard-receivers>, <options>

XML Attributes:

Attribute | Description | Valid Values | Default Value
--- | --- | --- | ---
name | Name of the context. Supplied as a parameter to lbm_context_attr_create_from_xml() and lbm_context_attr_set_from_xml(). Names are case-sensitive and can consist of only alpha-numeric ASCII characters, dash (-), and underscore (_). They must be 127 characters or less. | string | (If omitted, matches applications that don't set a context name.)
template | A case-sensitive label which UM matches to a template's assigned name. Can be a comma-separated list of template names, which are applied in order. | string | (If omitted, no template is applied.)
rule | Used to restrict the usage of contexts. See Order and Rule Specifications. | `"allow"` - Permit the matching object. `"deny"` - Prevent the matching object. | `allow`

Example:

<?xml version="1.0" encoding="UTF-8" ?>
<um-configuration version="1.0">
<templates>
<template name="CTX_FIX_Config.Prod">
...
</template>
...
</templates>
<applications>
<application name="FIX.01">
<contexts template="CTX_FIX_Config.Prod" order="deny,allow">
<context name="CTX_FIX" rule="allow">
...
</context>
...
</contexts>
...
</application>
...
</applications>
...
</um-configuration>

## UM Element "<wildcard-receivers>" <-

Container element that holds the configurations for wildcard receiver objects. The <wildcard-receiver> elements contained within `<wildcard-receivers>` are matched to the wildcard receiver objects created by the application.

Note
  If the user desires to constrain the use of wildcard receivers, it should be done with `order="allow,deny"` and `rule="allow"` attributes (which denies all wildcards except those specifically allowed). The use of `order="deny,allow"` and `rule="deny"` to allow any wildcard except those specifically denied will not work as desired. For example, denying the pattern ".*" will still permit the use of "^.*", which will match the same topics (i.e. all of them).

- Parent: <context>
- Children: <wildcard-receiver>

XML Attributes:

Attribute | Description | Valid Values | Default Value
--- | --- | --- | ---
template | A case-sensitive label which UM matches to a template's assigned name. | string | (If omitted, no template is applied.)
order | Valid values are "deny,allow" and "allow,deny". Used to control how wildcard receiver usage is restricted. See Order and Rule Specifications. | string | `"deny,allow"` (But note that this value is not useful for restrictingwildcard receivers. `"allow,deny"` should always be used.)

Example:

<?xml version="1.0" encoding="UTF-8" ?>
<um-configuration version="1.0">
<templates>
<template name="CTX_FIX_Config.Prod">
...
</template>
...
</templates>
<applications>
<application name="FIX.01">
<contexts template="CTX_FIX_Config.Prod" order="deny,allow">
<context name="CTX_FIX" rule="allow">
<wildcard-receivers template="WC_FIX_Config.Prod" order="deny,allow">
...
</wildcard-receivers>
...
</context>
...
</contexts>
...
</application>
...
</applications>
...
</um-configuration>

## UM Element "<wildcard-receiver>" <-

Container of configuration for a single wildcard receiver.

- Cardinality (number of times element can be supplied): 0 .. unbounded
- Parent: <wildcard-receivers>
- Children: <options>

XML Attributes:

Attribute | Description | Valid Values | Default Value
--- | --- | --- | ---
template | A case-sensitive label which UM matches to a template's assigned name. | string | (If omitted, no template is applied.)
rule | Used to restrict the usage of wildcard receivers. See Order and Rule Specifications. | `"allow"` - Permit the matching object. `"deny"` - Prevent the matching object. (Note that this is not a useful setting for restricting wildcard receivers since the application can choose a different pattern that matches the forbidden topic.) | `allow`
pattern | Match wildcard receivers with this pattern. Note that this string is matched exactly to the pattern supplied to the wildcard receiver. This pattern is not intended to match more than one wildcard receiver. | string | (no default; must be specified)
pattern-type | Type of wildcard receiver pattern matching engine the wildcard receiver is using. Only `"pcre"` is supported. | `"pcre"` - Perl regular expression. This is the only supported selection. `"regex"` - Posix regular expression. Deprecated; do not use. `"application-callback"` - Application-supplied pattern matcher. Deprecated; do not use. | `"pcre"`

Example:

<?xml version="1.0" encoding="UTF-8" ?>
<um-configuration version="1.0">
<templates>
<template name="CTX_FIX_Config.Prod">
...
</template>
...
</templates>
<applications>
<application name="FIX.01">
<contexts template="CTX_FIX_Config.Prod" order="deny,allow">
<context name="CTX_FIX" rule="allow">
<wildcard-receivers template="WC_FIX_Config.Prod" order="deny,allow">
<wildcard-receiver pattern="WC_FIX" rule="allow">
...
</wildcard-receiver>
...
</wildcard-receivers>
...
</context>
...
</contexts>
...
</application>
...
</applications>
...
</um-configuration>

## UM Element "<receivers>" <-

Container element that holds the configurations for receiver objects. The <topic> elements contained within `<receivers>` are matched to the receiver objects created by the application. For receivers that do not match any of the contained <topic> elements, the default permission is determined by the `order="..."` attribute.

- Parent: <context>
- Children: <topic>

XML Attributes:

Attribute | Description | Valid Values | Default Value
--- | --- | --- | ---
template | A case-sensitive label which UM matches to a template's assigned name. Can be a comma-separated list of template names, which are applied in order. | string | (If omitted, no template is applied.)
order | Valid values are "deny,allow" and "allow,deny". Used to control how receiver usage is restricted. See Order and Rule Specifications. | string | `"deny,allow"`

Example:

<?xml version="1.0" encoding="UTF-8" ?>
<um-configuration version="1.0">
<templates>
<template name="CTX_FIX_Config.Prod">
...
</template>
...
</templates>
<applications>
<application name="FIX.01">
<contexts template="CTX_FIX_Config.Prod" order="deny,allow">
<context name="CTX_FIX" rule="allow">
<receivers template="RCV_FIX_Config.Prod" order="deny,allow">
...
</receivers>
...
</context>
...
</contexts>
...
</application>
...
</applications>
...
</um-configuration>

## UM Element "<sources>" <-

Container element that holds the configurations for source objects. The <topic> elements contained within `<sources>` are matched to the source objects created by the application. For sources that do not match any of the contained <topic> elements, the default permission is determined by the `order="..."` attribute.

- Parent: <context>
- Children: <topic>

XML Attributes:

Attribute | Description | Valid Values | Default Value
--- | --- | --- | ---
template | A case-sensitive label which UM matches to a template's assigned name. Can be a comma-separated list of template names, which are applied in order. | string | (If omitted, no template is applied.)
order | Valid values are "deny,allow" and "allow,deny". Used to control how source usage is restricted. See Order and Rule Specifications. | string | `"deny,allow"`

Example:

<?xml version="1.0" encoding="UTF-8" ?>
<um-configuration version="1.0">
<templates>
<template name="CTX_FIX_Config.Prod">
...
</template>
...
</templates>
<applications>
<application name="FIX.01">
<contexts template="CTX_FIX_Config.Prod" order="deny,allow">
<context name="CTX_FIX" rule="allow">
<sources template="SRC_FIX_Config.Prod" order="deny,allow">
...
</sources>
...
</context>
...
</contexts>
...
</application>
...
</applications>
...
</um-configuration>

## UM Element "<templates>" <-

Container element that holds one or more configuration template definitions. A configuration template holds a set of UM configuration options. See XML Configuration File Format for information on templates.

- Parent: <um-configuration>
- Children: <template>

Example:

<?xml version="1.0" encoding="UTF-8" ?>
<um-configuration version="1.0">
<templates>
...
</templates>
...
</um-configuration>

## UM Element "<template>" <-

Container element that holds a collection of UM configuration options which can be referenced by other elements. See XML Configuration File Format for information on templates.

- Cardinality (number of times element can be supplied): 0 .. unbounded
- Parent: <templates>
- Children: <options>

XML Attributes:

Attribute | Description | Valid Values | Default Value
--- | --- | --- | ---
name | A case-sensitive label assigned to the template, which can be referenced by most other elements via their "template" attribute. Names are case-sensitive and can consist of any printable ASCII characters. They must be 99 characters or less. | string | (no default; must be specified)

Example:

<?xml version="1.0" encoding="UTF-8" ?>
<um-configuration version="1.0">
<templates>
<template name="FIX_Config.Prod">
...
</template>
...
</templates>
...
</um-configuration>

## UM Element "<license>" <-

Identifies the UM product license, either as the license key or as a pointer to a license file, as an alternative to setting it in an environment variable. The content within the `<license>...</license>` is either a file name or a license string, depending on the value supplied for the `format` attribute.

- Parent: <um-configuration>

XML Attributes:

Attribute | Description | Valid Values | Default Value
--- | --- | --- | ---
format | Specifies how the content within the `<license>...</license>` is interpreted. | `"filename"` - The license element contains the name of a file that contains the license key. `"string"` - The license element contains the actual license key. | string
xml:space | Specifies how whitespace (tabs, spaces, linefeeds) are handled in the element content. See xml:space Attribute. | `"default"` - Trim whitespace. `"preserve"` - Retain whitespace exactly as entered. | default

Example 1:

<?xml version="1.0" encoding="UTF-8" ?>
<um-configuration version="1.0">
<license format="filename">um_license.txt</license>
...
</um-configuration>

Example 2:

<?xml version="1.0" encoding="UTF-8" ?>
<um-configuration version="1.0">
<license format="string">
Product=LBM,UME,UMQ,UMDRO:Organization=User or Org:Expiration-Date=never:License-Key=1234 5678 9ABC DEF0
</license>
...
</um-configuration>

# XML Configuration File DTD <-

The XML configuration file DTD is integrated into UM and appears below.

<?xml version="1.0" encoding="UTF-8"?>
<!ELEMENT um-configuration (license | templates | applications)*>
<!ATTLIST um-configuration version CDATA #REQUIRED>
<!ELEMENT license ( #PCDATA )>
<!ATTLIST license format (filename | string) "string">
<!ATTLIST license xml:space (default | preserve) "default">
<!ELEMENT templates (template*)>
<!ELEMENT template (options+)>
<!ATTLIST template name CDATA #REQUIRED>
<!ELEMENT options (option | application-data)*>
<!ATTLIST options type (event-queue | context | source | receiver | wildcard-receiver | hfx) #IMPLIED>
<!ELEMENT option (allow | deny)*>
<!ATTLIST option name CDATA #REQUIRED>
<!ATTLIST option default-value CDATA #IMPLIED>
<!ATTLIST option order CDATA #IMPLIED>
<!ELEMENT application-data ( #PCDATA )>
<!ATTLIST application-data xml:space (default | preserve) "default">
<!ELEMENT allow ( #PCDATA )>
<!ATTLIST allow xml:space (default | preserve) "default">
<!ELEMENT deny ( #PCDATA )>
<!ATTLIST deny xml:space (default | preserve) "default">
<!ELEMENT applications (application*)>
<!ELEMENT application (contexts | event-queues | hfxs | application-data)+>
<!ATTLIST application name CDATA #IMPLIED>
<!ATTLIST application template CDATA #IMPLIED>
<!ELEMENT contexts (context*)>
<!ATTLIST contexts template CDATA #IMPLIED>
<!ATTLIST contexts order CDATA #IMPLIED>
<!ELEMENT event-queues (event-queue*)>
<!ATTLIST event-queues template CDATA #IMPLIED>
<!ATTLIST event-queues order CDATA #IMPLIED>
<!ELEMENT hfxs (topic*)>
<!ATTLIST hfxs template CDATA #IMPLIED>
<!ATTLIST hfxs order CDATA #IMPLIED>
<!ELEMENT event-queue (options*)>
<!ATTLIST event-queue name CDATA #IMPLIED>
<!ATTLIST event-queue template CDATA #IMPLIED>
<!ATTLIST event-queue rule (allow | deny) "allow">
<!ELEMENT context (sources | receivers | wildcard-receivers | options)+>
<!ATTLIST context name CDATA #IMPLIED>
<!ATTLIST context template CDATA #IMPLIED>
<!ATTLIST context rule (allow | deny) "allow">
<!ELEMENT sources (topic*)>
<!ATTLIST sources template CDATA #IMPLIED>
<!ATTLIST sources order CDATA #IMPLIED>
<!ELEMENT receivers (topic*)>
<!ATTLIST receivers template CDATA #IMPLIED>
<!ATTLIST receivers order CDATA #IMPLIED>
<!ELEMENT wildcard-receivers (wildcard-receiver*)>
<!ATTLIST wildcard-receivers template CDATA #IMPLIED>
<!ATTLIST wildcard-receivers order CDATA #IMPLIED>
<!ELEMENT topic (options*)>
<!ATTLIST topic template CDATA #IMPLIED>
<!ATTLIST topic rule (allow | deny) "allow">
<!ATTLIST topic pattern CDATA #IMPLIED>
<!ATTLIST topic topicname CDATA #IMPLIED>
<!ELEMENT wildcard-receiver (options*)>
<!ATTLIST wildcard-receiver template CDATA #IMPLIED>
<!ATTLIST wildcard-receiver rule (allow | deny) "allow">
<!ATTLIST wildcard-receiver pattern CDATA #IMPLIED>
<!ATTLIST wildcard-receiver pattern-type (pcre | regex | application-callback) #IMPLIED>

# Sample XML Configuration File <-

A sample XML configuration file appears below and has the following notable aspects.

- Contains object attributes for a UM context and source.
- Application name is Sending.
- Uses a template of attributes also called Sending-LBTRM.
- The template, Sending-LBTRM, uses the order attribute for the fd_management_type to allow all file descriptor types except DEVPOLL. However the Sending-LBTRM application further restricts the file descriptor types to exclude EPOLL in addition to DEVPOLL.

<?xml version="1.0" encoding="UTF-8" ?>
<um-configuration version="1.0">
<templates>
<template name="Sending-LBTRM">
<options type="source">
<option default-value="0" name="late_join"/>
<option default-value="500" name="resolver_advertisement_maximum_initial_interval"/>
<option default-value="5000" name="resolver_advertisement_minimum_initial_duration"/>
<option default-value="10" name="resolver_advertisement_minimum_initial_interval"/>
<option default-value="60" name="resolver_advertisement_minimum_sustain_duration"/>
<option default-value="1000" name="resolver_advertisement_sustain_interval"/>
<option default-value="lbtrm" name="transport"/>
<option default-value="14400" name="transport_lbtrm_destination_port"/>
<option default-value="0.0.0.0" name="transport_lbtrm_multicast_address"/>
</options>
<options type="context">
<option default-value="wsaeventselect" name="fd_management_type" order="deny,allow">
<deny>wincompport</deny>
</option>
<option default-value="5000" name="mim_delivery_control_activity_check_interval"/>
<option default-value="60000" name="mim_delivery_control_activity_timeout"/>
<option default-value="2000000" name="resolver_initial_advertisement_bps"/>
<option default-value="2000" name="resolver_initial_advertisements_per_second"/>
<option default-value="2000" name="resolver_initial_queries_per_second"/>
<option default-value="2000000" name="resolver_initial_query_bps"/>
</options>
</template>
</templates>
<applications>
<application name="Sending">
<contexts order="deny,allow">
<context rule="allow" template="Sending-LBTRM">
<sources order="deny,allow">
<topic rule="allow" topicname="IXCM">
<options type="source">
<option default-value="1" name="late_join"/>
<option default-value="lbtrm" name="transport"/>
<option default-value="14488" name="transport_lbtrm_destination_port"/>
<option default-value="239.101.3.101" name="transport_lbtrm_multicast_address"/>
</options>
</topic>
</sources>
<receivers order="deny,allow"/>
<wildcard-receivers order="deny,allow"/>
<options type="context">
<option default-value="239.101.4.11" name="resolver_multicast_address"/>
<option default-value="239.101.4.11" name="resolver_multicast_incoming_address"/>
<option default-value="12965" name="resolver_multicast_incoming_port"/>
<option default-value="239.101.4.11" name="resolver_multicast_outgoing_address"/>
<option default-value="12965" name="resolver_multicast_outgoing_port"/>
<option default-value="12965" name="resolver_multicast_port"/>
<option default-value="239.101.4.12" name="resolver_multicast_interface"/>
<option default-value="0" name="resolver_multicast_receiver_socket_buffer"/>
<option default-value="wsaeventselect" name="fd_management_type" order="deny,allow">
<deny>wincompport</deny>
</option>
</options>
</context>
</contexts>
<event-queues order="deny,allow">
<event-queue rule="allow">
<options type="event-queue">
<option default-value="lbm" name="monitor_transport"/>
<option default-value="" name="monitor_appid"/>
</options>
</event-queue>
</event-queues>
</application>
</applications>
</um-configuration>