.\" Copyright and comments
.TH pchar 8 "15 January 2001"
.SH NAME
pchar \- Perform network measurements along an Internet path
.SH SYNOPSIS
.B pchar
.RB [ " \-cChnqSvV " ]
.RB [ " \-a\ \fIanalysis\fP " ]
.RB [ " \-b\ \fIburst\fP " ]
.RB [ " \-d\ \fIdebug\fP " ]
.RB [ " \-g\ \fIgap\fP " ]
.RB [ " \-H\ \fIhops\fP " ]
.RB [ " \-i\ \fIinterface\fP " ]
.RB [ " \-I\ \fIincrement\fP " ]
.RB [ " \-l\ \fIorigin\fP " ]
.RB [ " \-m\ \fImtu\fP " ]
.RB [ " \-M\ \fImode\fP " ]
.RB [ " \-p\ \fIprotocol\fP " ]
.RB [ " \-P\ \fIport\fP " ]
.RB [ " \-R\ \fIreps\fP " ]
.RB [ " \-s\ \fIhop\fP " ]
.RB [ " \-t\ \fItimeout\fP " ]
.RB [ " \-w\ \fIfile\fP " ]
.BR " \-r\ \fIfile\fP " |
.I "host"
.SH DESCRIPTION
.I Pchar 
measures the characteristics of the network path between two Internet
hosts, on either IPv4 or IPv6 networks.  It is an
independently-written reimplementation of the 
.I pathchar
utility, using similar algorithms.  Both programs measure network
throughput and round-trip time by sending varying-sized UDP packets
into the network and waiting for ICMP messages in response.  Like
.IR traceroute ,
they modulate the IPv4 time-to-live (TTL) field or the IPv6 hop limit
field to get measurements
at different distances along a path.
.LP
In its default mode, a run of
.I pchar
over a short path might produce an output that looks like this:
\fC
.nf
pchar to dancer.ca.sandia.gov (146.246.246.1) using UDP/IPv4
Packet size increments by 32 to 1500
46 test(s) per repetition
32 repetition(s) per hop
 0:
    Partial loss:      0 / 1472 (0%)
    Partial char:      rtt = 0.657235 ms, (b = 0.000358 ms/B), r2 = 0.989713
                       stddev rtt = 0.004140, stddev b = 0.000006
    Hop char:          rtt = 0.657235 ms, bw = 22333.268771 Kbps
    Partial queueing:  avg = 0.000150 ms (418 bytes)
 1: 146.246.243.254 (con243.ca.sandia.gov)
    Partial loss:      0 / 1472 (0%)
    Partial char:      rtt = 0.811278 ms, (b = 0.000454 ms/B), r2 = 0.995401
                       stddev rtt = 0.003499, stddev b = 0.000005
    Hop char:          rtt = 0.154043 ms, bw = 83454.764777 Kbps
    Partial queueing:  avg = 0.000153 ms (336 bytes)
 2: 146.246.250.251 (slcon1.ca.sandia.gov)
    Partial loss:      0 / 1472 (0%)
    Partial char:      rtt = 1.044412 ms, (b = 0.002161 ms/B), r2 = 0.999658
                       stddev rtt = 0.004533, stddev b = 0.000006
    Hop char:          rtt = 0.233133 ms, bw = 4686.320952 Kbps
    Partial queueing:  avg = 0.000100 ms (46 bytes)
 3: 146.246.246.1 (dancer.ca.sandia.gov)
    Path length:       3 hops
    Path char:         rtt = 1.044412 ms, r2 = 0.999658
    Path bottleneck:   4686.320952 Kbps
    Path pipe:         611 bytes
    Path queueing:     average = 0.000100 ms (46 bytes)
