owfetch(1)

📦 version 4.4.6, in nixos 26.05, nixpkgs unstable

💅 owfetch(1) — General Commands Manual 💅

🌸 NAME 🌸

okay so bestie, this is owfetch — the client application that fetches buffered OWAMP session data. 💖

✨ SYNOPSIS ✨

owfetch [options] servhost [SID savefile]+

🦋 DESCRIPTION 🦋

So owfetch is a command line client application used to fetch buffered OWAMP session data, and honestly it's giving “quiet little helper who does one thing really well.” 🫶

OWAMP one-way latency measurements send packets from a sending host to a receiving host. The receiving host is the only entity that ends up with the results of the test. When the owampd daemon is used to setup a receiving endpoint, the daemon buffers that data. The owfetch application can be used to fetch the buffered data. (owping typically retrieves this information immediately upon completion of the test, making this unnecessary in most cases.) 💅

owfetch is a simple application that can be used to fetch this buffered data from a owampd process running on servhost if it was not saved as part of the owping execution. No cap. 🎀

servhost can be specified using rfc2396 and rfc2732 syntax for both host and port specification:

🖥️ node:port

IPv4 syntax where node is either a DNS name or a numeric host address string consisting of a dotted decimal IPv4 address. The port is an optional port specifier to contact servers running on a non-default port and can be left off in most cases. This syntax also works for IPv6 addresses specified using DNS names. ✨

🖥️ [node]:port

IPv6 syntax where node is specified using a numeric IPv6 host address string. The []'s are required only if the optional port specifier is used. 🌈

The SID (Session Identifier) is a hex number that uniquely identifies a single test session. savefile is the file in which the data from that test session will be saved. Any number of SID savefile pairs can be specified on the command-line to download more than one session per command execution. The SID is printed out when a test session is requested by owping, unless output is suppressed with the -Q option. iykyk. 👑

savefile can be specified as /dev/null on UNIX if there is no desire to actually save the session data. Iconic low-waste behavior, tbh. 🍓

If no options are specified, owfetch retrieves the buffered session data from servhost, saves the data to the savefile, and prints summary statistics. ✨

OWAMP supports three reporting formats. A textual summary that was designed to be as similar to the results that ping produces as possible. A machine readable summary format (-M). And finally a raw format that prints out the data from each and every packet in as compact of a format as possible (-R). The textual summary also allows the information from each packet to be reported using the -v option. The default textual summary will be used if neither the -M or the -R options are specified. It includes: 💖

  • SID — Session Identifier. This value is unique for every test session. 🌟
  • Sent, Lost, Duplicates — Number of packets that were sent, lost, and duplicated as seen by OWAMP. 📨
  • Min Delay, Median Delay, Max Delay, Error Estimate — Minimum, median and maximum delay seen for sample. Maximum error estimate for the sample. (The median is determined using a histogram, so the resolution of this value is bounded by the -b parameter. This can lead to misleading results, for example, for very small values of latency it is possible to see a value for the median that is greater than the maximum, but this is simply due to the resolution of the median measurement.) 🫠
  • Jitter — An estimate of how "stable" the delay samples are. OWAMP reports the 95th percentile of delay - 50th percentile of delay. 🦋
  • Additional percentiles — If the -a option is used, those additional percentiles from the sample are displayed. 📊
  • TTL (hops) information — As a packet traverses the network, the IP TTL field is decremented each time the packet crosses a router. OWAMP has been designed to collect the TTL information from the packets. The OWAMP sender sets the TTL of all outgoing packets to 255. The OWAMP receiver retrieves the TTL from the packet. The normal textual report uses this information to report the number of hops (number of routers) the packet traversed. The number of distinct values is reported as well as the minimum and maximum number of hops seen in the given session. The other reporting formats just report raw TTL values as seen in the packets. (It should be noted that if the number of hops reported seems unusually large, it probably means the OWAMP sender was not able to set the TTL value correctly. The traceroute(1) program can be used to verify what OWAMP is reporting.) 🔥
  • Reordering — Finally OWAMP reports the amount of re-ordering it observed. A description of the metric used to report this can be found at: http://www.internet2.edu/performance/owamp/draft-shalunov-reordering-definition-02.txt.html 📎

