NAME

iftest − interface testing utility

SYNOPSIS

iftest [-delvV] [-c packet_count] [-m {tx|rx|dx}] [-p profile_value] [-q bind_sap] [-r seed_value] [-s packet_size] [-x pattern] [destination] devname

DESCRIPTION

The iftest utility is a dual purpose interface tester designed to operate over DLPI (Data Link Provider Interface) V2.0 STREAMS drivers.  Generally, the user invokes two iftest applications, one on the local node and the second on a remote node.  The first purpose of iftest is as a driver data path confidence tester.  The user verifies that data may travel from the local iftest (sender), through the driver corresponding to devname, over the media, through the remote driver corresponding to destination, and finally to the remote iftest (responder).  This mode of operation (known as debug mode) is iftest’s default operation mode.  The user has complete control over packet size, packet content, number of packets transmitted, and various utility features, such as randomization of packet lengths during transmission and whether data verification is done on packet reception.  It is possible to have multiple senders sending to the same responder.  Each must use the same DLSAP (see -q option).  The user may also test the loopback path in the driver, in which case only a single iftest is invoked (see -e option and EXAMPLES).  The second purpose of iftest is as a driver performance tester.  This mode of operation is known as measurement mode.  iftest is able to test the one-way transmission rate of a local node, the one-way reception rate of a remote node, and the two-way transmission/reception rate of a local/remote pair.  See the -m option for a detailed description of the three measurement mode tests.  Unlike debug mode, it is not possible to have multiple senders sending to the same responder.  It is possible to set up multiple sender/responder pairs though (see EXAMPLES).  As with debug mode, the user may also calculate the loopback performance of a driver (see dx mode under -m).  The devname parameter, the only mandatory command line argument, specifies the filename of a DLPI driver’s device node.  The destination parameter is used only by the sender.  If destination is not present on the command line, iftest assumes it is a responder.  destination may be a hostname, an IP address, or a Physical address.  To use a hostname or an IP address, the TCP/IP service must be in operation.  A hostname must be in hosts(4N).  In addition, iftest uses ARP to convert a final IP address into a Physical address.  If no ARP entry exists for the IP address, iftest will display an error message to stderr and terminate.  A user can quickly force an ARP entry by using ping hostname.  Then reissue the sender command line.  For iftest to properly parse a Physical address, it is necessary to prefix the address with "0h".  The address must be in hexadecimal.  Either upper or lower case may be used for the digits A through F.  Upon completion of either a debug test or a measurement test, a sender application will clean after itself, display mode dependent data, and terminate.  Responder applications do not self-terminate since the user might want to do more debug or do another measurement.  To terminate a responder, the user must issue an interrupt to the process (for example, hitting the <BREAK> key).  The responder will then clean up after itself, display mode dependent data, and terminate.  Both a sender and a responder may be terminated early by use of an interrupt.  Although killing iftest (via a kill signal as opposed to an interrupt signal) will probably cause iftest to clean up properly (close file descriptors, free memory, free up minor devices in driver, etc.), this is not the recommended way of terminating iftest.  The kill technique assumes current UNIX behavior and assumes the driver properly frees resources associated with minor devices (such as DLSAPs) upon close.  Mode dependent data is displayed to stdout.  The mode dependent data displayed for debug mode is the number of packets received.  For a sender this is typically 0, although it should be non-zero if the responder is echoing packets.  The responder displays the cumulative total number of packets received from all sender sources.  For measurement mode, the sender displays the resulting statistics.  See end of -m option for a description.  A responder in measurement mode displays nothing before termination. 

OPTIONS

The user may issue the following options on the iftest command line:

-d Display data contents of packets.  A sender iftest displays to stdout the contents of a transmit data packet once, just before the first transmission.  A responder displays the contents of every packet received.  A sender receiving echoed packets from a responder also displays every received packet.  -d is valid in debug mode only. 

-e Echo data back to sender.  This option is valid only on a responder iftest command line.  Causes the responder to echo (retransmit) any received data packet back to the sender iftest.  This option functions even if the responder is receiving packets from multiple sender applications.  Note that a data packet is reflected exactly as it is received.  This option may be used to set up sender data verification (see -V option).  Although -e is not valid on a sender, a sender can still test loopback (i.e., looping the packet within the driver without going out to the media) by specifying devname’s own Physical address in the destination.  This of course assumes the device supports loopback.  -e is valid in debug mode only. 

-l Transmit data packets forever.  This option is valid only on a sender iftest command line.  Causes the sender to transmit data packets forever, thus ignoring the default packet count, until the user generates an interrupt signal.  iftest fails if both -l and -c (packet count) are specified.  -l is valid in debug mode only. 

