Concepts Guide

lbmrd Configuration File

The lbmrd configuration file must start with this line:

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

After that, the '<lbmrd>' element contains the rest of the configuration.

The lbmrd configuration does not support the XInclude feature.

Note
  The configuration file must contain a '<domains>' element and a '<transformations>' element (and their contents), even if there is no NAT. See Dummy lbmrd Configuration File. The '<daemon>' element and its contents are optional.

# lbmrd Configuration Elements <-

## LBMRD Element "<lbmrd>" <-

Container element which holds the lbmrd configuration. Also defines the version of the configuration format used by the file.

- Children: <daemon>, <domains>, <transformations>

XML Attributes:

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

Example:

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

## LBMRD Element "<transformations>" <-

Container element for definitions of NAT translations applied to TIRs. Translations are used to help lbmrd know how to modify source advertisements when Network Address Translation (NAT) is being used.

See LBMRD NAT Transit for more information on NAT.

- Parent: <lbmrd>
- Children: <transform>

Example:

<?xml version="1.0" encoding="UTF-8" ?>
<lbmrd version="1.0">
<transformations>
...
</transformations>
...
</lbmrd>

For a full example of an lbmrd NAT configuration, see Example NAT Configuration.

## LBMRD Element "<transform>" <-

Defines a set of transformation tuples. Each tuple applies to a TIR sent from a specific network domain (specified using the `source` attribute), and destined for a specific network domain (specified using the `destination` attribute). The `source` and `destination` attributes must specify network domain names as defined by the <domain> elements.

See LBMRD NAT Transit for more information on NAT.

- Parent: <transformations>
- Children: <rule>

XML Attributes:

Attribute | Description | Valid Values | Default Value
--- | --- | --- | ---
source | Name of source network domain, defined in <domain>. | IDREF | (no default; must be specified)
destination | Name of receiver network domain, defined in <domain>. | IDREF | (no default; must be specified)

Example:

<?xml version="1.0" encoding="UTF-8" ?>
<lbmrd version="1.0">
<transformations>
<transform source="Net-NYC" destination="Net-NJC">
...
</transform>
...
</transformations>
...
</lbmrd>

For a full example of an lbmrd NAT configuration, see Example NAT Configuration.

## LBMRD Element "<rule>" <-

Container for a transformation rule which maps one address and port to another.

See LBMRD NAT Transit for more information on NAT.

- Parent: <transform>
- Children: <match>, <replace>

Example:

<?xml version="1.0" encoding="UTF-8" ?>
<lbmrd version="1.0">
<transformations>
<transform source="Net-NYC" destination="Net-NJC">
<rule>
...
</rule>
...
</transform>
...
</transformations>
...
</lbmrd>

For a full example of an lbmrd NAT configuration, see Example NAT Configuration.

## LBMRD Element "<replace>" <-

Defines the address and port which are to replace those matched in the TIR originating from a UM context within the `source` network (as specified by <transform>), and being delivered to contexts within the `destination` network.

- Parent: <rule>

XML Attributes:

Attribute | Description | Valid Values | Default Value
--- | --- | --- | ---
address | IP address within a TIR. Address must be specified only in dotted-decimal and refer to a specific host. For LBMRD Element "<match>", the IP address should be within the network specified by <transform> `source` attribute. For LBMRD Element "<replace>", the IP address should be within the network specified by <transform> `destination` attribute. | string | (no default; must be specified)
port | Port number to match or replace. To match any port, use value `"*"`. To replace with same port as matched, use value `"*"`. | string | `"*"`

Example:

<?xml version="1.0" encoding="UTF-8" ?>
<lbmrd version="1.0">
<transformations>
<transform source="Net-NYC" destination="Net-NJC">
<rule>
<match address="10.1.1.50" port="*"/>
<replace address="192.168.1.1" port="*"/>
...
</rule>
...
</transform>
...
</transformations>
...
</lbmrd>

For a full example of an lbmrd NAT configuration, see Example NAT Configuration.

## LBMRD Element "<match>" <-

Defines the address and port to match within a TIR originating from a UM context within the `source` network (as specified by <transform>), and being delivered to contexts within the `destination` network.

- Parent: <rule>

XML Attributes:

