12PING(1)                             2ping                            2PING(1)
2
3
4

NAME

6       2ping - A bi-directional ping utility
7

SYNOPSIS

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

DESCRIPTION

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
17       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
23       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
30       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

OPTIONS

35       ping-compatible options (long option names are 2ping-specific):
36
37       --audible, -a
38              Audible ping.
39
40       --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
46       --count=count, -c count
47              Stop after sending count ping requests.
48
49       --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
57              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
63       --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
68       --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
74              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
82       --preload=count, -l count
83              If specified, 2ping sends that many packets not waiting for  re‐
84              ply.
85
86       --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
92              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
97       --quiet, -q
98              Quiet  output.  Nothing is displayed except the summary lines at
99              startup time and when finished.
100
101       --packetsize-compat=bytes, -s bytes
102              ping compatibility; this will set --min-packet-size to this plus
103              8 bytes.
104
105       --verbose, -v
106              Verbose  output.   In 2ping, this prints decodes of packets that
107              are sent and received.
108
109       --version, -V
110              Show version and exit.
111
112       --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
117       2ping-specific options:
118
119       --help, -h
120              Print a synposis and exit.
121
122       --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
131       --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
140       --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
145       --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
150       --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
155       --debug
156              Print (lots of) debugging information.
157
158       --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
163       --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
167       --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
173       --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
179       --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
186       --loopback
187              Use  one or more client/listener pairs of UNIX datagram sockets.
188              Mainly for testing purposes.
189
190       --loopback-pairs=pairs
191              Number of pairs to generate when using --loopback.
192
193       --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
198       --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
204       --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
212       --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
217              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
225       --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
231       --no-send-version
232              Do not send the current running version of 2ping with each pack‐
233              et.
234
235       --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
239       --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
246       --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
251              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
255       --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
259       --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
265       --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
269       --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
276       --srv-service=service
277              When  combined  with  --srv,  service  name  to  be used for SRV
278              lookups.  Default service is “2ping”.
279
280       --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
285       --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

BUGS

291       None known, many assumed.
292

AUTHOR

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

AUTHORS

297       Ryan Finnie.
298
299
300
301                                                                      2PING(1)
Impressum