OpenSS7 NETPERF Utility

OpenSS7 NETPERF Utility Installation and Reference Manual

About This Manual

This is Edition 6, last updated 2007-06-24, of The OpenSS7 NETPERF Utility Installation and Reference Manual, for Version 2.3 release 6 of the OpenSS7 NETPERF Utility package.

Preface

Notice

This version of netperf is a version modified by The OpenSS7 Project to support network performance testing and benchmarking of the OpenSS7 Linux Kernel Native and STREAMS implementations of Stream Control Transmission Protocol (SCTP) as described in RFC 2960. To support testing of the emerging SCTP protocol, specific stream, request/response and connect/close tests were added to test the SCTP protocol in a fashion similar to Transmission Control Protocol (TCP). The objective of retaining as much compatibility as possible to the TCP tests was to provide a basis for comparison between TCP and SCTP implementations on the Linux and HP-UX operating systems.

In addition, XTI tests have been enhanced and are used to test the OpenSS7 STREAMS XTI INET implementation, See OpenSS7 STREAMS INET Driver. The OpenSS7 STREAMS INET implementation is an implementation XTI STREAMS over Sockets for the Linux operating system. Tests in the XTI API test group compared against equivalent tests in the Sockets API test group provide an indication of the overheads introduced by running XTI over Sockets. The OpenSS7 STREAMS INET driver also provides XTI over Sockets for the Linux Native SCTP implementation and comparisons between the XTI over Sockets and pure STREAMS approaches to SCTP can be made.

Abstract

This manual provides a Installation and Reference Manual for OpenSS7 NETPERF Utility.

Objective

The objective of this manual is to provide a guide for the STREAMS programmer when developing STREAMS modules, drivers and application programs for OpenSS7 NETPERF Utility.

This guide provides information to developers on the use of the STREAMS mechanism at user and kernel levels.

STREAMS was incorporated in UNIX System V Release 3 to augment the character input/output (I/O) mechanism and to support development of communication services.

STREAMS provides developers with integral functions, a set of utility routines, and facilities that expedite software design and implementation.

Intent

The intent of this manual is to act as an introductory guide to the STREAMS programmer. It is intended to be read alone and is not intended to replace or supplement the OpenSS7 NETPERF Utility manual pages. For a reference for writing code, the manual pages (see STREAMS(9)) provide a better reference to the programmer. Although this describes the features of the OpenSS7 NETPERF Utility package, OpenSS7 Corporation is under no obligation to provide any software, system or feature listed herein.

Audience

This manual is intended for a highly technical audience. The reader should already be familiar with Linux kernel programming, the Linux file system, character devices, driver input and output, interrupts, software interrupt handling, scheduling, process contexts, multiprocessor locks, etc.

The guide is intended for network and systems programmers, who use the STREAMS mechanism at user and kernel levels for Linux and UNIX system communication services.

Readers of the guide are expected to possess prior knowledge of the Linux and UNIX system, programming, networking, and data communication.

Revisions

Take care that you are working with a current version of this manual: you will not be notified of updates. To ensure that you are working with a current version, contact the Author, or check The OpenSS7 Project website for a current version.

A current version of this manual is normally distributed with the OpenSS7 NETPERF Utility package, netperf-2.3.6.¹

Version Control

     
     netperf.texi,v
     Revision 0.9.2.15  2007/02/28 06:30:21  brian
     - updates and corrections, #ifdef instead of #if
     
     Revision 0.9.2.14  2006/09/18 01:06:18  brian
     - updated manuals and release texi docs
     
     Revision 0.9.2.13  2006/08/28 10:46:52  brian
     - correction
     
     Revision 0.9.2.12  2006/08/28 10:32:43  brian
     - updated references
     
     Revision 0.9.2.11  2006/08/27 12:26:32  brian
     - finalizing auto release files
     
     Revision 0.9.2.10  2006/08/26 18:31:36  brian
     - handle long urls
     
     Revision 0.9.2.9  2006/08/26 09:16:18  brian
     - better release file generation
     
     Revision 0.9.2.8  2006/08/23 11:00:25  brian
     - added preface, corrections and updates for release
     
     Revision 0.9.2.6  2006-03-22 03:01:58 -0700  brian
     - added makefile target index
     
     Revision 0.9.2.5  2006-03-03 04:56:43 -0700  brian
     - 64-bit compatibility
     
     Revision 0.9.2.4  2005-07-08 07:15:37 -0600  brian
     - updates to documentation
     
     Revision 0.9.2.3  2005-07-01 01:29:37 -0600  brian
     - updates for LE2005 build
     
     Revision 0.9.2.2  2005-06-24 07:38:58 -0600  brian
     - added troubleshooting section to manuals
     
     Revision 0.9.2.1  2005-05-30 02:44:01 -0600  brian
     - moved documentation for RHEL4 build
     
     Revision 0.9  2005-05-30 02:44:01 -0600  brian
     file netperf.texi was initially added on branch HP.
     

ISO 9000 Compliance

Only the TeX, texinfo, or roff source for this manual is controlled. An opaque (printed, postscript or portable document format) version of this manual is an UNCONTROLLED VERSION.

Disclaimer

OpenSS7 Corporation disclaims all warranties with regard to this documentation including all implied warranties of merchantability, fitness for a particular purpose, non-infringement, or title; that the contents of the manual are suitable for any purpose, or that the implementation of such contents will not infringe on any third party patents, copyrights, trademarks or other rights. In no event shall OpenSS7 Corporation be liable for any direct, indirect, special or consequential damages or any damages whatsoever resulting from loss of use, data or profits, whether in an action of contract, negligence or other tortious action, arising out of or in connection with any use of this manual or the performance or implementation of the contents thereof.

