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 --all-interfaces must be  used  if
79              you would like to respond via an interface's sub-IP.
80
81       --preload=count, -l count
82              If  specified, 2ping sends that many packets not waiting for re‐
83              ply.
84
85       --pattern=hex_bytes, -p hex_bytes
86              You may specify up to 16 "pad" bytes to fill out the packets you
87              send.   This is useful for diagnosing data-dependent problems in
88              a network.  For example, --pattern=ff will cause the sent packet
89              pad area to be filled with all ones.
90
91              2ping-specific  notes:  This pads the portion of the packet that
92              does not contain the active payload data.  If the active payload
93              data is larger than the minimum packet size (--min-packet-size),
94              no padding will be sent.
95
96       --quiet, -q
97              Quiet output.  Nothing is displayed except the summary lines  at
98              startup time and when finished.
99
100       --packetsize-compat=bytes, -s bytes
101              ping compatibility; this will set --min-packet-size to this plus
102              8 bytes.
103
104       --verbose, -v
105              Verbose output.  In 2ping, this prints decodes of  packets  that
106              are sent and received.
107
108       --version, -V
109              Show version and exit.
110
111       --deadline=seconds, -w seconds
112              Specify  a timeout, in seconds, before 2ping exits regardless of
113              how many pings have been sent or  received.   Due  to  blocking,
114              this may occur up to one second after the deadline specified.
115
116       2ping-specific options:
117
118       --help, -h
119              Print a synposis and exit.
120
121       --ipv4, -4
122              Limit  binds to IPv4.  In client mode, this forces resolution of
123              dual-homed hostnames to the IPv4 address.   (Without  --ipv4  or
124              --ipv6, the first result will be used as specified by your oper‐
125              ating system, usually the  AAAA  address  on  IPv6-routable  ma‐
126              chines,  or  the  A  address on IPv4-only machines.) In listener
127              mode, this filters out any non-IPv4  --interface-address  binds,
128              either through hostname resolution or explicit passing.
129
130       --ipv6, -6
131              Limit  binds to IPv6.  In client mode, this forces resolution of
132              dual-homed hostnames to the IPv6 address.  (Without  -4  or  -6,
133              the  first  result  will  be used as specified by your operating
134              system, usually the AAAA address on IPv6-routable  machines,  or
135              the  A  address  on  IPv4-only machines.) In listener mode, this
136              filters  out  any  non-IPv6  --interface-address  binds,  either
137              through hostname resolution or explicit passing.
138
139       --all-interfaces
140              In  listener  mode,  listen on all possible interface addresses.
141              If used, this will override  any  addresses  given  by  --inter‐
142              face-address.   This functionality requires the netifaces module
143              to be installed.
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 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       --min-packet-size=min
187              Set  the  minimum  total payload size to min bytes, default 128.
188              If the payload is smaller than min bytes, padding will be  added
189              to the end of the packet.
190
191       --max-packet-size=max
192              Set  the  maximum  total payload size to max bytes, default 512,
193              absolute minimum 64.  If the payload is larger than  max  bytes,
194              information  will  be rearranged and sent in future packets when
195              possible.
196
197       --nagios=wrta,wloss%,crta,closs%
198              Produce output suitable for use in a Nagios check.   If  --count
199              is not specified, defaults to 5 pings.  A warning condition (ex‐
200              it code 1) will be returned if average RTT exceeds wrta or  ping
201              loss exceeds wloss%.  A critical condition (exit code 2) will be
202              returned if average  RTT  exceeds  crta  or  ping  loss  exceeds
203              closs%.
204
205       --no-3way
206              Do  not perform 3-way pings.  Used most often when combined with
207              --listen, as the  listener  is  usually  the  one  to  determine
208              whether a ping reply should become a 3-way ping.
209
210              Strictly speaking, a 3-way ping is not necessary for determining
211              directional packet loss between the  client  and  the  listener.
212              However,  the  extra  leg  of  the  3-way  ping allows for extra
213              chances to determine packet loss more efficiently.   Also,  with
214              3-way ping disabled, the listener will receive no client perfor‐
215              mance indicators, nor will the listener be able to determine di‐
216              rectional packet loss that it detects.
217
218       --no-match-packet-size
219              When sending replies, 2ping will try to match the packet size of
220              the received packet by adding padding if necessary, but will not
221              exceed  --max-packet-size.  --no-match-packet-size disables this
222              behavior, always setting the minimum to --min-packet-size.
223
224       --no-send-version
225              Do not send the current running version of 2ping with each pack‐
226              et.
227
228       --notice=text
229              Send arbitrary notice text with each packet.  If the remote peer
230              supports it, this may be displayed to the user.
231
232       --packet-loss=out:in
233              Simulate random packet loss outbound and inbound.  For  example,
234              25:10  means  a  25%  chance  of not sending a packet, and a 10%
235              chance of ignoring a received packet.  A single  number  without
236              colon separation means use the same percentage for both outbound
237              and inbound.
238
239       --port=port
240              Use UDP port port, either a numeric port  number  or  a  service
241              name string.  With --listen, this is the port to bind as, other‐
242              wise this is the port to send to.  Default is UDP port 15998.
243
244       --send-monotonic-clock
245              Send a monotonic clock value with each packet.   Peer  time  (if
246              sent  by the peer) can be viewed with --verbose.  Only supported
247              if the system is capable of generating a monotonic clock.
248
249       --send-random=bytes
250              Send random data to the peer, up to bytes.  The number of  bytes
251              will  be  limited by other factors, up to --max-packet-size.  If
252              this data is to be used for trusted purposes, it should be  com‐
253              bined with --auth for HMAC authentication.
254
255       --send-time
256              Send the host time (wall clock) with each packet.  Peer time (if
257              sent by the peer) can be viewed with --verbose.
258
259       --srv  In client mode, causes hostnames to be looked  up  via  DNS  SRV
260              records.  If the SRV query returns multiple record targets, they
261              will all be pinged in parallel; priority and weight are not con‐
262              sidered.   The  record's  port  will  be used instead of --port.
263              This functionality requires  the  dnspython  module  to  be  in‐
264              stalled.
265
266       --srv-service=service
267              When  combined  with  --srv,  service  name  to  be used for SRV
268              lookups.  Default service is "2ping".
269
270       --stats=interval
271              Print a line of brief current statistics every interval seconds.
272              The same line can be printed on demand by entering ^\ or sending
273              the QUIT signal to the 2ping process.
274

BUGS

276       None known, many assumed.
277

AUTHOR

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

AUTHORS

282       Ryan Finnie.
283
284
285
286                                                                      2PING(1)
Impressum