Attribute | Description | Valid Values | Default Value
--- | --- | --- | ---
address | IP address within a TIR. Address must be specified only in dotted-decimal and refer to a specific host. For LBMRD Element "<match>", the IP address should be within the network specified by <transform> `source` attribute. For LBMRD Element "<replace>", the IP address should be within the network specified by <transform> `destination` attribute. | string | (no default; must be specified)
port | Port number to match or replace. To match any port, use value `"*"`. To replace with same port as matched, use value `"*"`. | string | `"*"`

Example:

<?xml version="1.0" encoding="UTF-8" ?>
<lbmrd version="1.0">
<transformations>
<transform source="Net-NYC" destination="Net-NJC">
<rule>
<match address="10.1.1.50" port="*"/>
<replace address="192.168.1.1" port="*"/>
...
</rule>
...
</transform>
...
</transformations>
...
</lbmrd>

For a full example of an lbmrd NAT configuration, see Example NAT Configuration.

## LBMRD Element "<domains>" <-

Container element for definitions of network domains. Network domains are used to help lbmrd recognize networks and/or subnetworks which connect via Network Address Translation (NAT).

See LBMRD NAT Transit for more information on NAT.

- Parent: <lbmrd>
- Children: <domain>

Example:

<?xml version="1.0" encoding="UTF-8" ?>
<lbmrd version="1.0">
<domains>
...
</domains>
...
</lbmrd>

For a full example of an lbmrd NAT configuration, see Example NAT Configuration.

## LBMRD Element "<domain>" <-

Defines a network domain. The domain must be given a unique name via the `name` attribute. This name is referenced in <transform> elements. The `<domain>` element contains one or more <network> elements.

See LBMRD NAT Transit for more information on NAT.

- Parent: <domains>
- Children: <network>

XML Attributes:

Attribute | Description | Valid Values | Default Value
--- | --- | --- | ---
name | Unique name assigned to the defined network. | ID | (no default; must be specified)

Example:

<?xml version="1.0" encoding="UTF-8" ?>
<lbmrd version="1.0">
<domains>
<domain name="Net-NYC">
...
</domain>
<domain name="Net-NJC">
...
</domain>
...
</domains>
...
</lbmrd>

For a full example of an lbmrd NAT configuration, see Example NAT Configuration.

## LBMRD Element "<network>" <-

Defines a single network specification which is to be considered part of the enclosing <domain> element. The network specification must contain either an IP address, or a network specification in CIDR notation. DNS host names are not supported in the lbmrd configuration file.

See LBMRD NAT Transit for more information on NAT.

- Parent: <domain>

Example:

<?xml version="1.0" encoding="UTF-8" ?>
<lbmrd version="1.0">
<domains>
<domain name="Net-NYC">
<network>10.1.0.0/16</network>
...
</domain>
<domain name="Net-NJC">
<network>192.168.1/24</network>
...
</domain>
...
</domains>
...
</lbmrd>

For a full example of an lbmrd NAT configuration, see Example NAT Configuration.

## LBMRD Element "<daemon>" <-

Container element for configuration related to the overall lbmrd process.

- Cardinality (number of times element can be supplied): 0 .. 1
- Parent: <lbmrd>
- Children: <activity>, <interface>, <port>, <ttl>, <log>, <resolver_unicast_receiver_socket_buffer>, <resolver_unicast_send_socket_buffer>

Example:

<?xml version="1.0" encoding="UTF-8" ?>
<lbmrd version="1.0">
<daemon>
...
</daemon>
...
</lbmrd>

## LBMRD Element "<resolver_unicast_send_socket_buffer>" <-

Sets the send-side socket buffer size (in bytes).

- Parent: <daemon>
- Default Value: 1048576

Example:

<?xml version="1.0" encoding="UTF-8" ?>
<lbmrd version="1.0">
<daemon>
<resolver_unicast_send_socket_buffer>
1048576
</resolver_unicast_send_socket_buffer>
...
</daemon>
...
</lbmrd>

## LBMRD Element "<resolver_unicast_receiver_socket_buffer>" <-

Sets the receive-side socket buffer size (in bytes).

- Parent: <daemon>
- Default Value: 1048576

Example:

<?xml version="1.0" encoding="UTF-8" ?>
<lbmrd version="1.0">
<daemon>
<resolver_unicast_receiver_socket_buffer>
1048576
</resolver_unicast_receiver_socket_buffer>
...
</daemon>
...
</lbmrd>

## LBMRD Element "<log>" <-

Specifies the file name used for lbmrd logging.

- Parent: <daemon>

Example:

<?xml version="1.0" encoding="UTF-8" ?>
<lbmrd version="1.0">
<daemon>
<log>lbmrd.log</log>
...
</daemon>
...
</lbmrd>

## LBMRD Element "<ttl>" <-

Interval (in milliseconds) between keep alive checks between the lbmrd and the UM contexts.

- Parent: <daemon>
- Default Value: 60000

Example:

<?xml version="1.0" encoding="UTF-8" ?>
<lbmrd version="1.0">
<daemon>
<ttl>60000</ttl>
...
</daemon>
...
</lbmrd>

## LBMRD Element "<port>" <-

Supplies network port to bind the socket for receiving TR traffic from UM contexts. This is the port that a UM context should use when TCP-based TR is configured with the option resolver_unicast_daemon (context). The value contained within the `<port>...</port>` is an integer between 1 and 65535.

- Parent: <daemon>
- Default Value: 15380

Example:

<?xml version="1.0" encoding="UTF-8" ?>
<lbmrd version="1.0">
<daemon>
<port>15380</port>
...
</daemon>
...
</lbmrd>

## LBMRD Element "<interface>" <-

Specifies the network interface to bind the socket for receiving TR traffic from UM contexts. This is the IP address that a UM context should use when Unicast UDP-based TR is configured with the option resolver_unicast_daemon (context). See Specifying Interfaces for methods of specifying the interface within `<interface>...</interface>`.

If not specified, UM chooses the first interface it finds.

WARNING: It is strongly recommended to specify an interface when running lbmrd, either via the "-i" command-line option, or the `<interface>` XML tag. Otherwise, UM will select the first interface it finds, potentially 127.0.0.1 (loopback), which is rarely a good choice. Note that CIDR notation can make it easier. For example, "10.0.0.0/8" will match any interface on the 10 network.

- Parent: <daemon>

Example:

<?xml version="1.0" encoding="UTF-8" ?>
<lbmrd version="1.0">
<daemon>
<interface>10.1.1.50</interface>
...
</daemon>
...
</lbmrd>

## LBMRD Element "<activity>" <-

Interval between client activity checks (in milliseconds)

- Parent: <daemon>
- Default Value: 60000

Example:

<?xml version="1.0" encoding="UTF-8" ?>
<lbmrd version="1.0">
<daemon>
<activity>60000</activity>
...
</daemon>
...
</lbmrd>

# Dummy lbmrd Configuration File <-

If no NAT is present, and it is desired to use the XML configuration file for it's '<daemon>' contents, a "dummy" NAT configuration should be used.

<?xml version="1.0" encoding="UTF-8" ?>
<lbmrd version="1.0">
<daemon>
...
</daemon>
<domains>
<domain name="dummy">
<network>0.0.0.0/32</network>
</domain>
</domains>
<transformations>
<transform source="dummy" destination="dummy">
<rule>
<match address="0.0.0.0" port="0"/>
<replace address="0.0.0.0" port="0"/>
</rule>
</transform>
</transformations>
</lbmrd>

# Lbmrd DTD file <-

The DTD file is used to validate the user's configuration file.

<!ELEMENT lbmrd (daemon?, domains, transformations)>
<!ATTLIST lbmrd
version (1.0) #REQUIRED
>
<!ELEMENT daemon (activity|interface|port|ttl|log|resolver_unicast_receiver_socket_buffer|resolver_unicast_send_socket_buffer)*>
<!ELEMENT activity (#PCDATA) >
<!ELEMENT interface (#PCDATA) >
<!ELEMENT port (#PCDATA) >
<!ELEMENT ttl (#PCDATA) >
<!ELEMENT log (#PCDATA) >
<!ELEMENT resolver_unicast_receiver_socket_buffer (#PCDATA) >
<!ELEMENT resolver_unicast_send_socket_buffer (#PCDATA) >
<!ELEMENT domains (domain+)>
<!ELEMENT domain (network+)>
<!ATTLIST domain name ID #REQUIRED>
<!ELEMENT network ( #PCDATA )>
<!ELEMENT transformations ( transform+ )>
<!ELEMENT transform ( rule+ )>
<!ATTLIST transform
source IDREF #REQUIRED
destination IDREF #REQUIRED
>
<!ELEMENT rule ( match, replace )>
<!ELEMENT match EMPTY>
<!ATTLIST match
address CDATA #REQUIRED
port CDATA "*"
>
<!ELEMENT replace EMPTY>
<!ATTLIST replace
address CDATA #REQUIRED
port CDATA "*"
>