OpenSS7 Corporation reserves the right to revise this software and documentation for any reason, including but not limited to, conformity with standards promulgated by various agencies, utilization of advances in the state of the technical arts, or the reflection of changes in the design of any techniques, or procedures embodied, described, or referred to herein. OpenSS7 Corporation is under no obligation to provide any feature listed herein.

U.S. Government Restricted Rights

If you are licensing this Software on behalf of the U.S. Government ("Government"), the following provisions apply to you. If the Software is supplied by the Department of Defense ("DoD"), it is classified as "Commercial Computer Software" under paragraph 252.227-7014 of the DoD Supplement to the Federal Acquisition Regulations ("DFARS") (or any successor regulations) and the Government is acquiring only the license rights granted herein (the license rights customarily provided to non-Government users). If the Software is supplied to any unit or agency of the Government other than DoD, it is classified as "Restricted Computer Software" and the Government's rights in the Software are defined in paragraph 52.227-19 of the Federal Acquisition Regulations ("FAR") (or any successor regulations) or, in the cases of NASA, in paragraph 18.52.227-86 of the NASA Supplement to the FAR (or any successor regulations).

Acknowledgements

As with most open source projects, this project would not have been possible without the valiant efforts and productive software of the Free Software Foundation and the Linux Kernel Community.

Sponsors

Funding for completion of the OpenSS7 OpenSS7 NETPERF Utility package was provided in part by:

Additional funding for The OpenSS7 Project was provided by:

Contributors

The primary contributor to the OpenSS7 OpenSS7 NETPERF Utility package is Brian F. G. Bidulock. The following is a list of significant contributors to The OpenSS7 Project:

Authors

The authors of the OpenSS7 OpenSS7 NETPERF Utility package include:

See Author Index, for a complete listing and cross-index of authors to sections of this manual.

Maintainer

The maintainer of the OpenSS7 OpenSS7 NETPERF Utility package is:

Please send bug reports to bugs@openss7.org using the send-pr script included in the package, only after reading the BUGS file in the release, or See Problem Reports.

Web Resources

The OpenSS7 Project provides a website dedicated to the software packages released by the OpenSS7 Project.

Bug Reports

Please send bug reports to bugs@openss7.org using the send-pr script included in the OpenSS7 NETPERF Utility package, only after reading the BUGS file in the release, or See Problem Reports. You can access the OpenSS7 GNATS database directly via the web, however, the preferred method for sending new bug reports is via mail with the send-pr script.

Mailing Lists

The OpenSS7 Project provides a number of general discussion Mailing Lists for discussion concerning the OpenSS7 OpenSS7 NETPERF Utility package as well as other packages released by The OpenSS7 Project.

These are mailman mailing lists and so have convenient web interfaces for subscribers to control their settings. See http://www.openss7.org/mailinglist.html.

The mailing lists are as follows:

openss7

The openss7 mailing list is for general enquiries, information exchange and announcements regarding the OpenSS7 Project. This is our original mailing list and takes the highest amount of traffic.

openss7-announce

The openss7-announce mailing list is for announcements related to the OpenSS7 Project. This list will accept announcements posted by subscribers. Subscribe to this list if you are interested in announcements from the OpenSS7 Project, subscribers and sponsors, related to the OpenSS7 Project or STREAMS, SS7, SIGTRAN or SCTP in general.

openss7-cvs

The openss7-cvs mailing list is for automatic CVS log reporting. You must get permission of the owner to subscribe to this list. Subscribers are not allowed to post to this list, this is merely for distributing notification of changes to the CVS repository.h

openss7-develop

The openss7-develop mailing list is for email exchange related to the development projects under the OpenSS7 Project. This includes development requests, proposals, requests for comment or proposal. Subscribe to this list if you are interested in ongoing development details regarding the OpenSS7 Project.

openss7-test

The openss7-test mailing list is for email exchange related to the testing of code under the OpenSS7 Project. This specifically relates to conformance testing, verification testing, interoperability testing and beta testing. Subscribe to this list if you are interested in participating in and receiving ongoing details of test activities under the OpenSS7 Project.

openss7-bugs

The openss7-bugs mailing list is specifically tailored to bug tracking. The mailing list takes a feed from the OpenSS7 GNATS bug tracking system and accepts posting of responses to bug reports, tracking and resolution. Subscribe to this list if you are interested in receiving detailed OpenSS7 release code bug tracking information. This list is not archived; for historical information on problem reports, see our GNATS databases.

openss7-updates

The openss7-updates mailing list provides updates on OpenSS7 Project code releases and ongoing activities. Subscribers are not allowed to post to this list; this list is for official OpenSS7 Project announcements only. Subscribe to this list if you are interested in receiving updates concerning official releases and activities of the OpenSS7 Project.

openss7-streams

The openss7-streams mailing list is for email exchange related to the STREAMS development projects under the OpenSS7 Project. This includes development requests, proposals, requests for comment or proposal. Subscribe to this list if you are interested in ongoing development details regarding the OpenSS7 Project STREAMS components.

linux-streams

The linux-streams mailing list is for mail exchange related to Linux Fast-STREAMS or Linux STREAMS. This includes patches, development requests, proposals, requests for comment or proposal. Subscribe to this list if you are interested in ongoing development details regarding the STREAMS for Linux components. This is the the new (September 2006) home of the linux-streams list formerly of <gsyc.escet.urjc.es>.

Spam

To avoid spam being sent to the members of the OpenSS7 mailing list(s), we have blocked mail from non-subscribers. Please subscribe to the mailing list before attempting to post to them. (Attempts to post when not subscribed get bounced.)

As an additional measure against spam, subscriber lists for all OpenSS7 mailing lists are not accessible to non-subscribers; for most lists subscriber lists are only accessible to the list administrator. This keeps your mailing address from being picked off our website by bulk mailers.

Acceptable Use Policy

It is acceptable to post professional and courteous messages regarding the OpenSS7 package or any general information or questions concerning STREAMS, SS7, SIGTRAN, SCTP or telecommunications applications in general.