-v Verbose mode.  Causes iftest to display additional information to stdout.  This option may be specified more than once, each additional -v increasing the verbose level by one.  Each level also displays information from the preceeding levels.  The levels are: Level 1 displays the results of all device open, DLPI bind, DLPI unbind, and device close operations. Level 2 displays packet transmission/reception information, the format dependent on the operation mode.  If in debug mode, level 2 displays a "!" character for every packet transmitted and a "." character for every packet received.  If in measurement mode, level 2 displays an update counter to the screen for every 5000 packets sent (or received).  The counter counts down for a sender, starting at 7 and ending at 0.  The counter counts up for a responder, starting at 1 and (theoretically) ending at 8.  The counter display restarts during each test iteration. Level 3 displays DLPI requests for and responses to the bind, info, and unbind primitives.  In addition, if in measurement mode, level 3 displays algorithm debug information.  Level 3 also displays the Physical address corresponding to a hostname or IP address destination entered on the command line. 

-V Verify received data packets.  This option causes a responder iftest (or a sender if the responder has the -e option enabled) to verify the size and contents of all data packets received.  A sender/responder pair may both have this option on, although it is not required.  If the size of the data packet received does not agree with the size that was placed into the first longword of the packet, then iftest displays the following to stderr: iftest: Verify Error, TX data size = XX, RX data size = YY where XX is the packet size obtained from the first longword of the packet and YY is the actual size of the packet received from STREAMS.  Note that if the packet_size specified on the command line is less than a longword, the sender cannot place the size into the first longword.  Therefore, this verification check does not occur.  If the sender is doing packet verification and if the user did not specify -r (randomize packet size), the sender also verifies the received data size versus the original packet size sent to the responder.  If the two sizes do not match, the sender displays the following to stderr: iftest: Verify Error, TX data size = XX, echoed RX data size = YY where XX is the packet size originally sent to the responder and YY is the actual size of the packet received from STREAMS.  The contents of the received data packet are verified against the default data pattern, or against the pattern specified with the -x option.  Note that the same -x pattern must be specified on both sender and responder if doing packet verification.  If the data contents do not match the pattern, iftest displays the following to stderr: iftest: Verify Error, pattern mismatch at data offset = XX where XX is the offset from the beginning of the data packet where the mismatch occurred (the first byte is offset 0).  If one of the three above errors occurs, iftest also displays the contents of the data packet to stderr in the same fashion as -d.  iftest does not terminate after a verify error.  It continues to receive (and/or send) packets and verify them.  -V is valid in debug mode only. 

-c packet_count
Number of data packets to transmit.  This option is valid only on a sender iftest command line.  If not specified, a sender transmits 1000 packets.  iftest treats this value as an unsigned long.  iftest fails if both -c and -l (transmit forever) are specified.  -c is valid in debug mode only. 

-m {tx|rx|dx}
Measurement mode.  Changes the operation mode of iftest so that various transmission statistics may be gathered.  If -m is not specified, iftest runs in debug mode.  The different test modes are described below, both in text and graphics: Specifying tx mode causes a sender iftest to calculate the maximum packet transmission rate over the local driver in question.  This rate includes the amount of time necessary to send the packet to the driver, and for the driver to send the packet to the transmit hardware.  The rate does not reflect whether the data ever entered onto the media or actually arrived at a responder iftest.  Technically, the user need not even invoke a responder.  It is optional. 

Specifying rx mode causes a sender iftest to calculate the maximum packet reception rate of the remote responder iftest.  This rate includes the amount of time necessary to send the packet to the local driver, transmit the packet over the media, receive the packet in the remote driver, and receive the packet from the driver in the responder iftest.  Note that since transmission at the data link layer is not guaranteed, we have assumed an acceptable loss of 0.75% (75 in 10,000) packets.  The algorithm for a successful test assumes any packets lost beyond this percentage must have been lost through software errors, which causes a new test to start at a slower rate. 

-p profile_value
Specify loop count for profiling.  This option changes the behavior of the measurement mode test on a sender iftest.  Instead of attempting to find the data rate, the sender will run through a single test iteration using the delay count specified.  iftest treats this count as an unsigned long value.  The primary purpose of this option is to do profiling of the utility and/or system during the single test iteration.  Under normal rx and dx mode operation, profiling is useless if iftest requires multiple test iterations.  For accurate profiling information, the user wants only the iteration that was successul.  To use this option, take the Introduced Latency value returned from a previous -m test (which represents the delay loop count used during the lowest-time test iteration), and use that as the profile_value argument.  This option may be used in tx mode.  This option may not be used in debug mode.  Only a sender may specify -p. 

-q bind_sap
Alternate DLSAP.  Causes iftest to use this DLSAP to bind to the driver with.  If -q is not specified, iftest uses 0xaeae.  iftest treats this value as a hexidecimal long word.  Both a sender and responder must use the same DLSAP to communicate with each other. 

-r seed_value
Randomize packet size.  This option causes a sender iftest to send a pseudo-random packet size during each transmit.  The -r argument is the seed value used to prime the srand funtion (see rand(3C)).  iftest treats this value as an unsigned long.  iftest uses rand to generate a pseudo-random packet size between the minimum DLSDU allowed by the driver and the maximum packet size (see -s option).  -r may be specified in any operation mode, but only on a sender’s command line.  If using -r in measurement mode, note that whatever seed_value the user chooses, the exact same value must be used from one test to the next to generate the same random sequence.  If the same seed_value is not used, a different data rate may result since the transmitted packets were of a different size. 

-s packet_size
Specify transmit packet size.  Causes the sender iftest to send packets of length packet_size bytes.  iftest treats this value as an unsigned long.  If not specified, iftest sends 1024-byte packets (1K) or the maximum allowed over the driver, whichever is smaller.  packet_size should, but need not, be less than or equal to the maximum number of bytes that may be transmitted by the driver, and greater than or equal to the minimum number of bytes that may be transmitted by the driver.  If packet_size is not within the DLSDU (Data Link Service Data Unit) size boundaries, iftest prints a warning message to stderr, but allows the attempt to take place.  packet_size must be at least 4 bytes in measurement mode.  -s is not valid on a responder command line. 

-x pattern
Specify transmit data pattern.  This option tells a sender iftest the data pattern to place into the contents of the packet to transmit.  This option is typically, though not necessarily, used with the -V option on the responder.  If this is the case, the responder must also be invoked with the same pattern on its command line.  The pattern is read in as a character string.  A responder that has -x in its command line must also have -V specified (note the reverse is not mandatory).  When verifying data, it is assumed that the data pattern is repeated after the end of the pattern.  For instance, a data pattern of "1234" means "123412341234..." until the end of the packet is reached.  If -x is not specified, iftest will use the default pattern "hoser" during transmission and reception verification. 

EXAMPLES

Most examples below show two command lines.  The first line is for the sender, the second line is for the responder.  The responder must be started before the sender to receive all packets.  Examples with but a single command line are for doing sender loopback testing. 

iftest 0h000077028d05 /dev/e1x7_c0
iftest /dev/m376_c0

The above commands invoke the default action of iftest.  The commands set up a debug mode test between two separate (remote) nodes.  The sender and responder both use the default DLSAP 0xaeae.  The sender application transmits 1000 (default) data packets over the (Ethernet) driver corresponding to the device /dev/e1x7_c0.  The packets contain 1024 bytes (default) of data.  The destination of the packets is the (Ethernet) driver residing at address 0x000077028d05.  The responder receives the data over the (Ethernet) driver corresponding to device /dev/m376_c0. 

iftest -q 1818 -x hELLo 0h000077028d05 /dev/e1x7_c0
iftest -V -q 1818 -x hELLo /dev/m376_c0

The above commands set up a debug mode test between two separate (remote) nodes.  The sender and responder both use DLSAP 0x1818 instead of the default.  The sender application transmits 1000 (default) data packets over the (Ethernet) driver to Physical address 0x000077028d05.  The packets contain 1024 bytes (default) of data.  The responder receives the data over the (Ethernet) driver, and verifies the data packets as they arrive using the data pattern "hELLohELLo...". 

iftest -dlvv 144.191.22.127 /dev/e1x7_c0
iftest -evv /dev/m376_c0

The above commands set up a debug mode test between two separate (remote) nodes.  The sender and responder both use DLSAP 0xaeae (default).  The sender application continually transmits packets over the device specified to the driver corresponding to the IP address 144.191.22.127.  The sender will not stop transmitting until interrupted.  The packets contain 1024 bytes (default) of data, the pattern being "hoserhoser...".  The responder echoes each data packet back to the sender.  The sender displays the contents of the transmit packet once before the first transmission.  The sender also displays the contents of each received data packet.  Both sender and responder display Level 2 debug information during execution (display open, bind, unbind, and close results and packet transmission/reception). 

iftest -V -c 100 -r 33 -s 4096 jupiter /dev/m385_c0
iftest -eV /dev/m385_c0

