pchar(8)

📦 version 1.5, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 NAME 💖

pchar — Perform network measurements along an Internet path. (bestie, this is the pchar(8) page from the System Manager's Manual, and it's literally iconic 💅)

✨ 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 🌈

Okay so pchar measures the characteristics of the network path between two Internet hosts, on either IPv4 or IPv6 networks. It's 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. No cap, it's giving network detective energy and I'm obsessed 🕵️‍♀️✨

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. It's giving hop-by-hop gossip, and I'm here for it 💅

Between each hop, pchar prints the IP address and (if known) name of the host/router at the end of the link. Like, it's doxxing the routers but in a cute way 🎀

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). Periodt, the whole path tea is spilled 🍵

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

Trout mode is lowkey the speedrun of network measurement, fr fr 🏃‍♀️💨

✨ OPTIONS ✨

okay bestie, this is the part where pchar shows you its whole wardrobe. every flag, no skips, let's go 💅

  • -a analysis — picks your analysis type. current choices are lsq (the default, and it does a minimum filter then a least sum-of-squares fit to estimate link bandwidths), kendall (same minimum filter, then a linear fit based on Kendall's test statistic), lms (minimum filter, then a least median of squares fit), and lmsint (same lms computations but using only integer arithmetic). pick your fighter 🫶
  • -b burst — sets the size of packet bursts. a burst parameter > 1 makes some number of ICMP_ECHOREPLY packets get sent before the probe packet to induce queueing. these packets are great for measuring store-and-forward switched subnets, but ngl they make measurements of fast links behind bottlenecks inaccurate 😭 so like, use with intention.
  • -c — ignore routing changes detected during running. normally pchar will exit if it gets responses from more than one host for a given hop, because it assumes that's a routing transient. but certain load-balancing schemes can cause that same condition too, so in those situations -c may be useful. it's giving "i know what i'm doing" ✨
  • -C — use the pcap(3) packet capture library (this must have been enabled at configure time). also heads up: this option must be specified to enable TCP-based probes. no -C, no TCP, periodt.
  • -d debug — sets debugging output level. generally not useful except to the developer, so like... unless you are the developer, this is not for you 🙈
  • -g gap — sets the mean inter-probe gap in seconds. default is 0.25, which works out to approximately four probes per second. please be careful not to decrease this gap by too much, bestie, so you don't flood the network 🌊. the default is deliberately conservative; users who need or want to probe faster are presumed to have at least perused the documentation for the relevant command-line options. iykyk.
  • -G gaptype — sets the distribution used to pick interprobe gap times. current alternatives are fixed (the default) and exp, which picks gap times from an exponential distribution. exp is an attempt to simulate a Poisson process of probe packets (a lot of alliteration, we love that for it), BUT because each probe experiment takes a non-zero amount of time, this is only an approximation. not exact, just vibes 🦋
  • -H hops — sets the maximum number of hops pchar will probe into the network. default max is 30 hops, same as with pathchar and traceroute.
  • -h — print usage information. the classic cry for help 🥺
  • -i interface — sets the interface to listen on for the -C option.
  • -I increment — sets 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. default is a 32-byte increment. small increments should give you more accurate results, but they mean more probes, which means it takes longer to run. accuracy vs. time, the eternal struggle 😭
  • -l origin — sets the local source of probe packets. mostly useful on multi-homed hosts. if you don't specify it, it defaults to the value of hostname(3). note: you must use this option if the local hostname cannot be resolved to an IPv4 or IPv6 address. no resolution, no probe, no cap.
  • -m mtu — sets the maximum probe packet size. this value should be no larger than the path MTU between the two hosts. default is 1500 bytes, the Ethernet MTU 👑
  • -M mode — sets the operational mode. the normal 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" intended to be used as a portion of a larger network management infrastructure 🐟 iconic name honestly.
  • -n — don't attempt to resolve host addresses to names. we're keeping it numerical, we're keeping it fast.
  • -p protocol — selects the 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
    • ipv6udp — UDP over IPv6

the default protocol is either ipv4udp or ipv6udp, as appropriate to the network-layer address associated with the hostname you provided. compared with ipv4udp, the implementation of ipv4raw offers finer control over the contents of packet fields, but is otherwise identical. note: ipv6icmp and ipv6udp are only available if IPv6 support was compiled into pchar, which can be selected at configure time. and finally, ipv4tcp requires that pcap(3) support be specified at configure time and enabled with the -C option. so many prerequisites, so little time 💀

  • -P port — selects the 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. do not steal someone's port, that's not slay behavior 🚫
  • -q — quiet mode, suppressing all output. useful if you're writing statistics to standard out (see the -w option). silence is golden ✨
  • -r file — read measurements in from a file named file, as written by the -w option. this is useful for experimenting with different analysis algorithms over a fixed data set. science mode 🔬
  • -R reps — sets 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. same tradeoff as always, bestie.
  • -s hop — sets 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 let probing begin farther out from the testing host, which can help when you're trying to probe outside a local internetwork whose characteristics 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. using this feature requires the UCD SNMP library, plus enabling it at configure-time using --with-snmp.
  • -t timeout — sets the amount of time (in seconds) that pchar will wait for an ICMP error message before declaring a packet loss. default is 3 seconds.
  • -T tos — sets 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 that 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, it prints a synopsis of the hop number, repetition, and probe packet size on standard out. verbose mode mimics the output of pathchar. talkative era 💬
  • -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 that case, the quiet flag -q may be useful, to avoid cluttering the standard output stream. pro move honestly 🎀

🌈 SEE ALSO 🌈

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

the whole friend group, all iconic, all linked 💜

📝 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. so like, check your R² before you @ anyone, bestie 🫶

pchar was originally named pc, which was either an abbreviation for "path characteristics" or "pathchar clone". we don't know. it's a mystery. a little lore for you 🌸

💀 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. no auto-pilot here, that's on you.

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. okay so there's actually a workaround, we love that.

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. don't mix them up, i'm begging 🙈

there are way too many command-line options. yes that's in the official docs. the manpage is self-aware. it's giving main character energy honestly 👑

👑 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. legends only, no cap 🌟

and that's the whole page bestie, we did it 🎉 this one's from 15 January 2001, and it's the pchar(8) manual page — go probe something responsibly, and don't flood the network on your way out 💖✨🦋

📦 where this page comes from