Large Attachments

The mailing list is blocked from messages of greater than 40k. If you have attachments (patches, test programs, etc.) and you mail them to the list, it will bounce to the list administrator. If you are interested in making your patches, test programs, test results or other large attachments available to the members of the mailing list, state in the message that you would like them posted and the list administrator will place them in the mail archives.

Quick Start Guide

OpenSS7 NETPERF Utility

Package netperf-2.3.6 was released under GPLv2 2007-06-24.

Netperf is a general purpose tool for benchmarking bandwidth and performance of the Internet Protocol suite. The OpenSS7 Modified OpenSS7 NETPERF Utility package is an OpenSS7 Project release of the of the Hewlett-Packard netperf package configured to run with OpenSS7 STREAMS SCTP (Stream Control Transmission Protocol) and the OpenSS7 STREAMS XNS, XTI/TLI and INET packages.

The OpenSS7 NETPERF Utility package provide primarily the netperf(1) and netserver(8), C Language programs that act as Netperf client or server for testing connections and networking. The netserver(8) program is executed on one host acting as a server, and then netperf(1) is executed on another host acting in client mode. Characteristics of the connection or association can be altered when formed. Reporting formats and sample intervals can also be altered when the connection or association is formed. Users executing netperf(1) do not need to have shell access to the netserver(8) host.

This is a fork of the Netperf package released by Hewlett-Packard modified by the OpenSS7 Project for use with OpenSS7 STREAMS XNS, XTI/TLI, INET and SCTP packages. This OpenSS7 release of the package is based on the Netperf-2.3 release from Hewlett-Packard.

Modifications to the package are derived from the OpenSS7 STREAMS XNS, XTI/TLI, INET and SCTP implementations and are release under the GNU General Public License (GPL) Version 2. The Netperf tool itself is licensed under specific terms by Hewlett-Packard. Please see file LICENSES for the Hewlett-Packard Netperf copyright notices and licensing restrictions. The Netperf tool is

Copyright © 1993, 1994, 1995 Hewlett-Packard Company
All Rights Reserved

See the Hewlett-Packard License in the LICENSES file for complete details.

Please note that this modified version of the Netperf package is not endorsed by Hewlett-Packard in any way and that neither the original copyright holders nor OpenSS7 Corporation will take any responsibility in it.

This distribution is only currently applicable to Linux 2.4 and 2.6 kernels and was targeted at ix86, x86_64, ppc and ppc64 architectures, but should build and install for other architectures as well.

Release

This is the netperf-2.3.6 package, released 2007-06-24. This `2.3.6' release, and the latest version, can be obtained from the download area of The OpenSS7 Project website using a command such as:

     $> wget http://www.openss7.org/tarballs/netperf-2.3.6.tar.bz2

The release is available as an autoconf(1) tarball, src.rpm or dsc, or as a set of binary rpms or debs. See the download page for the autoconf(1) tarballs, src.rpms or dscs. See the netperf package page for tarballs, source and binary packages.

Please see the NEWS file for release notes and history of user visible changes for the current version, and the ChangeLog file for a more detailed history of implementation changes. The TODO file lists features not yet implemented and other outstanding items.

Please see the INSTALL, INSTALL-netperf and README-make, files (or see Installation) for installation instructions.

When working from cvs(1) or git(1), please see the README-cvs, file (or see Downloading from CVS). An abbreviated installation procedure that works for most applications appears below.

This release of the package is published strictly under Version 2 of the GNU Public License which can be found in the file COPYING. Package specific licensing terms (if any) can be found in the file LICENSES. Please respect these licensing arrangements. If you are interested in different licensing terms, please contact the copyright holder, or OpenSS7 Corporation <sales@openss7.com>.

See README-alpha (if it exists) for alpha release information.

Prerequisites

The quickest and easiest way to ensure that all prerequisites are met is to download and install this package from within the OpenSS7 Master Package, openss7-0.9.2.F, instead of separately.

Prerequisites for the OpenSS7 NETPERF Utility package are as follows:

1. Linux distribution, somewhat Linux Standards Base compliant, with a 2.4 or 2.6 kernel and the appropriate tool chain for compiling out-of-tree kernel modules. Most recent Linux distributions are usable out of the box, but some development packages must be installed. For more information, see Compatibility.

   	− A fairly LSB compliant GNU/Linux distribution.2
   	− Linux 2.4 kernel (2.4.10 - 2.4.27), or
   	− Linux 2.6 kernel (2.6.3 - 2.6.21);
   	− glibc2 or better.
   	− GNU info (for info files).
   	− GNU groff (for man pages).3

(Note: If you acquired netperf a part of the OpenSS7 Master Package, then the dependencies listed below will already have been met by unpacking the master package.)

2. OpenSS7 Linux Fast-STREAMS, streams-0.9.2.3. ⁴
3. OpenSS7 STREAMS Compatibility Modules, strcompat-0.9.2.6.
4. OpenSS7 STREAMS XNS, strxns-0.9.2.6.
5. OpenSS7 STREAMS XTI/TLI, strxnet-0.9.2.11.
6. OpenSS7 STREAM Network Services Library, strnsl-0.9.2.3. (Optional.)
7. OpenSS7 STREAMS INET, strinet-0.9.2.6.
8. OpenSS7 STREAMS SCTP, strsctp-0.9.2.8.
9. OpenSS7 STREAMS Channels, striso-0.9.2.3.
10. OpenSS7 STREAMS ISO, striso-0.9.2.3.
11. OpenSS7 STREAMS ISDN, strisdn-0.9.2.3.
12. OpenSS7 STREAMS SS7, strss7-0.9a.7.
13. OpenSS7 STREAMS SIGTRAN, sigtran-0.9.2.3.
14. OpenSS7 STREAMS VoIP, strvoip-0.9.2.3.

When configuring and building multiple OpenSS7 Project release packages, place all of the source packages (unpacked tarballs) at the same directory level and all build directories at the same directory level (e.g. all source packages under /usr/src).

When installing packages that install as kernel modules, it is necessary to have the correct kernel development package installed. For the following distributions, use the following commands:

     Ubuntu:  $> apt-get install linux-headers
     Debian:  $> apt-get install kernel-headers
     Fedora:  $> yum install kernel-devel

You also need the same version of gcc(1) compiler with which the kernel was built. If it is not the default, add `CC=kgcc' on the line after `./configure', for example:

     $> ../netperf-2.3.6/configure CC='gcc-3.4'

