12PING(1) 2ping 2PING(1)
2
6 2ping - A bi-directional ping utility
7
9 2ping [options] --listen | host/IP [host/IP [...]]
10
12 2ping is a bi-directional ping utility. It uses 3-way pings (akin to
13 TCP SYN, SYN/ACK, ACK) and after-the-fact state comparison between a
14 2ping listener and a 2ping client to determine which direction packet
15 loss occurs.
16 To use 2ping, start a listener on a known stable network host. The
18 relative network stability of the 2ping listener host should not be in
19 question, because while 2ping can determine whether packet loss is oc‐
20 curring inbound or outbound relative to an endpoint, that will not help
21 you determine the cause if both of the endpoints are in question.
22 Once the listener is started, start 2ping in client mode and tell it to
24 connect to the listener. The ends will begin pinging each other and
25 displaying network statistics. If packet loss occurs, 2ping will wait
26 a few seconds (default 10, configurable with --inquire-wait) before
27 comparing notes between the two endpoints to determine which direction
28 the packet loss is occurring.
29 To quit 2ping on the client or listener ends, enter ^C, and a list of
31 statistics will be displayed. To get a short inline display of statis‐
32 tics without quitting, enter ^\ or send the process a QUIT signal.
33
35 ping-compatible options (long option names are 2ping-specific):
36 --audible, -a
38 Audible ping.
39 --adaptive, -A
41 Adaptive ping. Interpacket interval adapts to round-trip time,
42 so that effectively not more than one (or more, if preload is
43 set) unanswered probe is present in the network. On networks
44 with low rtt this mode is essentially equivalent to flood mode.
45 --count=count, -c count
47 Stop after sending count ping requests.
48 --flood, -f
50 Flood ping. For every ping sent a period “.” is printed, while
51 for ever ping received a backspace is printed. This provides a
52 rapid display of how many pings are being dropped. If interval
53 is not given, it sets interval to zero and outputs pings as fast
54 as they come back or one hundred times per second, whichever is
55 more.
56 2ping-specific notes: Detected outbound/inbound loss responses
58 are printed as “>” and “<”, respectively. Receive errors are
59 printed as “E”. Due to the asynchronous nature of 2ping, suc‐
60 cessful responses (backspaces) may overwrite these loss and er‐
61 ror characters.
62 --interval=interval, -i interval
64 Wait interval seconds between sending each ping. The default is
65 to wait for one second between each ping normally, or not to
66 wait in flood mode.
67 --interface-address=address, -I address
69 Set source IP address. When in listener mode, this option may
70 be specified multiple to bind to multiple IP addresses. When in
71 client mode, this option may only be specified once, and all
72 outbound pings will be bound to this source IP.
73 2ping-specific notes: This option only takes an IP address, not
75 a device name. Note that in listener mode, if the machine has
76 an interface with multiple IP addresses and an request comes in
77 via a sub IP, the reply still leaves via the interface’s main
78 IP. So either this option – or (preferred) listening on all IPs
79 individually via the Python “netifaces” module – must be used if
80 you would like to respond via an interface’s sub-IP.
81 --preload=count, -l count
83 If specified, 2ping sends that many packets not waiting for re‐
84 ply.
85 --pattern=hex_bytes, -p hex_bytes
87 You may specify up to 16 “pad” bytes to fill out the packets you
88 send. This is useful for diagnosing data-dependent problems in
89 a network. For example, --pattern=ff will cause the sent packet
90 pad area to be filled with all ones.
91 2ping-specific notes: This pads the portion of the packet that
93 does not contain the active payload data. If the active payload
94 data is larger than the minimum packet size (--min-packet-size),
95 no padding will be sent.
96 --quiet, -q
98 Quiet output. Nothing is displayed except the summary lines at
99 startup time and when finished.
100 --packetsize-compat=bytes, -s bytes
102 ping compatibility; this will set --min-packet-size to this plus
103 8 bytes.
104 --verbose, -v
106 Verbose output. In 2ping, this prints decodes of packets that
107 are sent and received.
108 --version, -V
110 Show version and exit.
111 --deadline=seconds, -w seconds
113 Specify a timeout, in seconds, before 2ping exits regardless of
114 how many pings have been sent or received. Due to blocking,
115 this may occur up to one second after the deadline specified.
116 2ping-specific options:
118 --help, -h
120 Print a synposis and exit.
121 --ipv4, -4
123 Limit binds to IPv4. In client mode, this forces resolution of
124 dual-homed hostnames to the IPv4 address. (Without --ipv4 or
125 --ipv6, the first result will be used as specified by your oper‐
126 ating system, usually the AAAA address on IPv6-routable ma‐
127 chines, or the A address on IPv4-only machines.) In listener
128 mode, this filters out any non-IPv4 --interface-address binds,
129 either through hostname resolution or explicit passing.
130 --ipv6, -6
132 Limit binds to IPv6. In client mode, this forces resolution of
133 dual-homed hostnames to the IPv6 address. (Without -4 or -6,
134 the first result will be used as specified by your operating
135 system, usually the AAAA address on IPv6-routable machines, or
136 the A address on IPv4-only machines.) In listener mode, this
137 filters out any non-IPv6 --interface-address binds, either
138 through hostname resolution or explicit passing.
139 --all-interfaces
141 Deprecated. In listener mode, all addresses will be listened to
142 by default if the Python “netifaces” module is installed, unless
143 overridden by one or more --interface-address invocations.
144 --auth=key
146 Set a shared key, send cryptographic hashes with each packet,
147 and require cryptographic hashes from peer packets signed with
148 the same shared key.
149 --auth-digest=digest
151 When --auth is used, specify the digest type to compute the
152 cryptographic hash. Valid options are hmac-md5 (default),
153 hmac-sha1, hmac-sha256 and hmac-sha512.
154 --debug
156 Print (lots of) debugging information.
157 --encrypt=key
159 Set a shared key, encrypt 2ping packets, and require encrypted
160 packets from peers encrypted with the same shared key. Requires
161 the PyCryptodome or PyCrypto module.
162 --encrypt-method=method
164 When --encrypt is used, specify the method used to encrypt pack‐
165 ets. Valid options are hkdf-aes256-cbc (default).
166 --fuzz=percent
168 Simulate corruption of incoming packets, with a percent proba‐
169 bility each bit will be flipped. After fuzzing, the packet
170 checksum will be recalculated, and then the checksum itself will
171 be fuzzed (but at a lower probability).
172 --inquire-wait=secs
174 Wait at least secs seconds before inquiring about a lost packet.
175 Default is 10 seconds. UDP packets can arrive delayed or out of
176 order, so it is best to give it some time before inquiring about
177 a lost packet.
178 --listen
180 Start as a listener. The listener will not send out ping re‐
181 quests at regular intervals, and will instead wait for the far
182 end to initiate ping requests. A listener is required as the
183 remote end for a client. When run as a listener, a SIGHUP will
184 reload the configuration on all interfaces.
185 --loopback
187 Use one or more client/listener pairs of UNIX datagram sockets.
188 Mainly for testing purposes.
189 --loopback-pairs=pairs
191 Number of pairs to generate when using --loopback.
192 --min-packet-size=min
194 Set the minimum total payload size to min bytes, default 128.
195 If the payload is smaller than min bytes, padding will be added
196 to the end of the packet.
197 --max-packet-size=max
199 Set the maximum total payload size to max bytes, default 512,
200 absolute minimum 64. If the payload is larger than max bytes,
201 information will be rearranged and sent in future packets when
202 possible.
203 --nagios=wrta,wloss%,crta,closs%
205 Produce output suitable for use in a Nagios check. If --count
206 is not specified, defaults to 5 pings. A warning condition (ex‐
207 it code 1) will be returned if average RTT exceeds wrta or ping
208 loss exceeds wloss%. A critical condition (exit code 2) will be
209 returned if average RTT exceeds crta or ping loss exceeds
210 closs%.
211 --no-3way
213 Do not perform 3-way pings. Used most often when combined with
214 --listen, as the listener is usually the one to determine
215 whether a ping reply should become a 3-way ping.
216 Strictly speaking, a 3-way ping is not necessary for determining
218 directional packet loss between the client and the listener.
219 However, the extra leg of the 3-way ping allows for extra
220 chances to determine packet loss more efficiently. Also, with
221 3-way ping disabled, the listener will receive no client perfor‐
222 mance indicators, nor will the listener be able to determine di‐
223 rectional packet loss that it detects.
224 --no-match-packet-size
226 When sending replies, 2ping will try to match the packet size of
227 the received packet by adding padding if necessary, but will not
228 exceed --max-packet-size. --no-match-packet-size disables this
229 behavior, always setting the minimum to --min-packet-size.
230 --no-send-version
232 Do not send the current running version of 2ping with each pack‐
233 et.
234 --notice=text
236 Send arbitrary notice text with each packet. If the remote peer
237 supports it, this may be displayed to the user.
238 --packet-loss=out:in
240 Simulate random packet loss outbound and inbound. For example,
241 25:10 means a 25% chance of not sending a packet, and a 10%
242 chance of ignoring a received packet. A single number without
243 colon separation means use the same percentage for both outbound
244 and inbound.
245 --port=port
247 Use UDP port port, either a numeric port number or a service
248 name string. With --listen, this is the port to bind as, other‐
249 wise this is the port to send to. Default is UDP port 15998.
250 When port “-1” is specified, a random unused high port is
252 picked. This is useful for automated unit and functional test‐
253 ing, but not for normal use.
254 --send-monotonic-clock
256 Send a monotonic clock value with each packet. Peer time (if
257 sent by the peer) can be viewed with --verbose.
258 --send-random=bytes
260 Send random data to the peer, up to bytes. The number of bytes
261 will be limited by other factors, up to --max-packet-size. If
262 this data is to be used for trusted purposes, it should be com‐
263 bined with --auth for HMAC authentication.
264 --send-time
266 Send the host time (wall clock) with each packet. Peer time (if
267 sent by the peer) can be viewed with --verbose.
268 --srv In client mode, causes hostnames to be looked up via DNS SRV
270 records. If the SRV query returns multiple record targets, they
271 will all be pinged in parallel; priority and weight are not con‐
272 sidered. The record’s port will be used instead of --port.
273 This functionality requires the dnspython module to be in‐
274 stalled.
275 --srv-service=service
277 When combined with --srv, service name to be used for SRV
278 lookups. Default service is “2ping”.
279 --stats=interval
281 Print a line of brief current statistics every interval seconds.
282 The same line can be printed on demand by entering ^\ or sending
283 the QUIT signal to the 2ping process.
284 --subtract-peer-host-latency
286 If a peer sends its host latency (the amount of time it spends
287 between receiving a packet and sending out a reply), subtract it
288 from RTT calculations.
289
291 None known, many assumed.
292
294 2ping was written by Ryan Finnie <ryan@finnie.org>.
295
297 Ryan Finnie.
298 2PING(1)