PCHAR:  A TOOL FOR MEASURING NETWORK PATH CHARACTERISTICS
Bruce A. Mah
<bmah@kitchenlab.org>
$Id: README 1085 2005-02-12 20:25:51Z bmah $
---------------------------------------------------------

INTRODUCTION
------------

pchar is a reimplementation of the pathchar utility, written by Van
Jacobson.  Both programs attempt to characterize the bandwidth,
latency, and loss of links along an end-to-end path through the
Internet.  pchar works in both IPv4 and IPv6 networks.

The pchar program requires root privileges to send the network
packages.  It might be safe to make suid root, but no-one know for
sure.

As of pchar-1.5, this program is no longer under active development,
and no further releases are planned.

Please see the disclaimer notice at the end of this file for legal
information.

PLATFORMS
---------

The main development platforms for pchar are FreeBSD and Solaris.  There
have been reports of success with pchar on:

	FreeBSD 2.2.7, 3.X, 4.X, 5.X (x86, Alpha)
	NetBSD 1.4.1, 1.5 (various architectures)
	OpenBSD 2.5-2.8 (various architectures)
	IRIX 6.2, 6.5 (MIPS)
	IRIX64 6.5 (MIPS)
	Linux (RedHat 9 / x86, various Debian versions / x86)
	Solaris 2.4-2.6, 7, 8 (Sparc)
	Tru64/OSF/Digital Unix 4.0 (Alpha)
	MacOS 10.3.7 (Macintosh)

pchar is written in C++.  During various stages of development, the
gcc-2.7.2.1, gcc-2.8.1, egcs-1.1.2, gcc-2.95, and gcc-3.4.2 compilers
were used for building pchar.  Some testing has also taken place with
the Sun SparcWorks and IRIX MIPSpro C++ compilers.

pchar's IPv6 support was originally written for the KAME 19991018 
snapshot for FreeBSD 3.3-RELEASE.  The KAME team has since tested it
with FreeBSD, NetBSD, and OpenBSD, for more recent versions of the KAME 
IPv6 stack and the integrated IPv6 stacks in FreeBSD, NetBSD, and
OpenBSD.  pchar has also been run successfully on the native IPv6
stack in Solaris 8.

OBTAINING PCHAR
---------------

The current version of pchar is 1.5.

Clearly, anyone reading this file has very likely already obtained a
copy of pchar, but it's worth noting that the current source code
distribution can be found at:

http://www.kitchenlab.org/~bmah/Software/pchar/

pchar can also be found as part of the FreeBSD Ports Collection and
the NetBSD Packages Collection, the OpenBSD Ports Collection, and as
part of the ports/pkgsrc collections for the KAME distributions for
FreeBSD, NetBSD, and OpenBSD.  pchar is available as a Debian package
as well.

Beginning with pchar-1.3, source distributions are signed with the
following PGP public key, available from the author's Web page or from
most PGP keyservers:

pub  1024R/23EC263D 1997-03-12 Bruce A. Mah <bmah@acm.org>
     Key fingerprint = C6 12 04 94 49 D5 B1 79  24 E9 D2 D7 0E 4F 5E 40

Beginning with pchar-1.5, source distributions are signed with the
following PGP public key, available from the author's Web page or from
most PGP keyservers:

pub   1024D/5BA052C3 1997-12-08
      Key fingerprint = F829 B805 207D 14C7 7197  7832 D8CA 3171 5BA0 52C3
uid                  Bruce A. Mah <bmah@acm.org>
uid                  Bruce A. Mah <bmah@ca.sandia.gov>
uid                  Bruce A. Mah <bmah@ieee.org>
uid                  Bruce A. Mah <bmah@cisco.com>
uid                  Bruce A. Mah <bmah@employees.org>
uid                  Bruce A. Mah <bmah@freebsd.org>
uid                  Bruce A. Mah <bmah@packetdesign.com>
uid                  Bruce A. Mah <bmah@kitchenlab.org>
sub   2048g/B4E60EA1 1997-12-08


INSTALLATION
------------

pchar uses GNU autoconf, so compiling it may be as simple as extracting
the source code from the tar file and doing:

% ./configure
% make

To enable IPv6 support, give the --with-ipv6 option to configure.  If
there is a directory for IPv6-specific libraries, it can be specified
via an argument to the --with-ipv6 option, for example:

% ./configure --with-ipv6=/usr/local/v6
% make

To enable SNMP support, give the --with-snmp option to configure.  Any
argument to this option, if given, is taken as a directory in which to
find the UCD SNMP support files (usually /usr/local).

To enable pcap support (this enables kernel-level timestamps and TCP
probes), give the --with-pcap option to configure.  Any argument to
this option, if given, is taken as a directory in which to find the
pcap library/include files.  Note that the -C option must be given at
runtime to actually use the pcap support.

A FEW NOTES ON PCHAR'S OPERATION
--------------------------------

pchar sends probe packets into the network of varying sizes and
analyzes ICMP messages produced by intermediate routers, or by the
target host.  By measuring the response time for packets of different
sizes, pchar can estimate the bandwidth and fixed round-trip delay
along the path.  pchar varies the TTL of the outgoing packets to get
responses from different intermediate routers.  It can use UDP or ICMP
packets as probes; either or both might be useful in different
situations.

At each hop, pchar sends a number of packets (controlled by the -R flag)
of varying sizes (controlled by the -i and -m flags).  pchar determines
the minimum response times for each packet size, in an attempt to
isolate jitter caused by network queueing.  It performs a simple
linear regression fit to the resulting minimum response times.  This
fit yields the partial path bandwidth and round-trip time estimates.

To yield the per-hop estimates, pchar computes the differences in the
linear regression parameter estimates for two adjacent partial-path
datasets.  (Earlier versions of pchar differenced the minima for the
datasets, then computed a linear regressions.)  The -a flag selects
between one of (currently) two different algorithms for performing the
linear regression, either a least squares fit or a nonparametric
method based on Kendall's test statistic.

Using the -b option causes pchar to send small packet bursts,
consisting of a string of back-to-back ICMP ECHO_REPLY packets
followed by the actual probe.  This can be useful in probing switched
networks.

CAVEATS
-------

Router implementations may very well forward a packet faster than they
can return an ICMP error message in response to a packet.  Because of
this fact, it's possible to see faster response times from longer
partial paths; the result is a seemingly non-sensical, negative
estimate of per-hop round-trip time.

Transient fluctuations in the network may also cause some odd results.

If all else fails, writing statistics to a file will give all of the
raw data that pchar used for its analysis.

Some types of networks are intrinsically difficult for pchar to
measure.  Two notable examples are switched networks (with multiple
queues at Layer 2) or striped networks.  We are currently
investigating methods for trying to measure these networks.

pchar needs superuser access due to its use of raw sockets.

OSF/1 (a.k.a. Digital UNIX or Tru64) users should see item 5 in the
FAQ file regarding timing.

CONTACT INFO
------------

I can be reached by email at <bmah@kitchenlab.org>.  Although pchar is no
longer under active development, I still welcome comments and
suggestions on how to improve it.

DISCLAIMER
----------

This work was first produced by an employee of Sandia National
Laboratories under a contract with the U.S. Department of Energy.
Sandia National Laboratories dedicates whatever right, title or
interest it may have in this software to the public. Although no
license from Sandia is needed to copy and use this software, copying
and using the software might infringe the rights of others. This
software is provided as-is. SANDIA DISCLAIMS ANY WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED.

Contains software developed at Lawrence Berkeley Laboratory, and which
is "Copyright (c) 1995, 1996, 1997, 1998 The Regents of the University
of California."