Installation

The following commands will download, configure, build, check, install, validate, uninstall and remove the package:

     $> wget http://www.openss7.org/tarballs/netperf-2.3.6.tar.bz2
     $> tar -xjvf netperf-2.3.6.tar.bz2
     $> mkdir build
     $> pushd build
     $> ../netperf-2.3.6/configure --enable-autotest
     $> make
     $> make check
     $> sudo make install
     $> sudo make installcheck
     $> sudo make uninstall
     $> popd
     $> sudo rm -rf build
     $> rm -rf netperf-2.3.6
     $> rm -f netperf-2.3.6.tar.bz2

If you have problems, try building with the logging targets instead. If the make of a logging target fails, an automatic problem report will be generated that can be mailed to The OpenSS7 Project.⁵ Installation steps using the logging targets proceed as follows:

     $> wget http://www.openss7.org/tarballs/netperf-2.3.6.tar.bz2
     $> tar -xjvf netperf-2.3.6.tar.bz2
     $> mkdir build
     $> pushd build
     $> ../netperf-2.3.6/configure --enable-autotest
     $> make compile.log
     $> make check.log
     $> sudo make install.log
     $> sudo make installcheck.log
     $> sudo make uninstall.log
     $> popd
     $> sudo rm -rf build
     $> rm -rf netperf-2.3.6
     $> rm -f netperf-2.3.6.tar.bz2

See README-make for additional specialized make targets.

For custom applications, see the INSTALL and INSTALL-netperf files or the see Installation, as listed below. If you encounter troubles, see Troubleshooting, before issuing a bug report.

Brief Installation Instructions

The OpenSS7 NETPERF Utility package is available from the downloads area of The OpenSS7 Project website using a command such as:

     $> wget http://www.openss7.org/tarballs/netperf-2.3.6.tar.bz2

Unpack the tarball using a command such as:

     $> tar -xjvf netperf-2.3.6.tar.bz2

The tarball will unpack into the relative subdirectory named after the package name: netperf-2.3.6.

The package builds using the GNU autoconf utilities and the configure script. To build the package, we recommend using a separate build directory as follows:

     $> mkdir build
     $> cd build
     $> ../netperf-2.3.6/configure

In general, the package configures and builds without adding any special options to the configure script. For general options to the configure script, see the GNU INSTALL file in the distribution:

     $> less ../netperf-2.3.6/INSTALL

For specific options to the configure script, see the INSTALL-netperf file in the distribution, or simply execute the configure script with the --help option like so:

     $> ../netperf-2.3.6/configure --help

After configuring the package, the package can be compiled simply by issuing the `make' command:

     $> make

Some specialized makefile targets exists, see the README-make file in the distribution or simply invoke the `help' target like so:

     $> make help | less

After successfully building the package, the package can be checked by invoking the `check' make target like so:

     $> make check

After successfully checking the package, the package can be installed by invoking the `install' make target (as root) like so:

     $> sudo make install

The test suites that ship with the package can be invoked after the package has been installed by invoking the `installcheck' target. This target can either be invoked as root, or as a normal user, like so:

     $> make installcheck

(Note: you must add the --enable-autotest flag to configure, above for the test suites to be invoked with `make installcheck'.)

The package can be cleanly removed by invoking the `uninstall' target (as root):

     $> sudo make uninstall

Then the build directory and tarball can be simply removed:

     $> cd ..
     $> rm -rf build
     $> rm -rf netperf-2.3.6
     $> rm -f netperf-2.3.6.tar.bz2

Detailed Installation Instructions

More detailed installation instructions can be found in the Installation, contained in the distribution in `text', `info', `html' and `pdf' formats:

     $> cd ../netperf-2.3.6
     $> less doc/manual/netperf.txt
     $> lynx doc/manual/netperf.html
     $> info doc/manual/netperf.info
     $> xpdf doc/manual/netperf.pdf

