Comm Effect Utility Model

The Comm Effect Utility Model allows emane to function and an IPv4 network impairment tool.

Features

The Comm Effect utility model provides the following features: Network Impairments and Static Filters.

Network Impairments

The Comm Effect Utility Model supports the following network impairments controlled via CommEffectEvents or static filter:

Loss: The percentage of packets that will be dropped utilizing a uniform distribution model.
Latency: The average delay for a packet to traverse the network. The total delay is composed of a fixed and variable component. The fixed amount of the delay is defined via a latency parameter and the variable amount via a jitter parameter. Both parameters are defined via CommEffectEvent or static filter. The jitter component to latency is determined randomly by applying a value pulled from a uniform random distribution of +/- the jitter parameter value. The randomly generated jitter value is then added to the fixed latency to determine the total delay.
Duplicates: The percentage of packets that will be duplicated at the receiver.
Unicast Bitrate: The bitrate for packets destined for the NEM or handled in promiscuous mode.
Broadcast Bitrate: The bitrate for packets destined for the NEM broadcast address.

Static Filters

The Comm Effect Utility Model supports the ability to define static filters to control network impairments. Filters are defined via an XML configuration file and have the following characteristics:

The filter file used by a given NEM within the emulation is identified at initialization time via the NEM’s filterfile configuration parameter. Each filter defined in the filterfile is characterized by one or more target elements and a single effect element.

Currently only IPv4 Ethernet packet filter targets are supported. The target element has the following format within the filter XML file:

<target>
  <ipv4 src='0.0.0.0' dst='0.0.0.0' len='0' ttl='0' tos='0'>
    <udp sport='0' dport='0'/>
    <protocol type='0'/>
  </ipv4>
</target>

All of the <ipv4> attributes are optional:
1. src: Source address in IPv4 header. Valid range 0.0.0.0 - 255.255.255.255, where 0.0.0.0 implies don’t care.
2. dst: Destination address in IPv4 header. Valid range 0.0.0.0 - 255.255.255.255, where 0.0.0.0 implies don’t care.
3. len: Total length in IPv4 header. Valid range 0 - 65535, where 0 implies don’t care.
4. ttl: Time to live in IPv4 header. Valid range 0 - 255, where 0 implies don’t care.
5. tos: Type of Service/Differentiated Services in IPv4 header. Valid range 0-255, where 0 implies don’t care.
In addition, a filter can be defined via the IPv4 protocol field in the header. The communication protocol can be defined by name or numerical value. Currently, udp is the only protocol that can be defined by name. All other protocols must be identified via numerical value.
1. <udp>: Used to identify UDP protocol by name. When using this mechanism to define the udp protocol, sport and/or dport can also be identified for the udp protocol header. The valid range for sport and dport are 0 to 65535, where 0 implies don’t care.
```
 <target>
   <ipv4 dst='224.1.2.3'>
     <udp sport='12345' dport='12346'/>
   </ipv4>
 </target>
```
2. <protocol>: Used when identifying the communication protocol based on numerical value. The type attribute identifies the numerical value for the IPv4 communication protocol with a valid range from 0 to 255.
```
 <target>
   <ipv4 dst='224.1.2.3'>
     <protocol type='89'/>
   </ipv4>
 </target>
```
Each filter is assigned static network impairments (loss, latency, jitter, duplicates, unicastbitrate and broadcastbitrate).
```
<effect>
  <loss>20</loss>
  <duplicate>0</duplicate>
  <latency sec='0' usec='200000'/>
  <jitter sec='0' usec='0'/>
  <broadcastbitrate>1024</broadcastbitrate>
  <unicastbitrate>8096</unicastbitrate>
</effect>
```
The effect element has the following format:
1. <loss>: The loss 0 to 100 in percentage to be applied to the packets that match the associated target.
2. <duplicate>: The duplicates 0 to 100 in percentage to be applied to the packets that match the associated target.
3. <latency>: The fixed average delay to be applied to the packets that match the associated target.
  
  sec: Seconds have a valid range 0 to 65535.
  usec: Microseconds have a valid range 0 to 999999.
4. <jitter>: The random variation applied to the packets that match the associated target.
  
  sec: Seconds have a valid range 0 to 65535.
  usec: Microseconds have a valid range 0 to 999999.
5. <unicastbitrate>: The bitrate (bps) applied to packets addressed to the NEM or received in promiscuous mode matching the associated target. The bitrate has a valid range from 0, meaning unused, to max unsigned 64 bit number.
6. <broadcastbitrate>: The bitrate (bps) applied to packets addressed to the NEM broadcast address matching the associated target. The bitrate has a valid range from 0, meaning unused, to max unsigned 64 bit number.
The filters and their associated impairments are defined at initialization and cannot be altered during emulation.

Filter ordering determines the network impairment, and as such, more specific filters should be defined first. Each received packet is evaluated against the defined filters in order and the first match determines the impairment to be applied. In the below example, a packet as it is received by a node will be evaluated against each of the four filters (OSPF, TOS, UDP, DEFAULT) in order and the respective effect will be applied based on the first match.

It should be noted that the inclusion of the DEFAULT filter should only be used when CommEffectEvents are not being utilized since the filters take precedence. When filters are used in conjunction with CommEffectEvents, the event driven impairments serve as the default effect for all packets that do not match a filter target.

<!DOCTYPE commeffect SYSTEM "file:///usr/share/emane/dtd/commeffectfilters.dtd">
<commeffect>
  <filter>
    <description>OSPF Packets</description>
    <target>
      <ipv4>
        <protocol type="89"/>
      </ipv4>
    </target>
    <effect>
      <loss>0</loss>
      <duplicate>0</duplicate>
      <latency sec='0' usec='0'/>
      <jitter sec='0' usec='0'/>
    </effect>
  </filter>
  <filter>
    <description>TOS (Type of Service) = 192</description>
    <target>
      <ipv4 tos='192'>
      </ipv4>
    </target>
    <effect>
      <loss>10</loss>
      <duplicate>150</duplicate>
      <latency sec='0' usec='100000'/>
      <jitter sec='0' usec='0'/>
    </effect>
  </filter>
  <filter>
    <description>UDP Multicast (destination address = 224.1.2.3 and destination port = 12345)</description>
    <target>
      <ipv4 dst='224.1.2.3'>
        <udp dport='12345'/>
      </ipv4>
    </target>
    <effect>
      <loss>20</loss>
      <duplicate>0</duplicate>
      <latency sec='0' usec='200000'/>
      <jitter sec='0' usec='0'/>
    </effect>
  </filter>
  <filter>
    <description>DEFAULT:  All Other Packets</description>
    <target/>
    <effect>
      <loss>40</loss>
      <duplicate>30</duplicate>
      <latency sec='0' usec='600000'/>
      <jitter sec='0' usec='100000'/>
      <broadcastbitrate>8096</broadcastbitrate>
      <unicastbitrate>8096</unicastbitrate>
    </effect>
  </filter>
</commeffect>

`CommEffectEvent`

package EMANEMessage;
option optimize_for = SPEED;
message CommEffectEvent
{
  message CommEffect
  {
    required uint32 nemId = 1;
    required float latencySeconds = 2;
    required float jitterSeconds = 3;
    required float probabilityLoss = 4;
    required float probabilityDuplicate = 5;
    required uint64 unicastBitRatebps = 6;
    required uint64 broadcastBitRatebps = 7;
  }
  repeated CommEffect commEffects = 1;
}

emane/src/libemane/commeffectevent.proto

NEM XML Structure

The Comm Effect utility model is not a radio model and does not use a physical layer. It is a special class of plugin called a shim. Shims follow all the same paradigms found in EMANE Paradigms, and it is possible to build an NEM that contains one or more shims. In practice, this is usually never necessary.

The NEM XML definition for a Comm Effect utility model instance only contains a <shim> and <transport> element. In order to be accepted by the emulator as valid, the <nem> type attribute must be set to unstructured in order to relax checks that aim to prevent incorrect NEM configuration.

<!DOCTYPE nem SYSTEM "file:///usr/share/emane/dtd/nem.dtd">
<nem type="unstructured">
  <transport definition="emane-transraw.xml"/>
  <shim definition="emane-commeffect-utilitymodel.xml"/>
</nem>

emane-guide/examples/commeffect-01/node-1/emane-commeffect-nem.xml

Configuration

defaultconnectivitymode: Defines the default connectivity mode for Comm Effects. When set to on, full connectivity will be engaged until a valid Comm Effect event is received.

Default: yes                   Required: no                    Modifiable: no                  
Type:    bool                  Occurrs:  [1,1]                 Range:      [false,true]        
Values:  true

enablepromiscuousmode: Defines whether promiscuous mode is enabled or not. If promiscuous mode is enabled, all received packets (intended for the given node or not) that pass the receive test are sent upstream to the transport.
```
Default: yes                   Required: no                    Modifiable: no                  
Type:    bool                  Occurrs:  [1,1]                 Range:      [false,true]        
Values:  false
```

filterfile: Defines the absolute URI of the effects filter XML file which contains static filters to control network impairments.

Default: no                    Required: no                    Modifiable: no                  
Type:    string                Occurrs:  [1,1]

groupid: Defines the Comm Effect Group Id. Only NEMs in the same Comm Effect Group can communicate.

Default: yes                   Required: no                    Modifiable: no                  
Type:    uint32                Occurrs:  [1,1]                 Range:      [0,4294967295]      
Values:  0

receivebufferperiod: Defines the max buffering time in seconds for packets received from an NEM. The buffering interval for a given packet is determined by the bitrate for the source NEM and the packet size. Packets are then placed in a timed queue based on this interval and all packets that would cause the receive buffer period to be exceeded are discarded. A value of 0.0 disables the limit and allows all received packets to stack up in the queue.
```
Default: yes                   Required: no                    Modifiable: no                  
Type:    double                Occurrs:  [1,1]                 Range:      [min_double,max_double]
Values:  1.000000
```

Statistics

avgDownstreamProcessingDelay0: Average downstream processing delay

Type: float                 Clearable: yes

avgProcessAPIQueueDepth: Average API queue depth for a processUpstreamPacket, processUpstreamControl, processDownstreamPacket, processDownstreamControl, processEvent and processTimedEvent.
```
Type: double                Clearable: yes                 
```
avgProcessAPIQueueWait: Average API queue wait for a processUpstreamPacket, processUpstreamControl, processDownstreamPacket, processDownstreamControl, processEvent and processTimedEvent in microseconds.
```
Type: double                Clearable: yes                 
```
avgTimedEventLatency: Average latency between the scheduled timer expiration and the actual firing over the requested duration.
```
Type: double                Clearable: yes                 
```
avgTimedEventLatencyRatio: Average ratio of the delta between the scheduled timer expiration and the actual firing over the requested duration. An average ratio approaching 1 indicates that timer latencies are large in comparison to the requested durations.
```
Type: double                Clearable: yes                 
```

avgUpstreamProcessingDelay0: Average upstream processing delay

Type: float                 Clearable: yes

numAPIQueued: The number of queued API events.

Type: uint64                Clearable: yes

numDownstreamBytesBroadcastGenerated0: Number of layer generated downstream broadcast bytes
```
Type: uint64                Clearable: yes                 
```

numDownstreamBytesBroadcastRx0: Number of downstream broadcast bytes received

Type: uint64                Clearable: yes

numDownstreamBytesBroadcastTx0: Number of downstream broadcast bytes transmitted
```
Type: uint64                Clearable: yes                 
```
numDownstreamBytesUnicastGenerated0: Number of layer generated downstream unicast bytes
```
Type: uint64                Clearable: yes                 
```

numDownstreamBytesUnicastRx0: Number of downstream unicast bytes received

Type: uint64                Clearable: yes

numDownstreamBytesUnicastTx0: Number of downstream unicast bytes transmitted

Type: uint64                Clearable: yes

numDownstreamPacketsBroadcastDrop0: Number of downstream broadcast packets dropped
```
Type: uint64                Clearable: yes                 
```
numDownstreamPacketsBroadcastGenerated0: Number of layer generated downstream broadcast packets
```
Type: uint64                Clearable: yes                 
```
numDownstreamPacketsBroadcastRx0: Number of downstream broadcast packets received
```
Type: uint64                Clearable: yes                 
```
numDownstreamPacketsBroadcastTx0: Number of downstream broadcast packets transmitted
```
Type: uint64                Clearable: yes                 
```

numDownstreamPacketsUnicastDrop0: Number of downstream unicast packets dropped

Type: uint64                Clearable: yes

numDownstreamPacketsUnicastGenerated0: Number of layer generated downstream unicast packets
```
Type: uint64                Clearable: yes                 
```

numDownstreamPacketsUnicastRx0: Number of downstream unicast packets received

Type: uint64                Clearable: yes

numDownstreamPacketsUnicastTx0: Number of downstream unicast packets transmitted
```
Type: uint64                Clearable: yes                 
```

numUpstreamBytesBroadcastRx0: Number of upstream broadcast bytes received

Type: uint64                Clearable: yes

numUpstreamBytesBroadcastTx0: Number of updtream broadcast bytes transmitted

Type: uint64                Clearable: yes

numUpstreamBytesUnicastRx0: Number upstream unicast bytes received

Type: uint64                Clearable: yes

numUpstreamBytesUnicastTx0: Number of upstream unicast bytes transmitted

Type: uint64                Clearable: yes

numUpstreamPacketsBroadcastDrop0: Number of upstream broadcast packets dropped

Type: uint64                Clearable: yes

numUpstreamPacketsBroadcastRx0: Number of upstream broadcast packets received

Type: uint64                Clearable: yes

numUpstreamPacketsBroadcastTx0: Number of upstream broadcast packets transmitted
```
Type: uint64                Clearable: yes                 
```

numUpstreamPacketsUnicastDrop0: Number of upstream unicast packets dropped

Type: uint64                Clearable: yes

numUpstreamPacketsUnicastRx0: Number upstream unicast packets received

Type: uint64                Clearable: yes

numUpstreamPacketsUnicastTx0: Number of upstream unicast packets transmitted

Type: uint64                Clearable: yes

processedConfiguration: The number of processed configuration.

Type: uint64                Clearable: yes

processedDownstreamControl: The number of processed downstream control.

Type: uint64                Clearable: yes

processedDownstreamPackets: The number of processed downstream packets.

Type: uint64                Clearable: yes

processedEvents: The number of processed events.

Type: uint64                Clearable: yes

processedTimedEvents: The number of processed timed events.

Type: uint64                Clearable: yes

processedUpstreamControl: The number of processed upstream control.

Type: uint64                Clearable: yes

processedUpstreamPackets: The number of processed upstream packets.

Type: uint64                Clearable: yes

Statistic Tables

BroadcastPacketAcceptTable0: Broadcast packets accepted
```
Clearable:  yes
```
BroadcastPacketDropTable0: Broadcast packets dropped by reason code
```
Clearable:  yes
```
EventReceptionTable: Received event counts
```
Clearable:  yes
```
UnicastPacketAcceptTable0: Unicast packets accepted
```
Clearable:  yes
```
UnicastPacketDropTable0: Unicast packets dropped by reason code
```
Clearable:  yes
```

Examples

This guide includes the IEEE 802.11abg example:

commeffect-01: A five host example where each host is configured on a flat 10.98.0.0/16 network and connected via lan0 to an NEM using a Raw Transport.

commeffect-01

commeffect-01 experiment components

The commeffect-01 example experiment contains five hosts configured on a flat 10.98.0.0/16 network and connected via lan0 to an NEM using a Raw Transport. This configuration illustrates how you can connect physical or virtual network appliances to EMANE, in a manner in which the appliance is unaware of the emulator’s presence, whether using a physical interface, tunnel, vif, etc. Here, the network appliances are LXCs but they can just as easily be physical devices connected to an EMANE server.

Each host has a lan0 interface that is monitored by a host corresponding NEM. All outbound host lan0 traffic is routed into the emulation and if successfully received by the NEM associated with the destination(s), will be written the destination(s)’s corresponding lan0.

All Comm Effect utility model instance are initialized with network impairments via the emaneeventservice which publishes CommEffectEvents using values in scenario.eel.

0  nem:1 commeffect nem:2,0,0,0,0,1000000,1000000
0  nem:1 commeffect nem:3,0,0,0,0,1000000,1000000
0  nem:1 commeffect nem:4,0,0,0,0,1000000,1000000
0  nem:1 commeffect nem:5,0,0,0,0,1000000,1000000

0  nem:2 commeffect nem:1,0,0,0,0,1000000,1000000
0  nem:2 commeffect nem:3,0,0,0,0,1000000,1000000
0  nem:2 commeffect nem:4,0,0,0,0,1000000,1000000
0  nem:2 commeffect nem:5,0,0,0,0,1000000,1000000

0  nem:3 commeffect nem:1,0,0,0,0,1000000,1000000
0  nem:3 commeffect nem:2,0,0,0,0,1000000,1000000
0  nem:3 commeffect nem:4,0,0,0,0,1000000,1000000
0  nem:3 commeffect nem:5,0,0,0,0,1000000,1000000

0  nem:4 commeffect nem:1,0,0,0,0,1000000,1000000
0  nem:4 commeffect nem:2,0,0,0,0,1000000,1000000
0  nem:4 commeffect nem:3,0,0,0,0,1000000,1000000
0  nem:4 commeffect nem:5,0,0,0,0,1000000,1000000

0  nem:5 commeffect nem:1,0,0,0,0,1000000,1000000
0  nem:5 commeffect nem:2,0,0,0,0,1000000,1000000
0  nem:5 commeffect nem:3,0,0,0,0,1000000,1000000
0  nem:5 commeffect nem:4,0,0,0,0,1000000,1000000

emane-guide/examples/commeffect-01/host/scenario.eel

All hosts are configured similarly, taking a look at host-1 interfaces we can see the lan0 interface is configured as 10.98.1.2/16.

$ ssh host-1 ip addr show dev lan0
3: lan0@if102: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default qlen 1000
    link/ether 7e:9a:ba:30:f0:90 brd ff:ff:ff:ff:ff:ff link-netnsid 0
    inet 10.98.1.2/16 brd 10.98.255.255 scope global lan0
       valid_lft forever preferred_lft forever
    inet6 fe80::7c9a:baff:fe30:f090/64 scope link
       valid_lft forever preferred_lft forever

Looking at host-1 routes shows a flat network which is different than the host configuration in previous experiments which used a tiered topology with radio nodes acting as gateways for hosts.

$ ssh host-1 ip route show
10.98.0.0/16 dev lan0 proto kernel scope link src 10.98.1.2
10.99.0.0/16 dev backchan0 proto kernel scope link src 10.99.1.1

Pinging from host-1 to all other hosts over the lan0 interface shows 100% completion and minimal latency.

$ ssh host-1 fping host-2-lan host-3-lan host-4-lan host-5-lan -C 2
host-2-lan : [0], 64 bytes, 2.42 ms (2.42 avg, 0% loss)
host-3-lan : [0], 64 bytes, 2.70 ms (2.70 avg, 0% loss)
host-4-lan : [0], 64 bytes, 2.61 ms (2.61 avg, 0% loss)
host-5-lan : [0], 64 bytes, 2.70 ms (2.70 avg, 0% loss)
host-2-lan : [1], 64 bytes, 3.37 ms (2.90 avg, 0% loss)
host-3-lan : [1], 64 bytes, 3.35 ms (3.03 avg, 0% loss)
host-4-lan : [1], 64 bytes, 3.28 ms (2.95 avg, 0% loss)
host-5-lan : [1], 64 bytes, 3.11 ms (2.90 avg, 0% loss)

host-2-lan : 2.42 3.37
host-3-lan : 2.70 3.35
host-4-lan : 2.61 3.28
host-5-lan : 2.70 3.11

Using the emaneevent-commeffect utility, we can set the latency of all links to 100ms.

$ emaneevent-commeffect 1:5 latency=.1 -i letce0

Reissuing the same ping command verifies 100ms of latency in each directions.

$ ssh host-1 fping host-2-lan host-3-lan host-4-lan host-5-lan -C 2
host-2-lan : [0], 64 bytes, 201 ms (201 avg, 0% loss)
host-3-lan : [0], 64 bytes, 201 ms (201 avg, 0% loss)
host-4-lan : [0], 64 bytes, 201 ms (201 avg, 0% loss)
host-5-lan : [0], 64 bytes, 201 ms (201 avg, 0% loss)
host-2-lan : [1], 64 bytes, 202 ms (202 avg, 0% loss)
host-3-lan : [1], 64 bytes, 202 ms (201 avg, 0% loss)
host-4-lan : [1], 64 bytes, 201 ms (201 avg, 0% loss)
host-5-lan : [1], 64 bytes, 201 ms (201 avg, 0% loss)

host-2-lan : 201 202
host-3-lan : 201 202
host-4-lan : 201 201
host-5-lan : 201 201