NDIS Interface Impairment Generator Sample
NDIS 5 IM & NDIS 6 LWF
Windows XP - Windows 7

NDIS Interface Impairment Generator

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

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.

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:

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.

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:

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 Filter 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.

NOTE: 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:

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.

tdivine AT PCAUSA DOT com

Intended Audience

Download Sample Executables

You can download the NDIS Interface Impairment Generator sample executables for evaluation and your own personal use subject to these limitations:

The ZIP file containing sample executables include:

Download NDIS Impairment Generator Sample Executables for Windows XP through Windows 7 (x86 and x64).
V1.00.00.12, August 12, 2010

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.

The complete license can be found here.

See the PCAUSA Ordering page.

[Detailed Release Notes]

PCAUSA Home · Privacy Statement · Products · Ordering · Support · Utilities · Resources
Mailing Lists  · PCAUSA Newsletter · PCAUSA Discussion List
 

Rawether for Windows and WinDis 32 are trademarks of Printing Communications Assoc., Inc. (PCAUSA)
Microsoft, MS, Windows, Windows 95, Windows 98, Windows Millennium, Windows 2000, and Win32 are registered trademarks and Visual C++ and Windows NT are trademarks of the Microsoft Corporation.
Send mail to webmaster@pcausa.com with questions or comments about this web site.
Copyright © 1996-2010 Printing Communications Assoc., Inc. (PCAUSA)
Last modified: February 04, 2010