nrlsmf User's Guide

The nrlsmf application can be run as a stand-alone application capable of providing "classic" flooding of broadcast and multicast traffic for a specified network interface or can be used in conjunction with a controlling program to perform more sophisticated multicast forwarding. An interprocess communication "remote control" interface is provided so that a compatible program (e.g. nrlolsrd) may issue run-time commands to nrlsmf to dynamically control the multicast forwarding process. Both IPv4 and IPv6 operation are supported. Versions of nrlsmf can be built for the following operating systems: Linux, MacOS, BSD, Win32, and WinCE. The code base also supports working simulation models of SMF in the ns-2 and OPNET discrete event simulation environments. In the future it is hoped that the SMF functionality might be included as part of operating system kernels.

The nrlsmf program acts as a user-space packet forwarding engine by promiscuously "sniffing" packets on a specified interface or intercepting packets using operating system firewall facilities and then retransmitting packets (using its local network interface MAC address) according to set forwarding rules. Packets can be received and possibly forwarded on a single, specified network interface for operation within a "routing area" corresponding to that single (generally wireless) interface. And, nrlsmf also provides for packet reception and forwarding across multiple interfaces to allow for configurable gateway operation and/or multicast distribution across a set of interfaces. Only incoming (non-locally generated), non-link-local IP Multicast packets with time-to-live (TTL) greater than one are considered for forwarding. Duplicate packet detection is an important facet of wireless network multicast forwarding since packets often must be forwarded on the same interface as they are received. Thus, neighbors' subsequent retransmission of forwarded packets will be "heard" and the local forwarding engine must discriminate between new packets and previously-forwarded packets to avoid unnecessary retransmission.

The nrlsmf program provides a command-line syntax with which it can be launched. Many of the same commands (see Commands) available via the command-line may be applied during run-time using the "remote control" interprocess control interface (see Remote Control Interface). To launch nrlsmf, use the following command-line syntax:

nrlsmf [ipv6][resequence {on|off}][nhdp <ifaceList>]
       [cf <ifaceList>][smpr <ifaceList>][ecds <ifaceList>]
       [push <srcIface>,<dstIfaceList>][rpush <srcIface>,<dstIfaceList>]
       [merge <ifaceList>][rmerge <ifaceList>]
       [clear {<ifaceList>|all}]
       [unpush <srcIface>,<dstIfaceList>][unmerge <srcIface>,<dstIfaceList>]
       [forward {on|off}][relay {on|off}]
       [hash <algorithm>][idpd {on | off}][window {on|off}]
       [firewallForward {on|off}][firewallCapture {on|off}]
       [tap <tapInstanceName>]
       [instance <instanceName>][debug <debugLevel>][log <logFile>

The nrlsmf program supports a variety of commands that can be invoked via command-line at startup or at run-time using the "remote control" interprocess communication interfaces that is provided. There a four rough categories of commands. These include:

It should be noted that all of the commands listed here can be invoked via the run-time remote control interface (see Remote Control Interface). However, some commands, particularly the "Operating Mode Commands" are not intended to be invoked after initial startup. And, in general, the "Operating Mode Commands" SHOULD be invoked before other commands at startup. In some cases (firewallForward, etc), it is required that these commands precede "Interface" or "Gateway" commands.

The "MANET Interface Commands" apply to configuring specific, usually wireless, interfaces for MANET SMF operation. As such, packets inbound on such "MANET" interfaces may also be forwarded by nrlsmf back out the same interface as well as possibly other interfaces if so configured. The "resequence" command listed here should be used to ensure that packets generated are properly labeled using the IPv4 ID field or the IPv6 SMF_DPD header option for SMF duplicate packet detection.

The "Gateway Commands" apply to configuring nrlsmf to support a forced relay of packets to/from MANET/non-MANET interfaces. This can allow creation of gateways from infrastructure IP networks (e.g., the Internet) with IP Multicast routing support to dynamic MANET areas that rely upon SMF for group data distribution. The commands provided here are designed to have a great deal of flexibility, so some care must be taken to avoid loops with the modes (i.e., "rpush" or "rmerge" commands) that "resequence" (or tag) packet flows for duplicate packet detection. The nrlsmf application has some logic in its command-parsing to avoid some of these scenarios, but the flexibility allowed permits some configurations that may produce undesirable effects.

The "Remote-only Commands" listed here can be invoked only via the run-time, interprocess remote-control interface (see Remote Control Interface). The principal reason these commands are available only via inter-process communication is that the commands have a partially binary format to convey lists of MAC addresses to control aspects of nrlsmf operation. In each of these commands, an ASCII prefix is given to indicate the command type, followed by an ASCII "space" character, and then the binary list of concatenated 6-byte Ethertype MAC addresses (in Big Endian order). The length of the datagram command sent to nrlsmf implies the length of the MAC address list. The "selectorMac" and "neighborMac" apply to control of S-MPR forwarding. The "mneBlockMac" command is provided to support proper SMF behavior in the NRL Mobile Network Emulation (MNE) environment.

 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|   indexCount  | inboundIfIndex|       outboundIfIndex list    |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+               +-+-+-+-+-+-+-+-+
|                       ...                     |               |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+               |
|                                                               |
|                Ether-type frame w/ IP packet                  |
|                              ...                              |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

The nrlsmf application provides an interprocess communication "remote control" interface for receiving run-time instructions from other processes. The "remote control" interface is identified by a canonical name <instanceName>. The default name used by nrlsmf is, strangely enough, "nrlsmf". However, an alternative name can be specified using the instance command-line option described above. This might be useful if multiple nrlsmf instances are required to cover multiple network interfaces.

On UNIX systems, the <instanceName> corresponds to a Unix-domain datagram socket named "/tmp/<instanceName>" that is opened and monitored for commands (thus the default nrlsmf Unix-domain socket would be identified as "/tmp/nrlsmf"). On WIN32 systems, a "mailslot" named "\\.\mailslot\<instanceName>" is created and used while on WinCE systems a semaphore is instantiated along with a corresponding registry entry mapping to a locally-bound UDP socket provides equivalent functionality.

There are limitations in the use of some nrlsmf options. Many of these limitations are a result of nrlsmf being a cross-platform, user-space implementation. Many of these subtleties could be overcome with a kernel implementation of the code.

For example, to take advantage of configured firewall rules and/or quality-of-service (QoS) policies for multicast data transmission and forwarding, it may be desirable to use the nrlsmf "firewallForward" and/or "firewallCapture" options. There are some limitations associated with the user-space mechanisms available to capture and "forward" packets in this manner.

Some of these limitations may be addressed in future versions of nrlsmf if possible. It may be possible in some cases that system configuration (perhaps using virtual interface capabilities) may provide work-around solutions for some of these issues.

There are a number of additional features and refinements planned for the nrlsmf implementation. Some of these (in roughly priority order) include: