2PING(1)

2ping(1) 🦋 okay bestie, this is the manual page for 2ping, and I'm going to explain it like we're in the group chat 💖 This is part 1 of 2.

✨ NAME ✨

2ping is a bi-directional ping utility, so it's regular ping with main character energy 👑

✨ SYNOPSIS ✨

2ping [options] --listen | host/IP [host/IP [...]]

So you either run it with --listen to be the listener, or you give it one or more hosts/IPs to ping 🫶

✨ DESCRIPTION ✨

okay so 2ping is a bi-directional ping utility 💅 It uses 3-way pings (kinda like TCP's SYN, SYN/ACK, ACK 🦋) and then compares notes after the fact between a 2ping listener and a 2ping client. That's how it figures out which direction the packet loss is happening 🔥

Step one: start a listener on a known stable network host 🏠 The listener's stability should not be in question, bestie 🫶 Why? Because 2ping can tell whether packet loss is inbound or outbound relative to an endpoint, but that won't help you find the cause if both endpoints are sus 💀

Once the listener is up, start 2ping in client mode and tell it to connect to the listener ✨ The two ends start pinging each other and showing network stats. If packet loss happens, 2ping waits a few seconds (default 10, configurable with --inquire-wait) before comparing notes, so it can figure out which direction the loss is going 🧚

To quit on the client or listener end, hit ^C and a list of statistics will pop up 📊 Want a quick inline stats peek without quitting? Hit ^\ or send the process a QUIT signal 🌸

✨ OPTIONS ✨

Ping-compatible options (long option names are 2ping-specific, iykyk) 💜

• --audible, -a — Audible ping 🔊
• --adaptive, -A — Adaptive ping, and this one is lowkey iconic 🔥 The interpacket interval adapts to round-trip time, so effectively there's not more than one unanswered probe on the network (or more, if preload is set). On networks with low rtt, this mode is basically the same as flood mode.
• --count=count, -c count — Stop after sending count ping requests 🛑
• --flood, -f — Flood ping, the most dramatic mode 🌊 For every ping sent, a “.” gets printed, and for every ping received, a backspace gets printed. It's a rapid display of how many pings are getting dropped. If interval isn't given, it sets the interval to zero and outputs pings as fast as they come back or one hundred times per second, whichever is more.

2ping-specific notes: detected outbound and inbound loss show up as “>” and “<”, respectively. Receive errors show up as “E”. Because 2ping is asynchronous, successful responses (backspaces) may overwrite these loss and error characters 😭

• --interval=interval, -i interval — Chill for interval seconds between each ping ⏳ Normally the default is one second between pings, but in flood mode there's no waiting at all.
• --interface-address=address, -I address — Set the source IP address 📍 In listener mode, you can use this option multiple times to bind to multiple IP addresses. In client mode, you can only use it once, and all outbound pings get bound to that source IP.

2ping-specific notes: this option only takes an IP address, not a device name. Also, in listener mode, if the machine has an interface with multiple IP addresses and a request comes in via a sub IP, the reply still leaves via the interface's main IP. So either this option, or (preferred 🫶) listening on all IPs individually via the Python “netifaces” module, must be used if you want to respond via an interface's sub-IP.

• --preload=count, -l count — If specified, 2ping sends that many packets without waiting for a reply 🚀
• --pattern=hex_bytes, -p hex_bytes — You can specify up to 16 “pad” bytes to fill out the packets you send 🧩 This is super useful for diagnosing data-dependent problems in a network. For example, --pattern=ff will fill the sent packet's pad area with all ones.

2ping-specific notes: this pads the portion of the packet that does not contain the active payload data. If the active payload data is larger than the minimum packet size (--min-packet-size), no padding will be sent.

• --quiet, -q — Quiet output 🤫 Nothing is displayed except the summary lines at startup and when finished.
• --packetsize-compat=bytes, -s bytes — ping compatibility moment 🫠 This sets --min-packet-size to this value plus 8 bytes.
• --verbose, -v — Verbose output 📜 In 2ping, this prints decodes of the packets that are sent and received.
• --version, -V — Show the version and exit 🏷️
• --deadline=seconds, -w seconds — Set a timeout, in seconds, before 2ping exits, no matter how many pings have been sent or received ⏰ Due to blocking, this may happen up to one second after the deadline you set.

When port -1 is specified, 2ping picks a random unused high port for you 🦋 This is lowkey perfect for automated unit and functional testing 🧪 but NOT for normal use, bestie 🙈

• --send-monotonic-clock — ✨ Sends a monotonic clock value along with each packet. If the peer sends its own time, you can check it out with --verbose 👀
• --send-random=bytes — 🎲 Sends random data to the peer, up to bytes. The actual amount is capped by other factors too, and can't go past --max-packet-size. If you're gonna use this data for anything trusted, pair it with --auth for HMAC authentication 🔐
• --send-time — ⏰ Sends the host time (wall clock) with each packet. Same deal as above: if the peer sends its time back, --verbose will show it 💅
• --srv — 🌐 In client mode, hostnames get looked up through DNS SRV records. If the SRV query returns multiple record targets, they're ALL pinged in parallel, and priority and weight are not considered 👑 The record's port gets used instead of --port. This needs the dnspython module installed, so make sure it's there first 💖
• --srv-service=service — 🧚 When you're using --srv, this sets the service name for SRV lookups. The default service is 2ping 🌸
• --stats=interval — 📊 Prints a line of brief current statistics every interval seconds. You can also get that same line on demand by hitting ^\ or sending the QUIT signal to the 2ping process ⭐
• --subtract-peer-host-latency — 🫶 If a peer sends its host latency (the time it spends between receiving a packet and sending out a reply), this subtracts it from the RTT calculations. Very precise, very iconic 💜

🐛 BUGS 🐛

None known, many assumed 💀 Iykyk.

✍️ AUTHOR ✍️

2ping was written by Ryan Finnie <ryan@finnie.org> 🎀

👩‍💻 AUTHORS 👩‍💻

Ryan Finnie. The mastermind herself 👑

That's the whole 2PING(1) page, bestie 🦋💖 Go forth and ping things responsibly 💅✨