PCHAR:  A TOOL FOR MEASURING NETWORK PATH CHARACTERISTICS
Bruce A. Mah
Sandia National Laboratories
<bmah@ca.sandia.gov>
$Id: README,v 1.22 2000/01/24 23:01:07 bmah Exp $
---------------------------------------------------------

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.

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.0-3.4 RELEASE, 4.0 CURRENT (Intel)
	NetBSD 1.4.1, CURRENT (Intel)
	OpenBSD 2.5-2.6, CURRENT (Intel)
	IRIX 6.2 (MIPS)
	IRIX64 6.5 (MIPS)
	Linux 2.0-2.3 (Intel)
	Solaris 2.4-2.6 (Sparc)
	Tru64/OSF/Digital Unix 4.0 (Alpha)

pchar is written in C++.  Development, at various times, has used
gcc-2.7.2.1, gcc-2.8.1, egcs-1.1.2, and gcc-2.95.  Some testing has
also taken place with the Sun SparcWorks and IRIX 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.

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

The current version of pchar is 1.1.1.

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.ca.sandia.gov/~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.

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

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

pchar sends UDP 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.

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.

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 at <bmah@ca.sandia.gov>, and I welcome comments and
suggestions on how to improve pchar.  If you're interested in
receiving announcements of any future versions, please drop me a line
also.

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