The `text' version of the manual is always available in the MANUAL file in the release.

The current manual is also always available online from The OpenSS7 Project website at:

     $> lynx http://www.openss7.org/netperf_manual.html

1 Introduction

This manual documents the design, implementation, installation, operation and future development schedule of the OpenSS7 NETPERF Utility package.

1.1 Overview

This manual documents the design, implementation, installation, operation and future development of the OpenSS7 NETPERF Utility package.

Netperf is a benchmark that can be used to measure various aspects of networking performance. Its primary focus is on bulk data transfer and request/response performance using SCTP, TCP or UDP, the X/Open XTI/TLI XNS 5.2 interface and the Berkeley Sockets interface. There are optional tests available to measure the performance of DLPI, Unix Domain sockets and STREAMS, the Fore ATM API and the HP HiPPI LLA interface.

This tool is maintained and informally supported by the IND Networking Performance Team. It is NOT supported via any of the normal Hewlett-Packard support channels. You are free to make enhancements and modifications to this tool.

1.2 Organization of this Manual

This manual is organized (loosely) into several sections as follows:

We thank you in advance for your comments, and hope that you find this tool useful.

The maintainers of netperf.

"How fast is it? It's so fast, that ..." ;-)

1.3 Conventions and Definitions

This manual uses texinfo typographic conventions.

You may not be familiar with some of the conventions and definitions used by this manual. Generally, items of particular importance, command line options, and commands will be in boldface type. Filenames and command line items requiring user substitution will appear in italicized type.

A sizespec is a one or two item list passed with a command line option that can set the value of one or two netperf parameters. If you wish to set both parameters to separate values, items should be separated by a comma, for example: "parm1, parm2". If you wish to set the first parameter without altering the value of the second, you should follow the first item with a comma, for example: "parm1,". Likewise, precede the item with a comma if you wish to set only the second parameter, for example ",parm2". An item without a comma will set both parameters. This last mode is the one most frequently used.

Netperf has two types of command line options. The first are global command line options. They are essentially any option that is not tied to a particular test, or group of tests. An example of a global command line option is the test type. The second options are test specific options. These are options that are only applicable to a particular test. An example of a test specific option would be the send socket buffer size for a TCP_STREAM test. Global command line options are specified first, test specific options second. They must be separated from each other by a "--" (two dashes). If you wish to give test specific options only, they must be preceded by "--".

For example:

     $ netperf -- -m 1024

2 Objective

3 Reference

3.1 Files

NETPERF installs the following utility programs in the system binary directory, /usr/sbin/:

sctp_stream_script

tcp_stream_script

udp_stream_script

sctp_rr_script

tcp_rr_script

udp_rr_script

sctp_range_script

tcp_range_script

snapshot_script

arr_script

packet_byte_script

netserver

NETPERF installs the following user programs in the user binary directory, /usr/bin/:

netperf

netperf_arr

netperf_packet_byte

netperf_sctp_range

netperf_sctp_rr

netperf_sctp_stream

netperf_snapshot

netperf_tcp_range

netperf_tcp_rr

netperf_tcp_stream

netperf_udp_range

netperf_udp_rr

netperf_udp_stream

NETPERF installs the following info files in the system info directory, /usr/share/info/:

netperf.info

netperf.info-1

netperf.info-2

These files contain this manual in GNU info format.

NETPERF installs the following manpage macros and reference database files in the system man directory, /usr/share/man/:⁶

netperf.macros

This file contains manual page macro definitions included by the manual pages included in the package.

netperf.refs

This file contains a reference database referenced by the manual pages included in the package.

NETPERF installs the following manual pages in the system man directory, /usr/share/man/man1/:

netperf.1

netperf_arr.1

netperf_packet_byte.1

netperf_sctp_range.1

netperf_sctp_rr.1

netperf_sctp_stream.1

netperf_snapshot.1

netperf_tcp_range.1

netperf_tcp_rr.1

netperf_tcp_stream.1

netperf_udp_range.1

netperf_udp_rr.1

netperf_udp_stream.1

NETPERF installs the following manual pages in the system man directory, /usr/share/man/man2/:

NETPERF installs the following manual pages in the system man directory, /usr/share/man/man3/:

NETPERF installs the following manual pages in the system man directory, /usr/share/man/man4/:

NETPERF installs the following manual pages in the system man directory, /usr/share/man/man5/:

netperf.5

manual page for the netperf(5) package.

NETPERF installs the following manual pages in the system man directory, /usr/share/man/man7/:

NETPERF installs the following manual pages in the system man directory, /usr/share/man/man8/:

sctp_range_script.8

sctp_rr_script.8

sctp_stream_script.8

tcp_range_script.8

tcp_rr_script.8

tcp_stream_script.8

udp_rr_script.8

udp_stream_script.8

snapshot_script.8

arr_script.8

packet_byte_script.8

netserver.8

3.2 Drivers

3.3 Modules

3.4 Libraries

3.5 Utilities

3.6 Development

4 Tests

4.1 Design

4.1.1 Design Basics

Netperf is designed around the basic client-server model. There are two executables – netperf and netserver. Generally you will only execute the netperf program – the netserver program will be invoked by the other system's inetd.

When you execute netperf, the first thing that happens is the establishment of a control connection to the remote system. This connection will be used to pass test configuration information and results to and from the remote system. Regardless of the type of test being run, the control connection will be a TCP connection using BSD sockets.

Once the control connection is up and the configuration information has been passed, a separate connection will be opened for the measurement itself using the APIs and protocols appropriate for the test. The test will be performed, and the results will be displayed.

Netperf places no traffic on the control connection while a test is in progress. Certain TCP options, such as SO_KEEPALIVE, if set as your system's default, may put packets out on the control connection.

4.1.2 CPU Utilization

CPU utilization is a frequently requested metric of networking performance. Unfortunately, it can also be one of the most difficult metrics to measure accurately. Netperf is designed to use one of several (perhaps platform dependent) CPU utilization measurement schemes. Depending on the CPU utilization measurement technique used, a unique single-letter code will be included in the CPU portion of the test banner for both the local and remote systems.

The default CPU measurement technique is based on the use of "loopers" which will sit in tight little loops consuming any CPU left over by the networking. This method is not without its added overhead, but wherever possible, card has been taken to keep that overhead to a minimum. If you would like to get an estimate of the overhead, run one test with CPU utilization, and one test without, and compare the throughputs. Use of loopers in measuring CPU utilization is indicated by the letter code "L".

NOTE: For accurate CPU utilization on MP systems, it is crucial that netperf and netserver know the number of processors on the system. For some systems (HP-UX) this can be determined programmatically. Other systems require the use of the "-n" global command line argument.

HP-UX 10.X offers a zero additional overhead, very accurate CPU utilization mechanism based on the pstat() system call. If you are compiling on HP-UX 10, you should replace the "-DUSE_LOOPER" in the makefile with "-DUSE_PSTAT" and recompile. When this method is being used, the letter code "T" will be displayed.

Other codes may be included in later versions of netperf. When the CPU utilization mechanism is unknown, either a "U" or a "?" will be displayed.

Great care should be exercised when looking at CPU utilization. Be certain you are familiar with the technique being used, and its implications. For example, a mechanism that is based solely on CPU charged to the netperf (netserver) process alone will likely under-report the real CPU utilization significantly. Much network processing takes place away from the user process context. Caveat Benchmarker!

4.1.3 Supported Interfaces

Sockets

BSD/POSIX Sockets Interface

XTI

X/Open Transport Interface (XTI/TLI) XNS 5.2 Interface

IPv6

BSD/POSIX IPv6 Sockets Interface

Unix

BSD/POSIX Unix Domain Sockets Interface

DLPI

X/Open XNS 5.2 Data Link Provider Interface (DLPI)

DNS

Directory Name Service

4.1.4 Supported Protocols

SCTP

TCP

UDP

UNIX

DL

DNS

4.1.5 Supported Tests

STREAM

MAERTS

SENDFILE

RR

NBRR

CRR

TRR

CC

DNS

4.2 Stream Tests

4.2.1 Available bulk data transfer performance tests

4.2.1.1 Forward Unidirectional Stream Performance Test (STREAM)

The intent of the STREAMS performance tests is to test forward unidirectional bulk data transfer in the direction from client to server. This is similar to the MAERTS tests, with the exception that the data transfer is in the forward direction. The basic test sequence is as follows:

     server: bind()
     server: listen()
     client: bind()
     client: connect()
     server: accept()
     client: send() [repeated]
     server: recv() [repeated]
     client: shutdown()
     client: close()
     server: close()
     test complete

There are three interface types that are of interest:

Stream

This is a connection-oriented reliable unidirectional bulk data transfer without regard for message boundaries. Protocols supporting this type of data transfer are SCTP, TCP, UNIX CO, and DLPI CO. Interfaces supporting this type of data transfer are Sockets, XTI, IPv6, UNIX and DLPI.

This interface type has been traditionally tested by netperf, however, connection-oriented tests have been lumped together with connectionless tests. Supported tests are:

SCTP_STREAM

SCTP BSD/POSIX IPv4 Sockets Interface (SOCK_STREAM)

TCP_STREAM

TCP BSD/POSIX IPv4 Sockets Interface (SOCK_STREAM)

SCTPIPV6_STREAM

SCTP BSD/POSIX IPv6 Sockets Interface (SOCK_STREAM)

TCPIPV6_STREAM

TCP BSD/POSIX IPv6 Sockets Interface (SOCK_STREAM)

STREAM_STREAM

Unix Domain BSD/POSIX Sockets Interface (SOCK_STREAM)

DLCO_STREAM

DLPI Connection-Oriented (DLCO)

Datagram

This is a connectionless unreliable unidirectional bulk data transfer regarding message boundaries. Protocols supporting this type of data transfer are UDP, UNIX CL and DLPI CL. Interfaces supporting this type of data transfer are Sockets, XTI, IPv6, UNIX and DLPI.

This interface type has been traditionally tested by netperf, however, connection-oriented tests have been lumped together with connectionless tests. Supported tests are:

UDP_STREAM

UDPIPV6_STREAM

DLCL_STREAM

FORE_STREAM

Packet

This is a connection-oriented reliable unidirectional bulk data transfer regarding message boundaries. Protocols supporting this type of data transfer are SCTP, and DLPI CO. Interfaces supporting this type of data transfer are Sockets, XTI, IPv6 and DLPI.

This interface type has not been traditionally tested by netperf; however, with the introduction of SCTP as a test protocol, these tests have been added to the netperf framework. Supported tests are:

SCTP_PACKET

SCTP BSD/POSIX IPv4 Sockets Interface (SOCK_SEQPACKET)

SCTPIPV6_PACKET

SCTP BSD/POSIX IPv6 Sockets Interface (SOCK_SEQPACKET)

4.2.1.2 Reverse Unidirectional Stream Performance Test (MAERTS)

The intent of the MAERTS performance tests is to test reverse unidirectional bulk data transfer in the direction from server to client. This is similar to the STREAM tests, with the exception that the data transfer is in the opposite direction. The basic test sequence is as follows:

     server: bind()
     server: listen()
     client: bind()
     client: connect()
     server: accept()
     server: send() [repeated]
     client: recv() [repeated]
     server: shutdown()
     server: close()
     client: close()
     test complete

Supported tests are:

SCTP_MAERTS

IPv4 SCTP BSD/POSIX Sockets Interface

TCP_MAERTS

IPv4 TCP BSD/POSIX Sockets Interface

4.2.1.3 Paged Unidirectional Stream Performance Test (SENDFILE)

The intent of the SENDFILE performance tests is to test paged unidirectional stream bulk data transfer in the direction from client to server. This is similar to the STREAM tests with the variation that the BSD-style sendfile() system call is used to transfer data directly from a mmap'ed file to the connection. The basic test sequence is as follows:

     server: bind()
     server: listen()
     client: bind()
     client: connect()
     server: accept()
     client: sendfile()
     server: recv() [repeated]
     client: shutdown()
     client: close()
     server: close()
     test complete

This test has traditionally only been available for TCP under netperf; however, OpenSS7 has added SCTP as another protocol for SENDFILE testing. These tests only used the BSD/POSIX IPv4 Sockets interface. Supported tests are:

SCTP_SENDFILE

IPv4 SCTP BSD/POSIX Sockets Interface

TCP_SENDFILE

IPv4 TCP BSD/POSIX Sockets Interface

4.2.2 Using Netperf to measure bulk data transfer performance

The most common use of netperf is measuring bulk data transfer performance. This is also referred to as "stream" or "unidirectional stream" performance. Essentially, these tests will measure how fast one system can send data to another and/or how fast the other system can receive it.

4.2.2.1 SCTP Stream Forward Performance

4.2.2.2 SCTP Stream Reverse Performance

4.2.2.3 SCTP Stream Sendfile Performance

4.2.2.4 TCP Stream Forward Performance

The TCP stream performance test is the default test for the netperf program. The simplest test is performed by entering the command:

     $ netperf -H remotehost

which will perform a 10 second test between the local system and the system identified by remotehost. The socket buffers on either end will be sized according to the systems' default and all TCP options (e.g. TCP_NODELAY) will be at their default settings.

To assist in measuring TCP stream performance, two script files are provided with the netperf distribution. They are tcp_stream_script and tcp_range_script. tcp_stream_script will invoke netperf based on the setting of script variables controlling socket and send sizes. tcp_range_script will perform a similar set of tests, with the difference being that where tcp_stream_script tests specific data points, tcp_range_script will perform tests at points within a specified range.

If you would like to perform tests other than those done by the scripts, you can invoke netperf manually. Some of the options you will likely want to experiment with are:

-s sizespec

which will set the local send and receive socket buffer sizes to the value(s) specified. [Default: system default socket buffer sizes]

-S sizespec

which behaves just like -s but for the remote system

-m value

set the local send size to value bytes. [Default: local socket buffer size]

-M value

which behaves like -m, setting the receive size for the remote system. [Default: remote receive socket buffer size]

-I value

set the test length to value seconds when value is > 0 and to |value| bytes when value < 0

-D

set the TCP_NODELAY option to true on both systems

This is not a complete list of options that can affect TCP stream performance, but it does cover those options that are used most often. A complete list of netperf options can be found in "Test Options".

4.2.2.5 TCP Stream Reverse Performance

4.2.2.6 TCP Stream Sendfile Performance

4.2.2.7 UDP Stream Performance

A UDP stream performance test is very similar to a TCP stream test. One difference is that the send size cannot be larger than the smaller of the local and remote socket buffer sizes. What this means is that you must make certain that when you specify the -m option, you use a value that is less than or equal to the socket buffer sizes (-s and -S). Also, since the UDP stream test is not the default test, the -t testname option must be specified, with the testname set to UDP_STREAM. So, a simple UDP stream test command might look something like this:

     $ netperf -H remotehost -t UDP_STREAM -- -m 1024

There is a script provided that performs various UDP stream performance tests. It is called udp_stream_script. As with TCP stream performance, you can use the script provided, or perform tests yourself to get data points not covered by the script.

NOTE: UDP is an unreliable protocol. It is important that you examine the results carefully as the reported send rate can be much higher than the actual receive rate. Great care should be taken when reporting UDP_STREAM test results to make sure they are not misleading. For example, one should always report both send and receive rates together for a UDP_STREAM test. If you are going to report a single number, you should report the receive rate.

NOTE: If you would like to "pace" the send rate of the UDP_STREAM test, add a "-DINTERVALS" to the makefile, do a `make clean' and recompile. You can then use the -b and -w global options to set the burst size (sends) and wait time (milliseconds) respectively.