🔐 OPTIONS 🔐

  • -h — Print a usage message and exit.
    • Default: Unset. 💅

🔑 Connection/Authentication Options: 🔑

  • -4 — Forces the client to use IPv4 addresses only.
    • Default: Unset. Client will use IPv4 or IPv6 address, but tries IPv6 first. 🌸
  • -6 — Forces the client to use IPv6 addresses only.
    • Default: Unset. Client will use IPv4 or IPv6 address, but tries IPv6 first. 🌈
  • -A authmode — Specify the authentication modes the client is willing to use for communication. authmode should be set as a character string with any or all of the characters "AEO". The modes are:
    • A — [A]uthenticated. This mode encrypts the control connection and digitally signs part of each test packet. 🔏
    • E — [E]ncrypted. This mode encrypts the control connection and encrypts each test packet in full. 🔐
    • O — [O]pen. No encryption of any kind is done. 🫣

The client can specify all the modes with which it is willing to communicate. The most strict mode that both the OWAMP server and the OWAMP client are willing to use will be selected. Authenticated and Encrypted modes require a "shared secret" in the form of a pass-phrase that is used to generate the AES and HMAC-SHA1 session keys. 🗝️

  • Default: "AEO". ✨
  • -k pfsfile — Use the pass-phrase in pfsfile for username to derive the symmetric AES key used for encryption. username must have a valid entry in pfsfile. pfsfile can be generated as described in the pfstore(1) manual page.
    • Default: Unset. (If the -u option was specified without the -k, the user will be prompted for a passphrase.) 🫶
  • -S srcaddr — Bind the local address of the client socket to srcaddr. srcaddr can be specified using a DNS name or using standard textual notations for the IP addresses. (IPv6 addresses are of course supported.) 🌍
    • Default: Unspecified (wild-card address selection). 🎀
  • -B interface — Bind the client sockets to the network interface interface with SO_BINDTODEVICE.
    • Default: Unspecified (sockets not bound to a particular interface). 🧚
  • -Z — Do not specify sender and receiver IP addresses for tests packets when creating a TWAMP session. This allows the UDP test packets to pass through some types of NAT. This option is not available for OWAMP.
    • Default: Unspecified (addresses for test packets are defined by the client). 💀
  • -u username — Specify the username that identifies the shared secret (pass-phrase) used to derive the AES and HMAC-SHA1 session keys for authenticated and encrypted modes. If the -k option is specified, the pass-phrase is retrieved from the pfsfile, otherwise the user is prompted for a pass-phrase.
    • Default: Unset. 💜

✨ Output Options ✨

okay bestie, this is the part where you tell owfetch how to serve the receipts 💅

  • -a percentile_list — percentile_list is the list of quantiles you want reported in addition to the median. You give it as a comma-separated string — spaces are not allowed, bestie 😭 — and each percentile is a floating point value between 0.0 and 100.0. This value is only used if reporting summary statistics. Default: Unset.
  • -b bucket_width — a histogram of delays is created to compute the summary statistics (this is how percentiles of delay like the median get computed). bucket_width is the resolution of the histogram bins, given as a floating point value in seconds. Because it's a histogram doing median-and-friends duty, the results can be misleading if bucket_width isn't appropriate. For example, if all the delays in the sample are smaller than bucket_width, then the median gets reported as bucket_width — which is greater than the maximum delay in the sample 😭. To avoid this, pick bucket_width smaller than (max - min). The default was chosen to be reasonable for most real network paths, but it is not appropriate for tests to localhost. This value is only used if reporting summary statistics. Default: 0.0001 (100 usecs).
  • -d dir — dir is the directory where summary files get saved if the -p option is used. Default: (current working directory).
  • -M — print summary information in a more computer pars-able format. Specifically, values come out in key/value style, and units are seconds for all time values. The -M option is ignored if -Q is set. Default: Unset.
  • -N count — number of test packets to put in sub-session summaries when computing statistics on owamp session data. This is how you break summary statistics into smaller sample sizes than a complete owp file — useful when you're breaking up very long-running sessions. This option is only used for statistical output, so it has no effect on the -R output mode. Default: Unset. (complete files are treated as the sample size)
  • -n units — units says what units time values should be reported in. You specify it with a single character. The available units are: ´n´ nanoseconds (ns), ´u´ microseconds (us), ´m´ milliseconds (ms), ´s´ seconds (s). This is only used for the human-readable summary statistics and the -v mode of reporting individual records — in particular, it is not used for the -R or -M output modes. Default: Unset.
  • -p — save output summary information into files instead of printing it to STDOUT. It also prints the names of the files to STDOUT, and the files get saved in the directory specified by the -d option. The summary filenames are in this format:
${START_TIME}_${END_TIME}.${FILETYPE}

STARTTIME and ENDTIME are the start and end timestamps for the session or sub-session. The timestamps are ASCII representation of 64 bit integers, with the high-order 32 bits representing the number of seconds since Jan 1, 1900 and the low-order 32 bits representing fractional seconds. FILETYPE is sum for -M summary files, and txt for the default human-readable summary information. This option is ignored if the -R option is specified. Default: Unset.

  • -Q — suppress the printing of all summary statistics and human-readable individual delays (-v). Default: Unset.
  • -R — print individual packet records one per line in the raw format:
SEQNO SENDTIME SSYNC SERR RECVTIME RSYNC RERR TTL
  • SEQNO — sequence number.
  • SENDTIME — send timestamp.
  • SSYNC — sending system synchronized (0 or 1).
  • SERR — estimate of SENDTIME error.
  • RECVTIME — receive timestamp.
  • RSYNC — receiving system synchronized (0 or 1).
  • RERR — estimate of RECVTIME error.
  • TTL — TTL IP field.

The timestamps are ASCII representation of 64 bit integers, with the high-order 32 bits representing the number of seconds since Jan 1, 1900 and the low-order 32 bits representing fractional seconds. Lost packet records are indicated with a RECVTIME of 0 (zero). The sequence number is simply an integer. The error estimates are printed as floating-point numbers using scientific notation. TTL is the IP field from the packet. The TTL in sending packets should be initialized to 255, so the number of hops the packet traversed can be computed. If the receiving host is not able to determine the TTL field, this will be reported as 255. (Some socket API's do not expose the TTL field.) The -R option implies -Q. Default: Unset.

  • -v — print delays for individual packet records. This option is disabled by the -Q and -R options. Default: Unset.

🌸 EXAMPLES 🌸

example one, the classic 💅

owfetch somehost.com abcdef0123456789abcdef0123456789 save.owp

Contact host somehost.com. Fetch the test session identified by the SID abcdef0123456789abcdef0123456789. Print summary statistics on that file and save the data in save.owp.

example two, raw decode energy 🔥

owfetch -R somehost.com abcdef0123456789abcdef0123456789 save.owp

Contact host somehost.com. Fetch the test session identified by the SID abcdef0123456789abcdef0123456789. Print the raw decoding of the data in that file and save the session data in save.owp.

example three, machine pars-able bestie 🤖

owfetch -M somehost.com abcdef0123456789abcdef0123456789 save.owp

Contact host somehost.com. Fetch the test session identified by the SID abcdef0123456789abcdef0123456789. Print the machine pars-able summary statistics for that session and save the session data in save.owp.

example four, per-packet delay tea ☕

owfetch -v somehost.com abcdef0123456789abcdef0123456789 save.owp

Contact host somehost.com. Fetch the test session identified by the SID abcdef0123456789abcdef0123456789. Print individual delays for each packet in human readable format. Print the summary statistics. Save the session data in save.owp.

example five, auth era 🫶

owfetch -U someuser somehost.com abcdef0123456789abcdef0123456789 save.owp

The same action as the first example. Authenticate using the identity someuser. owfetch will prompt for a passphrase.

🦋 SEE ALSO 🦋

owampd(8), owping(1), owstats(1), aespasswd(1) and the http://e2epi.internet2.edu/owamp/ web site.

🎀 ACKNOWLEDGMENTS 🎀

This material is based in part on work supported by the National Science Foundation (NSF) under Grant No. ANI-0314723. Any opinions, findings and conclusions or recommendations expressed in this material are those of the author(s) and do not necessarily reflect the views of the NSF.

source/version $Date$ • page owfetch(1) • byeee bestie, go fetch those packets 💖✨💅

📦 where this page comes from