office: (770) 432-4580
fax: (770) 234-4182
skype: pcausa

NDIS Interface Impairment Generator

Overview

Occasionally there is a need to test network software on networks that "have problems" such as random packet drop and delays. This is especially true if you are using an unreliable protocol such as UDP or network media such as 802.11.

There are hardware test sets that can simulate a wide variety of impairments, and it is certainly recommended that you use them if you can afford them.

The PCAUSA Interface Impairment Generator is intended to provide a modest impairment capability in software. In some cases this limited capability may be sufficient.

Implementation Overview

The Impairment Generator is implemented as a NDIS filter installed as low as possible in the layer of filters above each Ethernet adapter miniport. In this position the NDIS filter can manipulate packets being sent or received to simulate various impairments. The generator currently supports these impairments:

  • Random Packet Drop on Send and Receive Paths
  • Send and Receive Packet Delay in 1 millisecond (approximate...) Increments

In addition the generator is capable of editing the IP header TTL (IPv4) or hop limit (IPv6) fields on outgoing packets:

  • Set TTL to Specified Value
  • Decrement TTL by Specified Value

By default the driver imposes impairments on all packets of selected protocol types that are sent or received on a specified interface. Optionally the user may further specify a remote host and impairments will be imposed only on packets exchanged between the local host and that host.

Installing and Using the Sample

Driver Installation

At this time the Impairment Generator NDIS drivers must be installed using the Network Control Panel. Select an Ethernet adapter, press the Install button and then select Service. Browse to the driver package folder appropriate for your platform:

  • WHL - For Windows Vista and Later 32-Bit Platforms
  • WLH_AMD64 - For Windows Vista and Later 64-Bit Platforms
  • WXP - For Windows XP and Windows Server 2003 32-Bit Platforms
  • WXP_AMD64 - For Windows XP and Windows Server 2003 32-Bit Platforms

Select the PcaEmulatorV1 INF file and then complete the installation.

If your platform has multiple adapters you can Uncheck the PCAUSA Network Emulator NDIS 6 Filter from adapters that you do not wish to impair.

TDPortMon Application Usage

The Impairment Generator control program is a Windows command line utility named ifimp.exe. The Usage output is:

C:\PCADev\FaultInjector>ifimp
PCAUSA NDIS Interface Impairment Generator V1.00.00.06 (32-Bit)
Copyright (c) 2010 Printing Communications Assoc., Inc. (PCAUSA)
All rights reserved

Set Impairments : ifimp [-4 -6 ] [ -p icmp -p tcp -p udp ] [ -options ] <interface>
Clear Impaitments: ifimp -c <interface>
Query Impairments: ifimp -q <interface>
Enumerate Filters: ifimp -f <interface>
Set Impairment options:
    -4 impair IPv4
    -6 impair IPv6
    -r ## remote host name
    -p ## protocol to impair: icmp, tcp or udp
    -i ## ## send drop and receive drop rates as percent
    -t ## send ttl: positive->set; negative->decrement
    -d ## packet delay in milliseconds
 

Understand that for all ifimp commands the last parameter of the command must the the IPv4 address of the adapter to be impaired.

In the example below IPv4 ICMP and TCP packets will be impaired on interface 192.168.15.107. Send and receive packets will be randomly dropped at a .5-percent rate. Packets that are not dropped will have their TTL decremented by 32 as they pass through the driver. The packet delay for send and receive is set to 1 milliseconds, which adds a total of 2 milliseconds to round-trip time.

C:\PCADev\FaultInjector>ifimp -4 -p tcp -i .5 .5 -d 1 -t -32 192.168.15.107

192.168.15.107 0.500000 0.500000 32
Delay: 1 msec
0x00000023 192.168.15.107 10737418 10737418 32
Delay: 10000 100-nsec units
Impairment Changed (Immediate)

It is not necessary to specify all impairment options. For example, the -t and the -d option can be omitted if desired:

C:\PCADev\FaultInjector>ifimp -4 -p tcp -i .5 .5 192.168.15.107

The capability to impose impairments on a single "flow" is also provided. The "-r" option can be used to specify a remote host name. If this option is selected then the impairments are applied only on packets destined to the specified remote host. In the example below impairments are restricted to packets sent/received from "fiveeyes" host:

C:\PCADev\FaultInjector>ifimp -4 -p tcp -r fiveeyes -i .5 .5 -d 100 -t 32 192.168.15.107

Clearing Impairments

The -c "clear" command line option can be used to clear all impairments in a specific interface. For example this command:

C:\PCADev\FaultInjector>ifimp -c 192.168.15.107
 

will remove all impairments on interface 192.168.15.107.

Viewing Settings and Statistics

The -q "query" command line option can be used to fetch the current impairment settings and statistics on an interface. For example:

C:\PCADev\FaultInjector\Work\Apps\Release>ifimp -q 192.168.15.121

will fetch this information on interface 192.168.15.121. Here is sample output:

Impairment Query Success

Interface: 192.168.15.121

Filter : IPv4, Match IPv4, ICMP

Remote IPv4 Host: 192.168.15.117

Send Drop:
   Command: 24.999999 percent
   Actual : 29.126214 percent
      Dropped 30 of 103 Packets

Receive Drop:
   Command: 24.999999 percent
   Actual : 27.397260 percent
      Dropped 20 of 73 Packets

Delay: 0 milliseconds
   Delayed 0 Send Packets
   Delayed 0 Receive Packets
      Delay Failed 0 Receive Packets

Example Random Drop Behavior

For this test the PCATTCP tool was used to generate a continuous TCP stream. The send and receive packet drop was set to .2 percent in each direction using this command:

C:\PCADev\FaultInjector\Work\Apps\Release>ifimp -4 -6 -p tcp -i .2 .2 192.168.15.107

192.168.15.107 0.200000 0.200000 0 0
0x00000023 192.168.15.107 4294967 4294967 0 0
Impairment Changed (Immediate)

The Task Manager Networking utilization is shown below. You can see that performance varied quite a bit. At the tail of the test the impairments were cleared and you can see the normal steady-state of the unimpaired interface.

Packet Delay Behavior

Windows is not a real-time operating system. It's minimum timer quantum is 1 millisecond or (much) more. The impairment generator packet delay result impairment is somewhat crude, but possibly helpful to some.

Using a TCP test program such as PCATTCP on a 1 Gbps Ethernet sustained TCP transfers approaching 500 Mbps can be achieved. However, with a minimum delay setting of 1 millisecond the transfer rate is reduced to about 32 Mbps. This is, in fact, about right for the 1 millisecond delay.

When performing sustained TCP transfers Windows usually sends a "list" of TCP packets each containing up to 1460 bytes of data payload. The size of this list can range from 1 to 6 (or more) packets. Assuming 6 1460-byte packets being sent with a send delay of 1 millisecond and a receive delay also of 1 millisecond, then 8760 bytes are transferred every 2 milliseconds. This corresponds roughly to 35 Mbps and agrees with the observed behavior of the impairment generator delay results.

This does not mean that the interface itself has been limited to the much lower apparent rate. For example, adding a second stream will up the interface utilization. Three even more, and so on.

On some systems - particular pre-Vista - the delay behavior may be fairly poor. For example, specifying a 1 millisecond delay in each direction may result in adding about 30 milliseconds to the RT time.

Examining Network Stack Layering

The -f option displays a list of the filters installed on the specified interface. Filters are ordered from the highest to the lowest in this list.

This command is only supported on Vista and later platforms.

C:\PCADev\FaultInjector>ifimp -f 192.168.15.107

Enumerating 3 Filter Modules:
Characteristics...: NDIS 6.0 Modifying Mandatory
IfIndex...........: 18
NetLuid...........: Index: 5; IfType: 0
Class.............: "ms_firewall_upper"
InstanceName......: "{43998418-5578-4337-BC9D-6AA9F6CF2CF4}-{B70D6460-3635-4D42-B866-B8AB1A24454C}-0000"

Characteristics...: NDIS 6.0 Modifying Optional
IfIndex...........: 17
NetLuid...........: Index: 3; IfType: 0
Class.............: "scheduler"
InstanceName......: "{43998418-5578-4337-BC9D-6AA9F6CF2CF4}-{B5F4D659-7DAA-4565-8E41-BE220ED60542}-0000"

Characteristics...: NDIS 6.0 Modifying Mandatory
IfIndex...........: 16
NetLuid...........: Index: 2; IfType: 0
Class.............: "diagnostic"
InstanceName......: "{43998418-5578-4337-BC9D-6AA9F6CF2CF4}-{0294AD45-8E86-4F6A-8A22-2EE10888F390}-0000"


The "diagnostic" filter with GUID {0294AD45-8E86-4F6A-8A22-2EE10888F390} is the fault injector filter. In this case it is layered immediately above the NIC miniport.

Quirks and Limitations

Here are a few "quirks" and limitations in the current impairment generator driver:

  • ICMP Impairments - These are limited to ICMP_ECHO and ICMP_ECHOREPLY.
  • Delay of Resource Limited Packets - Currently when the driver encounters a packet that has resource limitations (cannot be pended...) it does not delay the packet.
  • NDIS Task Offload - The driver disables NDIS checksum offloads for NDIS 5. NDIS 6 offload is not disabled.
  • System Timer Resolution - In order to support packet delay the driver sets the system timer resolution to 1 millisecond.
  • Reboot - Impairment settings are not persistent across reboots.

Caveat Emptor

This is an early release of this product. The IPv4 functionality has been tested fairly thoroughly.  However, the IPv6 functionality has seen only limited testing.

If you find problems or have suggestions for improvement if this product, please let me know.

In addition, if you have a requirement for a customized version of this driver (e.g., editing different fields or headers...) please let me know. PCAUSA can provide customized versions of this driver under contract if the requirements are practical.

support@pcausa.com

Download Sample Executables

You can download sample executables for evaluation and your own personal use subject to these limitations:

  • The evaluation executables are provided as-is and have no warranty.
  • You may not redistribute the PCAUSA the sample executables in any way.

insert product-specific instructions here...

Additional Documentation

Reference additional product documentation here...

Other Information

Licensing

The samples are licensed intellectual property of PCAUSA. However, if you purchase a PCAUSA sample driver product they are provided with a royalty-free license that is intended to allow customers to derive their own products using all or parts of the samples. The royalty-free license applies strictly to the distribution of product in binary (executable) form; there are quite naturally restrictions on distribution of sample source code.

 You can view the PCAUSA License here.

Price List and Ordering Information

Press the button below for Online Ordering and other Purchase Information.



Release Notes

Version Date Notes
V1.00.00.13 November 16, 2010 Increased packet delay limit from 100 milliseconds to 500 milliseconds per non-customer request. Use large delays with caution and report any problems that may be encountered with this feature.
V1.00.00.12 August 12, 2010 Increased size of buffer used for binding enumeration
V1.00.00.11 August 8, 2010 1.) Fixed nasty bug that occurred under heavy receive stress testing of the NDIS 6 driver. Driver did not properly undo modifications immediately when receiving resource-limited packets.
2.) NDIS 6 driver no longer disables NDIS checksum offload.
V1.00.00.10 August 5, 2010 Added NDIS 5 driver for Windows XP and Windows Server 2003.
V1.00.00.09 August 3, 2010 Added "-r" option to specify remote host for impairments. Only packets flowing between the local host and the specific remote host will be impaired if this option is used.
V1.00.00.08 July 30, 2010 Fixed uninitialized variable bug which could set TTL/Hop Count to random value and break connectivity.
V1.00.00.07 July 28, 2010 Eliminated use of EtherType 0xdead when dropping packets.
V1.00.00.06 July 23, 2010 Initial release of NDIS Interface Impairment Generator.

Detailed Release Notes...