The above commands set up a debug mode test between two separate (remote) nodes.  The sender application transmits 100 packets over the (FDDI) device specified to the driver corresponding to the hostname jupiter.  The packets contain a pseudo-random amount of data, varying between the minimum DLSDU and 4096 bytes.  The data contents are the default.  The responder does data verification on each packet, then echoes the packet back to the sender.  The sender also does data verification on each packet received. 

iftest -l -r 5000 -s 1500 0h08003e21ea8e /dev/e1x7_c0

The above command sets up a debug mode loopback test over an Ethernet driver.  The sender application continually transmits packets to the device.  We have specified a desintation of 0h08003e21ea8e, which corresponds to the device itself.  Assuming the driver corresponding to /dev/e1x7_c0 supports loopback, it reflects each packet immediately.  The packets contain a pseudo-random amount of data, varying between 46 bytes (minimum DLSDU for Ethernet) and 1500 bytes.  The sender continually transmits (and receives) packets until interrupted by the user. 

iftest -vv -m rx godzilla /dev/e1x7_c0
iftest -vv -m rx /dev/m376_c0

The above commands set up a measurement mode rx test between two separate (remote) nodes.  The sender application finds the fastest reception rate of the responder using a packet size of 1024 bytes (default).  We display additional debug information at Level 2 so that we have confidence that the test is not hung. 

iftest -vv -m rx -p 3321 godzilla /dev/e1x7_c0
iftest -vv -m rx /dev/m376_c0

Assuming that the Introduced Latency displayed after the preceeding example test completed showed a value of 3321, the above commands duplicate the last test iteration so that the user may do utility/system profiling.  The sender terminates after a single iteration. 

iftest -m tx -s 100 godzilla /dev/e1x7_c0
iftest -m tx /dev/m376_c0

The above commands set up a measurement mode tx test between two separate (remote) nodes.  The sender application finds the fastest transmission rate over the local driver using a packet size of 100 bytes.  Technically, the responder is not necessary here.  We started one anyway. 

iftest -m dx -s 1500 0h08003e21ea8e /dev/e1x7_c0

The above command sets up a measurement mode dx test that finds the fastest loopback rate for 1500-byte length packets over the local (Ethernet) driver. 

iftest -vvv -m dx godzilla /dev/e1x7_c0
iftest -vvv -m dx godzilla -q afaf /dev/m376_c1
iftest -vvv -m dx /dev/m376_c0
iftest -vvv -m dx -q afaf /dev/m376_c0

The above commands set up a measurement mode dx test between three separate (remote) nodes.  There are two sender nodes sending to a single responder node.  We still need two responders operating on the node though.  One responder accepts packets for DLSAP 0xaeae, the other for DLSAP 0xafaf.  This test attempts to find the maximum full-duplex rate when two senders send to the same node (see NOTES below).  We display additional debug information at Level 3 to see how the algorithm operates under these conditions. 

SEE ALSO

ping(1M),
rand(3C),
hosts(4N),
e1x7(7), m376(7), m385(7), ppp(7), slip(7)

DIAGNOSTICS

If iftest terminates normally, it displays mode dependent data as discussed in the DESCRIPTION section then exits with a 0 status.  If iftest does not terminate normally, it displays an error message to stderr and returns a non-zero exit status. 

NOTES

The algorithm used by iftest during measurement mode has inherent knowledge of the Packet Loss vs. Introduced Latency curve and the Test Time vs. Introduced Latency curve.  This makes iftest less portable since a different operating system and/or STREAMS might cause different system performance curves.  The user should analyze the algorithm using a Level 3 verbose level if using iftest on a system other than Motorola’s SVR4 Multi-Processor UNIX with AT&T STREAMS.  If attempting to use measurement mode with more than a single sender/responder pair, the resulting data rates will vary widely from test to test unless the sender/responder-pair systems are homogeneous.  For example, if two senders on different systems are sending to two responders on a single system, then the two sender systems must be using similar speed hardware and drivers, have similar cache sizes, and must have similar system loads.  The reason for this is because if one sender is much faster than another sender, the faster sender will most likely converge on its data rate faster than the slower one.  This will force the slower sender to have an unusually high initial Introduced Latency.  It will also completely change the driver performance of the responder since the faster sender will finish much sooner, thus allowing more bandwidth to the slower sender.  The algorithm used in measurement mode will never converge if the hardware and/or media cause a transmission error rate of over 0.75% failures (75 failures every 10,000 packets). Since iftest uses ARP to match an IP address to a Physical address, a user cannot specify localhost or a local interface name in the destination command line argument.  There is no way for ARP to know of such interface mappings.  The user must use the Physical address for loopback testing.