4.2.2.8 XTI SCTP Stream Performance

4.2.2.9 XTI TCP Stream Performance

The XTI TCP stream performance test is quite similar to the TCP_STREAM test. XTI requires a device file to be opened – as the device file is placed in different locations on different systems, it generally must be specified. The simplest XTI TCP stream test on HP-UX is performed by entering the command:

     $ netperf -H remotehost -t XTI_TCP_STREAM -- -X /dev/inet_cots

which will perform a 10 second test between the local system and the system identified by remotehost. The STREAMS buffers on either end will be sized according to the systems' default and all TCP options (e.g. T_TCP_NODELAY) will be at their default settings.

The test parameters for an XTI_TCP_STREAM test are the same as for a TCP_STREAM test with the addition of:

-X devspec

set the local/remote XTI device file name from devspec.

4.2.2.10 XTI UDP Performance

The XTI UDP stream performance test is quite similar to the UDP_STREAM test. XTI requires a device file be opened. As the device file is placed in different locations on different systems, it generally must be specified. The simplest XTI UDP stream test on HP-UX is performed by entering the command:

     $ netperf -H remotehost -t XTI_UDP_STREAM -- -X /dev/inet_clts

The test parameters for an XTI_UDP_STREAM test are the same as for a UDP_STREAM test with the addition of:

-X devspec

set the local/remote XTI device file name from devspec.

NOTE: UDP is an unreliable protocol. It is important that you examine the results carefully as the reported send rate can be much higher than the actual receive rate. Great care should be taken when reporting UDP_STREAM test results to make sure they are not misleading. For example, one should always report both send and receive rates together for a UDP_STREAM test. If you are going to report a single number, you should report the receive rate.

NOTE: If you would like to "pace" the send rate of the UDP_STREAM test, add a "-DINTERVALS" to the makefile, do a `make clean' and recompile. You can then use the -b and -w global options to set the burst size (sends) and wait time (milliseconds) respectively.

4.2.2.11 SCTP IPv6 Stream Forward Performance

4.2.2.12 TCP IPv6 Stream Forward Performance

4.2.2.13 UDP IPv6 Stream Forward Performance

4.2.2.14 DLPI Connection Oriented Stream Performance

NOTE: DLPI tests are not compiled-in by default with netperf. If you wish to measure performance over DLPI, you will need to add a -DDO_DLPI to the makefile and perhaps add to the "LIBS=" and recompile netperf and netserver.

A DLPI Connection Oriented Stream test (DLCO_STREAM) looks very similar to a TCP Stream test – they both use reliable, connection oriented protocols. The DLPI tests differs from the TCP test in that the message size must always be less than or equal to the local interface's MTU – DLPI does not provide TCP-style segmentation and reassembly.

The simplest DLPI Connection Oriented Stream test would look something like this:

     $ netperf -H remotehost -t DLCO_STREAM -- -m 1024

Here are some of the DLPI-specific command line options:

-D devspec

specify the local and/or remote DLPI device file name(s) (fully qualified). Syntax is the same as that of sizespec.

-m value

specify the send size, in bytes, for the local system. This must be less than or equal to the link MTU.

-M value

which behaves like -m, setting the receive size for the remote system.

-p ppaspec

set the local and/or remote DLPI PPA(s). Syntax is the same as that of a sizespec.

-r value

specify the request size, in bytes, for the test.

-R value

specify the response size, in bytes, for the test.

-s value

specify the 802.2 SAP for the test. This should not conflict with any assigned SAPs.

-w sizespec

specify the local send/recv window sizes in frames (where available).

-W sizespec

specify the remote sned/recv window sizes in frames (where available).

4.2.2.15 DLPI Connectionless Stream Performance

NOTE: DLPI tests are not compiled-in by default with netperf. If you wish to measure performance over DLPI, you will need to add a -DDO_DLPI to the makefile and perhaps add to the "LIBS=" and recompile netperf and netserver.

A DLPI Connectionless Stream test (DLCL_STREAM) is analogous to a UDP_STREAM test. They both make use of unreliable, connectionless transports. The DLPI test differs from the UDP test in that the message size must always be less than or equal to the link MTU – DLPI does not provide IP-like segmentation and reassembly functionality, and the netperf benchmark does not presume to provide one.

The simplest DLPI Connectionless Stream test command line would look something like this:

     $ netperf -H remotehost -t DLCL_STREAM -- -m 1024

Here are some of the DLPI-specific command line options for the DLCL_STREAM test:

-D devspec

specify the local and/or remote DLPI device file name(s) (fully qualified). Syntax is the same as that of sizespec.

-m value

specify the send size, in bytes, for the local system. This must be less than or equal to the link MTU.

-M value

which behaves like -m, setting the receive size for the remote system.

-p ppaspec

set the local and/or remote DLPI PPA(s). Syntax is the same as that of a sizespec.

-r value

specify the request size, in bytes, for the test.

-R value

specify the response size, in bytes, for the test.

-s value

specify the 802.2 SAP for the test. This should not conflict with any assigned SAPs.

-w sizespec

specify the local send/recv window sizes in frames (where available).

-W sizespec

specify the remote sned/recv window sizes in frames (where available).

4.2.2.16 Unix Domain Stream Sockets Performance

NOTE: Unix Domain Socket tests are not compiled into netperf by default. If you wish to measure the performance of Unix Domain Sockets, you must recompile netperf and netserver with -DDO_UNIX added to the makefile.

A Unix Domain Stream Socket Stream test (STREAM_STREAM) is very much like a TCP_STREAM test.

The simplest Unix Domain Socket Stream test command line would look something like this:

     $ netperf -t STREAM_STREAM

The -H global command line option is not valid for Unix Domain Socket test and should not be specified.

Here are some of the Unix Domain-specific command line options for the STREAM_STREAM test:

-m value

set the local send size to value bytes. [Default: local socket buffer size]

-M value

which behaves like -m, setting the receive size for the remote system. [Default: remote receive socket buffer size]

-p dirspec

set the directory where pipes will be created. [Default:system default for the tempnam() call]

-s sizespec

which will set the local send an receive socket buffer sizes to the value(s) specified. [Default: system default socket buffer sizes]

-S sizespec

which behaves just like -s but for the remote system.

4.2.2.17 Unix Domain Datagram Sockets Performance

NOTE: Unix Domain Socket tests are not compiled into netperf by default. If you wish to measure the performance of Unix Domain Sockets, you must recompile netperf and netserver with -DDO_UNIX added to the makefile.

A Unix Domain Datagram Socket stream test (DG_STREAM) is very much like a TCP_STREAM test except that message boundaries are preserved. The simplest Unix Domain Datagram Socket stream test command line would look something like this:

     $ netperf -t DG_STREAM

The -H global command line option is not valid for a Unix Domain Socket test and should not be specified. Here are some of the test specific command line options available in a DG_STREAM test.

-m value

set the local send size to value bytes. [Default: local socket buffer size]

-M value

which behaves like -m, setting the receive size for the remote system. [Default: remote receive socket buffer size]

-p dirspec

set the directory where pipes will be created. [Default:system default for the tempnam() call]

-s sizespec

which will set the local send an receive socket buffer sizes to the value(s) specified. [Default: system default socket buffer sizes]

-S sizespec

which behaves just like -s but for the remote system.

4.2.2.18 Fore ATM API Stream Performance

NOTE: Fore ATM API tests are not compiled into netperf by default. If you wish to measure the performance of connections over the Fore ATM API, you must recompile netperf and netserver with -DDO_FORE added to the makefile.

A Fore ATM API stream test (FORE_STREAM) is very much like a UDP_STREAM test.

NOTE: The Fore ATM API explores an unreliable protocol. It is important that you examine the results carefully as the reported send rate can be much higher than the actual receive rate. Great care should be taken when reporting FORE_STREAM test results to make sure they are not misleading. For example, one should always report both send and receive rates together for a FORE_STREAM test. If you are going to report a single number, you should report the receive rate.

The simplest Fore ATM API stream test command line would look something like this:

     $ netperf -t FORE_STREAM -H remotehost

Here are some of the test specific command line options applicable to a FORE_STREAM test.

-a AAL

use the ATM Adaptation Layer number AAL to encapsulate packets. Specifying 3 or 4 will yield AAL3/4, and 5 will yield AAL5. [Default: 5 -> AAL5]

-b sizespec

set the mean burst target and/or minimum in units of kilobit packets. The first value is target and the second is minimum. [Default: 0,0]

-d devspec

set the name of the ATM device file to be opened. [Default: /dev/atm]

-m value

set the local send size to value bytes. This must not be larger than the ATM MTU. [Default: ATM MTU]

-M value

which behaves like -m, setting the receive size for the remote system. [Default: ATM MTU]

-p sizespec

set the peak bandwidth target and/or minimum in units of kilobits/s. The first value is target and the second is minimum. [Default: 0,0 -> network assigned]

-P sizespe