owping(1)

📦 version 4.4.6, in nixos 26.05, nixpkgs unstable

💖 NAME 💖

okay so welcome to owping(1), bestie — this is the page from the General Commands Manual for owping, the client application to request one-way latency tests. That's the whole official NAME vibe. 🫶

🌈 SYNOPSIS 🌈

owping [options] testpeer [server]

✨ DESCRIPTION ✨

okay so owping is a command line client application that you use to initiate one-way latency tests. slay.

Round-trip latency measurements (ping) are an accepted technique to look for network problems; one-way measurements have the potential to be even more useful. With round-trip measurements it is difficult to isolate the direction in which congestion is experienced. Traffic is often asymmetric with many sites being either primarily producers or consumers of data. One-way measurements allow more informative measurements. It is much easier to isolate the effects of traffic on specific parts of a network. 💅

owping works by contacting an owampd daemon on the remote peer host. owampd manages the resources of the host on which it runs.

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

server is an optional argument that indicates the OWAMP server address if it is different from the testpeer. This is mostly useful in the case of hosts with more than one network interface where the OWAMP server is not listening on the interface that you want to test. The server can be specified using the same syntax as the testpeer. 👑

The owping client is used to request the type of test wanted. The parameters allow the user to select the full send schedule, direction of test (send, receive, or both) as well as packet size. The results are returned to the client after the test completes. The test will not be complete until timeout after the last packet is scheduled to be sent. ⏳

With no options specified, owping will perform concurrent bidirectional tests of 100 packets each at a rate of approximately 1 packet every 0.1 seconds to and from the testpeer. Then, the receivers on each host will wait a reasonable period after that to count possible duplicate packets. (See the -L option.) Upon completion of the sessions, summary statistics are printed to STDOUT. 📈

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.
  • 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
lowkey important note for the TTL tea ☕: 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. 👀

💅 OPTIONS 💅

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

