SSHPING(8)

💅 SSHPING(8) — the ssh-based ping test utility ✨

okay so bestie, welcome to sshping(8) — yes it's a whole manual section, yes she's iconic. Quick vibe check: this page lives in section 8 of the manual, and the utility itself is described as an ssh-based ping test utility. Now let's get into it 🫶

---

🌸 NAME 🌸

sshping — measure character-echo latency and bandwidth for an interactive ssh session. no cap, that's the whole job 💖

---

🦋 SYNOPSIS 🦋

sshping [options] [user@]addr[:port]

---

✨ DESCRIPTION ✨

sshping is an SSH-based, ping-like utility that measures interactive character echo latency and file transfer upload/download throughput. literally ping but make it ssh 💅

and before you ask: it's pronounced "shipping" 🚢 (iykyk)

---

🎀 PARAMETERS 🎀

• user — the username you log in to the remote system as. if you leave it out, it defaults to the current username on your local system, so it's giving "i'm me and that's the vibe" 💁‍♀️
• addr — the IP name or address of the target system. the main character of the whole operation 👑
• port — the tcp port number for the ssh daemon on the target system. it must be a number — service names like "ssh" are not supported, so don't try it, she will not be amused 💀. default is 22.

---

⭐ OPTIONS ⭐

short and long forms of options take the same arguments as shown. no funny business, same arguments either way 🫡

• -b, --bindaddr IP — bind to this source address 📍
• -c, --count NCHARS — number of characters to echo, default 1000 🔢
• -d, --delimited — use delimiters in big numbers, e.g. 1,234,567 — so your eyes don't fall out reading raw nanoseconds 🙈
• -e, --echocmd CMD — use CMD for the echo command; default: cat > /dev/null. for the character echo test, this command is issued to the remote system (sshping adds the newline) so that anything "typed" is echoed back. cute, right? 🐚
• -f, --config-file F — read and parse the ssh configuration file F for options. ⚠️ depending upon which version of libssh you have, you may not see any error if the file F is missing or had bad syntax. so you should check for the existance of file F in your script before passing it here — fr fr, do the check. see ssh_config(5) for details of the file's contents. default is ~/.ssh/config 📄
• -h, --help — print usage and exit. the classic "what does anything do" button 🙋‍♀️
• -H, --human-readable — use flesh-friendly units 🍓 (yes, flesh-friendly. she said what she said.)
• -i, --identity FILE — identity file, ie ssh private keyfile 🔑 keep it secret, keep it safe
• -p, --password PWD — use password PWD (can be seen, use with care) 👀 bestie that's a whole security caveat, treat it with respect
• -P, --ping-summary — append measurements in ping-like round-trip-time line format, e.g. rtt min/avg/max/mdev = 1.371/2.095/2.505/0.389 ms 📊
• -r, --runtests e|s — run these tests, e=echo, s=speed; default es=both. pick your fighter or run 'em both 💪
• -s, --size MB — for the transfer speed test (the scp test), send/receive MB megabytes; default=8 MB 📦
• -t, --time SECS — time limit for the echo test. we'll stop the test soon after this number of seconds, or the --couont number of characters, whichever comes first. (yes, --couont. treasure the typo, she's canon now 💀) timing starts after the ssh login and shell creation ⏱️
• -v, --verbose — show more output, use twice for lots: -vv 🗣️🗣️
• -z, --remote FILE — path and name of a remote file that we can write to, for the upload test; and that we will read back, for the download test. the default is to create the 1MB dummy file /tmp/sshping-PID.tmp and repreatedly transfer that file --size times 🔁

---

👑 OUTPUT FIELDS 👑

🔌 Connection

ssh-Login-Time

Time in nanoseconds to establish the tcp network connection, authenticate, and form the ssh session, then start an ssh channel, launch a remote shell, login to the remote system and read back any logon banners. ⏳

if an interactive password is needed to login, the time to supply the password is included as well — so type fast! 🏃‍♀️💨

💬 Character Echo Tests

The character echo test issues a single byte to the remote system, then waits for it to be echoed back. It checks that the returned character is correct, then notes the wallclock time elapsed for the round-trip. This is repeated with a different character until either the test time limit is expired or the character count limit is reached. 🔄

Since only a subset of the printable ASCII character set is used, bytes == characters. one byte, one character, no math needed 🧮

Minimum-Latency

Fastest (lowest) round-trip time for a character echo, in nanoseconds. the speedrun champion 🥇

Median-Latency

The median round-trip time for a character echo. The median is not the same as the average; think of this as the "typical" latency. You probably want this number when you think average. 👀 yes bestie, this is the one you actually want

Average-Latency

The average (mean) round-trip time for a character echo, in nanoseconds. 📈

Average-Deviation

The standard deviation on the average latency. It quantifies how varied the latency is for each character's echo. A lower number indicates a tighter grouping of latencies, a higher number indicates more variation in the latencies. "One" standard deviation is the average plus or minus this amount. 🎢 lowkey the drama meter for your network

Maximum-Latency

The slowest (highest) round-trip time for a character echo, in nanoseconds. the one that made you go "girl what happened" 😭

Echo-Count

The number of bytes echoed during the test. 🔢

🚀 Transfer Speed Test

The file transfer speed test measures the upload and download throughput rate, in bytes per second (Bps), using the scp subsystem. This is the subsystem typically used when copying files over ssh. 📁

For the upload test, a random 1MB file is copied to the target system ("uploads" it), measuring the time required for the transfer. The file is repeatedly copied to get transfer sizes greater than 1MB as given by --size. By default the target file is /tmp/sshping-PID.tmp but this can be changed with --remote. ⬆️

For the download test, the file just-uploaded is copied down repeatedly, 1MB at a time, as-if it were separate files to simulate downloading multiple files. The --size value again is used to determine the number of copies pulled. ⬇️ (yes, "as-if". she's doing her best 💅)

Upload-Size

Number of bytes uploaded during the test. 📤

Upload-Rate

Throughput speed for the upload transfer, in Bytes/second. 🏎️

Download-Size

Number of bytes downloaded during the test. 📥

Download-Rate

Throughput speed for the download transfer, in Bytes/second. 🛬

---

🌈 EXAMPLES 🌈

here's what it looks like when she eats and leaves no crumbs 🔥

# bin/sshping -d cheyenne.example.com
ssh-Login-Time:      1,835,377,610 ns
Minimum-Latency:           548,993 ns
Median-Latency:            698,494 ns
Average-Latency:           704,123 ns
Average-Deviation:          72,839 ns
Maximum-Latency:         1,075,017 ns
Echo-Count:                  1,000 B
Upload-Size:             8,000,000 B
Upload-Rate:             9,371,579 B/s
Download-Size:           8,000,000 B
Download-Rate:           5,493,034 B/s

like, look at those commas slaying thanks to -d 🎀

---

🧚 AUTHOR 🧚

Written by Uncle Spook. https://github.com/spook/sshping — give the icon a follow, periodt 💜

---

📜 LICENSE 📜

Copyright (c) 2017-2019 by Uncle Spook

MIT License

Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

---

aaand that's the page, bestie 🫶 this edition of the sshping manual is v0.1.4, dated 2018-03-13, so she's vintage and we love her for it. go measure some latency, you absolute icon 👑💖