Provided by: pchar_1.5-6_amd64 bug

NAME

       pchar - Perform network measurements along an Internet path

SYNOPSIS

       pchar  [  -cChnqSvV  ]  [ -a analysis ] [ -b burst ] [ -d debug ] [ -g gap ] [ -H hops ] [
       -i interface ] [ -I increment ] [ -l origin ] [ -m mtu ] [ -M mode ]  [  -p protocol  ]  [
       -P port ] [ -R reps ] [ -s hop ] [ -t timeout ] [ -w file ]  -r file | host

DESCRIPTION

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

       In its default mode, a run of pchar over a short path might produce an output  that  looks
       like this:
       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)

       The  path  here  passes  through  three  hops.  Each hop consists of four lines of output:
       Partial loss documents the number and percentage of probe packets that  were  lost  during
       the  probes  for that hop.  The partial char line shows the estimated round-trip time from
       the probing host through the current hop.  The hop char line shows estimates of the round-
       trip  time  and  bandwidth  for  the  current hop.  Finally, the partial queueing shows an
       estimate of the average queueing along the path, up to and including the current hop.

       Between each hop, pchar prints the IP address and (if known) name of  the  host/router  at
       the end of the link.

       After  the last hop (usually the target host), pchar prints statistics on the entire path,
       including the path length and path pipe (the latter is an estimate of the  delay-bandwidth
       product of the path).

       Pchar  has another mode of operation, called trout (short for “tiny traceroute”).  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:
       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

OPTIONS

       -a analysis
              Set  analysis  type.   Current  choices are lsq (the default), which uses a minimum
              filter followed by a least sum-of-squares fit to estimate link bandwidths, kendall,
              which uses the same minimum filter followed by a linear fit based on Kendall's test
              statistic, lms, which does a minimum filter followed by a least median  of  squares
              fit,  and  lmsint,  which  is  an implementation of the lms computations using only
              integer arithmetic.

       -b burst
              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.

       -c     Ignore  routing  changes  detected during running.  Normally, 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 -c option may
              be useful.

       -C     Use 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.

       -d debug
              Sets debugging output level.  Generally not useful except to the developer.

       -g gap 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.

       -G gaptype
              Set  distribution  used  to  select interprobe gap times.  Current alternatives are
              fixed  (the  default)  and  exp,  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.

       -H hops
              Set the maximum number of hops that pchar will probe into the network.  The default
              maximum is 30 hops, the same as with pathchar and traceroute.

       -h     Print usage information.

       -i interface
              Set the interface to listen on for the -C option.

       -I increment
              Set the probe packet size increment.  Pchar will send IP packets  with  sizes  that
              are  integer  multiples of increment, up to the maximum specified by the -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).

       -l origin
              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 hostname(3).  Note that  this
              option  must  be  used  if the local hostname cannot be resolved to an IPv4 or IPv6
              address.

       -m mtu 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.

       -M mode
              Set  operational  mode.   The  normal  operational mode is pchar, which uses active
              probes to characterize the bandwidth, latency, loss,  and  queueing  of  the  links
              comprising  a path.  Another mode is trout, a “tiny traceroute” that is intended to
              be used as a portion of a larger network management infrastructure.

       -n     Don't attempt to resolve host addresses to names.

       -p protocol
              Select protocol to use.  Current options are: ipv4udp (UDP over IPv4), ipv4raw (UDP
              over  IPv4, using raw IP packets), ipv4icmp (ICMP over IPv4, using raw IP packets),
              ipv4tcp (TCP over IPv4, using raw IP packets), ipv6icmp (ICMPv6  over  IPv6,  using
              raw  IP  packets),  and  ipv6udp  (UDP  over IPv6).  The default protocol is either
              ipv4udp or ipv6udp, as appropriate to the network-layer address associated with the
              hostname  provided.   Compared  with  ipv4udp, the implementation of ipv4raw offers
              finer control over the contents of packet fields, but is otherwise identical.  Note
              that  the  ipv6icmp  and  ipv6udp  options  are  only available if IPv6 support was
              compiled into pchar, which can be selected at configure time.  Finally, the ipv4tcp
              option  requires  that  pcap(3)  support be specified at configure time and enabled
              with the -C option.

       -P port
              Select starting UDP port number (the default is  32768).   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.

       -q     Quiet mode, suppressing all output.  Useful if writing statistics to  standard  out
              (see the -w option).

       -r file
              Read  measurements  in  from  a file named file, as written by the -w option.  This
              option is useful for experimenting with different analysis algorithms over a  fixed
              data set.

       -R reps
              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.

       -s hop 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  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.

       -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 --with-snmp.

       -t timeout
              Set  the amount of time (in seconds) that pchar will wait for an ICMP error message
              before declaring a packet loss.  The default is 3 seconds.

       -T tos 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  -p  that  use  IPv6  as  a network-layer protocol, this option sets the
              traffic class field in the IPv6 header according to RFC 2460.

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

       -V     Print version and copyright information and exit.

       -w file
              Write statistics to a datafile named file.  This  file  can  be  read  back  in  by
              specifying  the  -r  option  in a subsequent run of pchar for off-line analysis, or
              parsed by other programs for plotting, etc.

              If file is given as  - , then the statistics are written to standard out.  In  this
              case,  the  quiet  flag  -q  may be useful, to avoid cluttering the standard output
              stream.

SEE ALSO

       pcap(3), ping(8), traceroute(8), pathchar(8)

NOTES

       Because 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 pchar.  For example, the coeffecients of determination for  the
       least squares fit can be useful in seeing how “good” 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.

       Pchar was originally named pc, which was either an abbreviation for “path characteristics”
       or “pathchar clone”.

BUGS

       Pathchar  automatically  determines  an appropriate maximum packet size to use, based on a
       Path MTU discovery algorithm.  Pchar relies on the user specifying the maximum packet size
       manually.

       Some  versions  of  Solaris  rate-limit the generation of ICMP error messages.  Any run of
       pchar through, or to, a Solaris machine may show abnormally high packet loss rates.   This
       feature  of  Solaris affects traceroute and pathchar as well, but not 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 -p option) may yield more satisfactory (or at least
       faster) results.

       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.

       There are way too many command-line options.

AUTHOR

       Bruce  A. Mah <bmah@acm.org>.  The author of the original pathchar utility is Van Jacobson
       <van@ee.lbl.gov>.  The algorithms used by pchar were coded from Van Jacobson's  viewgraphs
       describing the operation of pathchar.

                                         15 January 2001                                 pchar(8)