🛠️ Test Configuration Options: 🛠️

  • -c count — Number of test packets to send in the test session. Default: 100.
  • -D DSCP — sets an RFC 2474 style DSCP value for the TOS byte in the packets you're sending 💅. You can drop in a 6-bit numeric value in decimal, hex, or octal. And on top of that, these symbolic DSCP name constants are understood too (the example applications are straight from RFC 4594, not me making things up ✨):
    • NONE — no value listed, no service class, no example. It's giving mystery 🎀
    • DEFAULT, DF, CS0 — value 000000, service class Standard, examples Undifferentiated (the DF and CS0 rows keep the same Standard / Undifferentiated vibes as DEFAULT, just no separate value cell listed) 🌸
    • CS1 — value 001000, service class Low-Priority Data, examples No BW assurance
    • AF11 — value 001010 · AF12 — value 001100 · AF13 — value 001110 → all three are service class High-Throughput Data, example Store and forward 🦋
    • CS2 — value 010000, service class OAM, examples OAM&P
    • AF21 — value 010010 · AF22 — value 010100 · AF23 — value 010110 → service class Low-Latency Data, example Web-based ordering ⭐
    • CS3 — value 011000, service class Broadcast Video, examples TV & live events
    • AF31 — value 011010 · AF32 — value 011100 · AF33 — value 011110 → service class Multimedia Streaming, example Streaming video and audio 💖
    • CS4 — value 100000, service class Real-Time Interactive, examples Video conf and gaming
    • AF41 — value 100010 · AF42 — value 100100 · AF43 — value 100110 → service class Multimedia Conferencing, example H.323 video conferencing 👑
    • CS5 — value 101000, service class Signaling, examples Video conf and gaming
    • EF — value 101110, service class Telephony, examples IP Telephony bearer 🔥
    • CS6 — value 110000, service class Network Control, examples Network routing
    • CS7 — value 111000, no service class, no example (it's the quiet one 🙈)
Default: Unset.
  • -f | -F fromfile — does a One-way test from the target testpeer, bestie 🫶. The -F form is the one that saves the results into fromfile. And here's the tea: if you don't specify any directional options (-f, -F, -t, -T), then owping requests concurrent bidirectional tests. Otherwise, only the directions you explicitly named get performed, periodt 💅
Default: True, unless the -t or -T have been specified explicitly.
  • -i send_schedule — send_schedule is the scheduled delay between sent packets ⏱️. You give it a list of delays as a comma separated string — and no, spaces are not allowed, don't try it 😭. Each delay is a value plus a type, and there are two types currently available:
    • f — [f]ixed offsets. This one means the value is a real offset. 🎯
    • e — [e]xponential. This means an exponentially distributed pseudo-random quantity with a mean about the value given. This is the default if you don't slap an alpha qualifier on there, and the whole point of it is to negate periodicity effects 🌀

So here's how the sending process rolls: when it starts, it peeks at the first delay in the list and waits that long before sending the first packet. Then it takes the next delay from the list to figure out how much longer to wait before packet number two. This keeps going until there are no more delay values in the list — and then it loops right back to the beginning of the complete send_schedule and starts the whole dance over again 🌈. It keeps doing this until the sending process has sent count packets, as specified by the -c option.

Default: 0.1e (seconds)
  • -E enddelay — how long a sender waits after session completion (that's last packet send-time plus timeout) before it sends the stop sessions message 🕐.

This matters big time if the sender clock is running ahead of the receiver clock. Let me break it down for you:

A session is complete timeout after the send time of the final packet. If the sender clock is ahead of the receiver's clock, the sender will declare the session complete before the receiver does 😬. The receiver is only allowed to keep records for the packets that were sent at least timeout before it receives the stop sessions message from the sender. So if the sender clock is running ahead of the receiver clock, the receiver gets forced to delete some number of the final packets from the session. Yikes 💀.

This parameter directs the sender to wait enddelay after session completion, which allows the receiver clock to be essentially enddelay later than the sender clock and still retain full sessions 🫶.

Default: 1.0 (seconds)
  • -L timeout — how long to wait for a packet to be received before declaring it lost 🔍. Because of that, it's also the amount of time the test session has to stay active after the last packet is sent so it can actually count duplicate packets. So like — add this number to the duration of your session to figure out how long to expect a test session to take, iykyk.
Note: the default of 2 seconds longer than a round-trip estimate was simply a guess for how long a typical user would be willing to wait after the end of the test for the results 🙈. But for the OWAMP results to be statistically relevant, and to be able to compare data between two sessions, the timeout option should be specified. Like, actually. 👑
Default: 2 seconds longer than the round-trip estimate. (seconds)
  • -P 0 | lowport-highport — picks the specific port range to use for OWAMP-Test packets 🎀. Two ways to give it:
    • 0 — tells the client to let the system pick the port (ephemeral). Main character energy, let the OS decide ✨
    • a range — lowport must be a smaller value than highport, and both numbers must be valid port values (16 bit unsigned integer values, no cheating 💅)
Default: 0
  • -s size — the size of the padding added to each minimally-sized test packet 📦. Heads up on the minimums: the minimal UDP payload for a test packet in open mode is 14 bytes. The minimal UDP payload for a test packet in authenticated or encrypted mode is 48 bytes 🔐.
Default: 0 (bytes)
  • -t | -T tofile — does a one-way test toward the target testpeer 🦋. The -T form is the one that saves the results into tofile. And same deal as before: if no directional options (-f, -F, -t, -T) are specified, owping requests concurrent bidirectional tests; otherwise only the explicit directions are performed 💖.
Default: True, unless the -f or -F have been specified explicitly.
  • -z delayStart — Time to wait before starting a test, bestie. The client tries to calculate a reasonable minimum delay so that the start of the test happens after the setup protocol is done. If delayStart is specified as a value less than this reasonable minimum delay, the reasonable minimum will be used instead. No cap.

Default: 2-3 times the round-trip estimate plus 1 (seconds)

💖 Connection/Authentication Options 💖

  • -4 — Forces the client to use IPv4 addresses only. IPv4 girlie forever 💅

Default: Unset. Client will use IPv4 or IPv6 address, but tries IPv6 first.

  • -6 — Forces the client to use IPv6 addresses only. IPv6 main character energy ✨

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.) Slay 🦋

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 🎀

  • -a percentile_list — percentile_list indicates the list of quantiles to be reported out in addition to median. This is done by specifying a list of percentiles in a comma separated string (spaces are not allowed). Each percentile is indicated by 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 used to compute percentiles of delay such as median.) The bucket_width indicates the resolution of the bins in the histogram. This value is specified using a floating point value and the units are seconds.
⚠️ Because a histogram is used to compute the median (and other percentiles of delay), the results can be misleading if the bucket_width is not appropriate. For example, if all of the delays in the sample are smaller than the value of bucket_width, then the median will be reported as bucket_width — a value that is greater than the maximum delay in the sample. 😭 To avoid this, bucket_width should be picked to be smaller than (max - min). The default value was selected to be reasonable for most real network paths, but it is not appropriate for tests to the localhost however.