.fi
\fP
.LP
The path here passes through three hops.  Each hop consists of four
lines of output:  
.B Partial loss
documents the number and percentage of probe packets that were lost
during the probes for that hop.
The
.B partial char
line shows the estimated round-trip time
from the probing host through the current hop.  The
.B hop char
line shows estimates of the round-trip time and bandwidth for the
current hop.  Finally, the
.B partial queueing
shows an estimate of the average queueing along the path, up to and
including the current hop.
.LP
Between each hop,
.I pchar
prints the IP address and (if known) name of the host/router at the
end of the link.
.LP
After the last hop (usually the target host),
.I pchar
prints statistics on the entire path, including the
.B path length 
and
.B path pipe
(the latter is an estimate of the delay-bandwidth product of the
path).
.LP
.I Pchar
has another mode of operation, called \fItrout\fP (short for \*(lqtiny
traceroute\*(rq).  In this mode, packets of random sizes (one packet per
hop diameter) are sent along the path to a destination.  No attempt at
estimating link properties is made; however, this mode is extremely
fast.  It is intended for use as a part of a larger measurement
infrastructure.  The output from this mode might look like:
\fC
.nf
trout to bmah-freebsd-1.cisco.com (171.70.84.44) using ICMP/IPv4 (raw sockets)
Packet size increments from 28 to 1500 by 32
 0: 171.70.84.42 (bmah-freebsd-0.cisco.com)
 1: 171.70.84.44 (bmah-freebsd-1.cisco.com) 352 -> 352 bytes: 0.318 ms
.fi
\fP
.SH OPTIONS
.TP
.B \-a \fIanalysis\fP
Set analysis type.  Current choices are \fBlsq\fP (the default), 
which uses a
minimum filter followed by a least sum-of-squares fit to estimate link
bandwidths, \fBkendall\fP, which uses the same minimum filter
followed by a linear fit based on Kendall's test statistic, 
\fBlms\fP, which does a minimum filter followed by a least
median of squares fit, and \fBlmsint\fP, which is an implementation of
the \fBlms\fP computations using only integer arithmetic.
.TP
.B \-b \fIburst\fP
Set the size of packet bursts.
A burst parameter > 1 will result in some number of ICMP_ECHOREPLY
packets sent before the probe packet to induce queueing.
These packets are useful for measuring store-and-forward switched
subnets, but make measurements of fast links behind bottlenecks
inaccurate.
.TP
.B \-c
Ignore routing changes detected during running.  
Normally, 
.I pchar
will exit if it receives responses from more than one host for a given
hop, assuming that this condition is caused by a routing transient.
However, certain load-balancing schemes can also cause this condition.
In such situations, using the 
.B \-c
option may be useful.
.TP
.B \-C
Use 
.IR pcap (3)
packet capture library (this must have been enabled at configure time).
Note that this option must be specified to enable TCP-based probes.
.TP
.B \-d \fIdebug\fP
Sets debugging output level.  Generally not useful except to the
developer.
.TP
.B \-g \fIgap\fP
Set the mean inter-probe gap in seconds.  The default is 0.25, which results
in approximately four probes per second being run.  Care should be
taken not to decrease this gap by too much, in order to avoid
flooding the network.  The default value here is deliberately
conservative; users with the need or desire to probe more quickly
are presumed to have at least perused the documentation for the
relevant command-line options.
.TP
.B \-G \fIgaptype\fP
Set distribution used to select interprobe gap times.
Current alternatives are \fBfixed\fP (the default) and \fBexp\fP,
which picks gap times from an exponential distribution.  The
latter option is an attempt to simulate a Poisson process of probe
packets (a lot of aliteration), however due to the fact that each
probe experiment takes a non-zero amount of time, this is only an
approximation.
.TP
.B \-H \fIhops\fP
Set the maximum number of hops that
.I pchar
will probe into the network.  The default maximum is 30 hops, the
same as with
.I pathchar
and
.IR traceroute.
.TP
.B \-h
Print usage information.
.TP
.B \-i \fIinterface\fP
Set the interface to listen on for the 
.B -C
option.
.TP
.B \-I \fIincrement\fP
Set the probe packet size increment.
.I Pchar
will send IP packets with sizes that are integer multiples of
.IR increment ,
up to the maximum specified by the
.B \-m
option.  The default is a 32-byte increment.  Small increments should
produce more accurate results, but will result in more probes (thus
taking longer to run).
.TP
.B \-l \fIorigin\fP
Set the local source of probe packets.  This option is mostly
useful on multi-homed hosts.  If not specified, it defaults to the
value of 
.IR hostname (3).
Note that this option \fImust\fP be used if the local hostname
cannot be resolved to an IPv4 or IPv6 address.
.TP
.B \-m \fImtu\fP
Set the maximum probe packet size.  This value should be no larger
than the path MTU between the two hosts.  The default is 1500 bytes,
the Ethernet MTU.
.TP
.B \-M \fImode\fP
Set operational mode.  The normal operational mode is \fIpchar\fP,
which uses active probes to characterize the bandwidth, latency, loss,
and queueing of the links comprising a path.  Another mode is
\fItrout\fP, a \*(lqtiny traceroute\*(rq that is intended to be used as a
portion of a larger network management infrastructure.
.TP
.B \-n
Don't attempt to resolve host addresses to names.
.TP
.B \-p \fIprotocol\fP
Select protocol to use.  Current options are:
.B ipv4udp
(UDP over IPv4),
.B ipv4raw
(UDP over IPv4, using raw IP packets), 
.B ipv4icmp
(ICMP over IPv4, using raw IP packets), 
.B ipv4tcp
(TCP over IPv4, using raw IP packets),
.B ipv6icmp
(ICMPv6 over IPv6, using raw IP packets), and
.B ipv6udp
(UDP over IPv6).  
The default protocol is either \fBipv4udp\fP or \fBipv6udp\fP,
as appropriate to the network-layer address associated with the
\fIhostname\fP provided.
Compared with
.BR ipv4udp ,
the implementation of
.B ipv4raw 
offers finer control over the contents of packet fields, but is
otherwise identical.  Note that the 
.B ipv6icmp
and 
.B ipv6udp
options are only available if IPv6 support was compiled into
.IR pchar ,
which can be selected at configure time.  Finally, the
.B ipv4tcp
option requires that
.IR pcap (3)
support be specified at configure time and enabled with the
.B
\-C
option.
.TP
.B \-P \fIport\fP
Select starting UDP port number (the default is 32768).
.I Pchar
uses consecutive port numbers starting from this value, counting up.
Care should be taken not to use port numbers that are actually in use
by network services.
.TP
.B \-q
Quiet mode, suppressing all output.  Useful if writing statistics
to standard out (see the 
.B \-w
option).
.TP
.B \-r \fIfile\fP
Read measurements in from a file named
.IR file ,
as written by the 
.B -w
option.  This option is useful for experimenting with different
analysis algorithms over a fixed data set.
.TP
.B \-R \fIreps\fP
Set the number of repetitions of each probe packet size to be sent.
The default is 32 packets of each size.  Smaller values speed up testing,
at the expense of accuracy.
.TP
.B \-s \fIhop\fP
Set the starting hop at which to begin probing.  The default is 1,
so network probing will begin at the host adjacent to the host where
.I pchar
is being run.  Larger values allow probing to begin farther out from
the testing host; this can be helpful when attempting to probe outside
a local internetwork whose characterisics are well-known.
.TP
.B \-S
Do SNMP queries at each hop to determine each router's idea of
what it thinks its next-hop interface characteristics are.  Use of
this features requires the UCD SNMP library, as well as enabling
at configure-time using \fB--with-snmp\fP.
.TP
.B \-t \fItimeout\fP
Set the amount of time (in seconds) that
.I pchar
will wait for an ICMP error message before declaring a packet loss.
The default is 3 seconds.
.TP
.B \-T \fItos\fP
Set the IP Type Of Service bits for outgoing UDP packets.  This option
isn't terribly useful for a lot of people, but it can be used, for
example, to force a particular DiffServ codepoint within networks that
support this functionality.  For values of
.B \-p
that use IPv6 as a network-layer protocol, this option sets the
traffic class field in the IPv6 header according to RFC 2460.
.TP
.B \-v
Verbose mode.  While each probe is in progress, print a synopsis
of the hop number, repetition, and probe packet size on standard
out.  Verbose mode mimics the output of 
.IR pathchar .
.TP
.B \-V
Print version and copyright information and exit.
.TP
.B \-w \fIfile\fP
Write statistics to a datafile named
.IR file .
This file can be read back in by specifying the
.B \-r
option in a subsequent run of 
.I pchar
for off-line analysis, or parsed by other programs for plotting, etc.
.IP
If
.I file
is given as
.BR
\- ,
then the statistics are written to standard out.  In this case, the
quiet flag
.B
\-q
may be useful, to avoid cluttering the standard output stream.
.SH SEE ALSO
.IR pcap (3),
.IR ping (8),
.IR traceroute (8),
.IR pathchar (8)
.SH NOTES
Because
.I pchar
relies on measurements to drive its estimates of network
characteristics, it may occasionally produce some seemingly odd
results.  Care should be taken when interpreting the output of
.IR pchar .
For example, the coeffecients of determination for the least
squares fit can be useful in
seeing how \*(lqgood\*(rq of a fit the bandwidth and round-trip time
parameters describe the performance seen by the probe packets.  The
coefficient of determination takes values from 0 to 1, where a
value of 1 indicates that the estimated parameters perfectly fit the
data.
.LP
.I Pchar
was originally named
.IR pc ,
which was either an abbreviation for \*(lqpath characteristics\*(rq or
\*(lqpathchar clone\*(rq.
.SH BUGS
.I Pathchar 
automatically determines an appropriate maximum packet size
to use, based on a Path MTU discovery algorithm.  
.I Pchar
relies on the user specifying the maximum packet size manually.
.LP
Some versions of Solaris rate-limit the generation of ICMP error
messages.  Any run of 
.I pchar
through, or to, a Solaris machine may show abnormally high packet loss
rates.  This feature of Solaris affects
.I traceroute
and
.I pathchar
as well, but not
.IR ping .
Some versions of Linux appear to have similar rate-limiting.
In situations such as this, the use of ICMP-based probes (selected by
the \fB-p\fP option) may yield more satisfactory (or at least faster) 
results.
.LP
Timestamps printed after each run are printed relative to the local
time zone.
Timestamps saved in trace files are expressed as seconds
past the epoch.
.LP
There are way too many command-line options.
.SH AUTHOR
Bruce A. Mah <bmah@acm.org>.  The author of the original
.I pathchar
utility is Van Jacobson <van@ee.lbl.gov>.  The algorithms used
by
.I pchar
were coded from Van Jacobson's viewgraphs describing the operation
of
.IR pathchar .