RELEASE NOTES PSPacer version 1.2 April 17, 2006 PSPacer is an implementation of a precise software pacer for Linux. This software was developed by the National Institute of Advanced Industrial Science and Technology (AIST), Japan. A part of the development was supported by a grant from the Ministry of Education, Sports, Culture, Science and Technology (MEXT) of Japan through the NAREGI (National Research Grid Initiative) Project. PSPACER IS LICENSED UNDER THE GNU GPL. For more information, refer the project page at http://www.gridmpi.org/. =============================================================================== WHAT IS PSPACER? PSPacer achieves precise network bandwidth control and smoothing of bursty traffic without any special hardware. It is implemented as a Linux loadable kernel module, i.e. a classful queuing discipline (Qdisc) module available for traffic control with tc (8) command. This module achieves a precise pacing per each class. For detailed description of the behavior of PSPacer, please refer to the paper "Design and Evaluation of Precise Software Pacing Mechanisms for Fast Long-Distance Networks," which is included in this package. =============================================================================== LICENSE - The GPL license. Makefile - Makefile. README - This file. README.ja - This file (in Japanese). ChangeLog - The ChangeLog. doc/ - Miscellaneous documentation (usage guide, paper). kernel/ - The kernel module. man/ - The man pages. scripts/ - Some sample setup/test scripts. tc/ - The extension library for tc (8). =============================================================================== LIMITATIONS (1) PSPacer controls the bandwidth and burstiness according to the ratio of the target bandwidth in the maximum transmission bandwidth of the system. Therefore, the system (computer, network interface, operating system, buffer settings, etc.) should have a capability to transmit packets at the maximum transmission rate (i.e. gigabit/sec for 1000BASE, 100 megabits/sec for 100BASE) to realize a precise pacing. For example, if a 33MHz/32bit PCI bus is used to connect a Gigabit Ethernet network interface, the bottleneck is the PCI bus, and the system can not transmit packets at the rate of gigabit/sec. In this case, you can explicitly specify the maximum transmission bandwidth using qdisc's "rate" parameter as follows: # /sbin/tc qdisc add ... psp ... rate 700mbit ^^^^^^^^^^^^ However, in this case, the output traffic may be imprecise since the behavior of PCI bus is not stable enough. Therefore, if you want to control Gigabit Ethernet traffic, we recommend to use PCI-X, 66MHz/64bit PCI or CSA connected network interface. Or, if the total bandwidth of the output streams is less than 100Mbps, you can set the network interface to use 100BASE so as to obtain precise pacing. For the same reason, avoid using a shared switch (dumb hub) as the edge switch to which the PC with PSPacer is connected. (2) PSPacer uses the IEEE 802.3x PAUSE frame as a gap between packets. Therefore, you can not use the PAUSE frame to stop transmission from the switch/router to which the system is connected. It is recommended to disable IEEE 802.3x flow control function of the switch (to which a PC with PSPacer is connected) in order to avoid unexpected behavior. =============================================================================== COMPILATION AND INSTALLATION #1: INSTALLATION FROM RPM (FEDORA CORE 4 ONLY) - download the RPM package: - install: # rpm -ivh pspacer-<version>.i386.rpm #2: INSTALLATION FROM SOURCE CODE The following source codes are required for the compilation: - Linux kernel 2.4.x or 2.6.x - iproute2 [NOTICE] Since the iproute2 package is tightly coupled with the kernel, you must use a proper combination. see TESTED ENVIRONMENT for more information. - unpack the iproute2 tarball: $ cd /opt $ wget http://developer.osdl.org/dev/iproute2/download/ \ iproute2-<version>.tar.gz $ tar zxvf iproute2-<version>.tar.gz $ ln -s iproute2-<version> iproute2 - unpack the PSPacer tarball: $ tar zxvf pspacer-<version>.tar.gz - make & install: $ cd pspacer-<version> <edit tc/Makefile.inc for your environment> $ make $ su # make install =============================================================================== SIMPLE USAGE - setup qdiscs (add the PSPacer qdisc as the root qdisc) # /sbin/tc qdisc add dev eth0 root handle 1: psp default 1 (add the PSPacer class whose target rate is 500Mbps) # /sbin/tc class add dev eth0 parent 1: classid 1:1 psp rate 500mbit (add the PFIFO qdisc as the sub qdisc) # /sbin/tc qdisc add dev eth0 parent 1:1 handle 10: pfifo - run iperf $ iperf -c <server host> -i 10 -t 60 ------------------------------------------------------------ Client connecting to XXXX, TCP port 5122 TCP window size: 16.0 KByte (default) ------------------------------------------------------------ [ 3] local 192.168.1.1 port 46457 connected with 192.168.1.2 port 5122 [ 3] 0.0-10.0 sec 567 MBytes 476 Mbits/sec [ 3] 10.0-20.0 sec 567 MBytes 476 Mbits/sec : - cleanup qdiscs (remove the PFIFO sub qdisc) # /sbin/tc qdisc del dev eth0 parent 1:1 handle 10: (remove the PSPacer class) # /sbin/tc class del dev eth0 parent 1: classid 1:1 (remove the PSPacer qdisc) # /sbin/tc qdisc del dev eth0 root handle 1: (remove the PSPacer module) # /sbin/rmmod sch_psp For more information, see the usage guide (doc/usage.en.pdf), and man page. =============================================================================== TESTED ENVIRONMENT The software is tested on the following environments: * Linux distribution: o RedHat Linux 9 (kernel 2.4.26 + iproute ss010824) o FedoraCore 1 (kernel 2.4.30 + iproute ss040831) o FedoraCore 3 (kernel 2.6.9 + iproute ss040831) o FedoraCore 3 (kernel 2.6.11 + iproute ss050330) o FedoraCore 3 (kernel 2.6.13 + iproute ss040831) o FedoraCore 4 (kernel 2.6.11 + iproute ss050314) o SUSE SLES 8.1 AMD64 (kernel 2.4.21 + iproute ss020116) o Debian GNU/Linux 3.1 (kernel 2.6.8 + iproute ss041019) o Debian GNU/Linux sid (kernel 2.6.12.2 + iproute ss041019) * Network interface card: o Intel PRO/1000 (PCI-X, CSA) o Intel PRO/100 o Broadcom BCM5704 (PCI-X)