This value is only used if reporting summary statistics.

Default: 0.0001 (100 usecs)

  • -d dir — dir indicates the directory in which to save summary files if the -p option is used.

Default: (current working directory)

  • -M — Print summary information in a more computer pars-able format. Specifically, values are printed out in a key/value style. 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 option is used to break down the summary statistics in smaller sample sizes than a complete owp file. This is useful when breaking up very long running sessions.

This option is only used for statistical output, and therefore has no effect on the -R output mode.

Default: Unset. (complete files are treated as the sample size)

  • -n units — units indicates what units time values should be reported in. units is specified using a single character specifying the units wanted.

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. Also, print the names of the files to STDOUT. The files will be saved in the directory specified by the -d option.

The summary filenames are in the 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. The 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.

🌈 ENVIRONMENT VARIABLES 🌈

  • OWAMP_DEBUG_TIMEOFFSET — Offset time by this amount (float)

✨ EXAMPLES ✨

Bestie, this is the part where it gets real — like, actual commands you can type. Every single one is here, no skips, no "etc." 💅

  • owping somehost.com — Run two concurrent ~10-second test sessions at a rate of a packet every 0.1 seconds. One session is sending packets from the local host to somehost.com, the other session is receiving packets from somehost.com. It prints summary statistics of the results only.
  • owping somehost.com:98765 — Same two concurrent test sessions, but pointed at a server running on somehost.com on a non-default port. Port said, port slayed. 🎀
  • owping -u someuser somehost.com — Runs the default test exactly like the first example. You authenticate using the identity someuser, and owping will prompt for a passphrase. (Yes, you have to type it. No, nobody's watching. 🙈)
  • owping -f somehost.com — A single ~10-second test session at a rate of one packet every 0.1 seconds, with the packets being sent from somehost.com and received at the local host. Reverse mode, iconic behaviour. 🦋
  • owping -F from.owp somehost.com — Same as the previous example, except the resulting data gets saved in from.owp. The owstats program can decode that datafile using the same Output options that are available in owping. (Datafile saved = main character energy. 💾👑)
  • owping -F from.owp -T to.owp somehost.com — Runs two concurrent ~10-second test sessions at a rate of a packet every 0.1 seconds. One session sends packets from the local host to somehost.com, the other receives packets from somehost.com. It prints summary statistics of the results and saves the resulting data in from.owp and to.owp. Two files, both slaying. ✨
  • owping -i 1e -c 10 somehost.com — Runs two concurrent ~10-second test sessions at an average rate of 1 packet every second. One session sends packets from the local host to somehost.com, the other receives packets from somehost.com. Prints summary statistics of the results only.
  • owping -i 1f -c 10 somehost.com — Runs two concurrent ~10-second test sessions at a rate of 1 packet every second. One session sends packets from the local host to somehost.com, the other receives packets from somehost.com. Prints summary statistics of the results only.
👀 Lowkey important: 1e is the average rate, 1f is the rate. They look like twins, they are not the same. Don't mix them up or the vibe check will fail.
  • owping -i 1.0e,0f -c 20 somehost.com — Runs two concurrent ~10-second test sessions. It sends back-to-back packet pairs at an average rate of a packet pair every 1 seconds. One session sends packets from the local host to somehost.com, the other receives packets from somehost.com. Prints summary statistics of the results only. Back-to-back pairs?? That's giving efficiency. 🔥

🌸 NOTES 🌸

Okay so real talk for a sec — this one actually matters. 🫶

Using authentication and encryption modes adds extra processing requirements between the fetching of a timestamp and when the packet is sent, and that extra bit is greater for encryption than for authentication. Translation: your crypto is doing homework in the middle of the timestamp, and it shows.

The result? It adds more computational delay to the time reported by OWAMP for each packet. So like, the number you see includes that overhead. Not a bug, just physics-adjacent reality. 💀

🎀 SEE ALSO 🎀

Go read these next, bestie, they're the squad:

💖 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. (Standard disclaimer behaviour, but we respect it. 🫡)

⭐ And that's the whole page, bestie! This fine piece of documentation is owping(1), brought to you by the $Date$ of it all — so like, when you cite it, cite it with the source/version and date from the footer, periodt. Now go ping something and slay. 💅🌈🦋

📦 where this page comes from