.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "2PING 8"
.TH 2PING 8 "2012-04-22" "" ""
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
2ping \- A bi\-directional ping client/listener
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fB2ping\fR [\ \fBoptions\fR\ ] \fB\-\-listen\fR\ |\ \fIhost/IP\fR
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fB2ping\fR is a bi-directional ping utility.  It uses 3\-way pings (akin to 
\&\s-1TCP\s0 \s-1SYN\s0, \s-1SYN/ACK\s0, \s-1ACK\s0) and after-the-fact state comparison between a 
2ping listener and a 2ping client to determine which direction 
packet loss occurs.
.PP
To use 2ping, start a listener on a known stable network host.  The 
relative network stability of the 2ping listener host should not be in 
question, because while 2ping can determine whether packet loss is 
occurring inbound or outbound relative to an endpoint, that will not 
help you determine the cause if both of the endpoints are in question.
.PP
Once the listener is started, start 2ping in client mode and tell it to 
connect to the listener.  The ends will begin pinging each other and 
displaying network statistics.  If packet loss occurs, 2ping will wait a 
few seconds (default 10, configurable with \-w) before comparing notes 
between the two endpoints to determine which direction the packet loss 
is occurring.
.PP
To quit 2ping on the client or listener ends, enter ^C, and a list of 
statistics will be displayed.  To get a short inline display of 
statistics without quitting, send the process a \s-1QUIT\s0 signal (yes, that's 
the opposite of what you would think, but it's in line with the normal 
ping utility).
.SH "OPTIONS"
.IX Header "OPTIONS"
\&\fBping\fR\-compatible options:
.IP "\fB\-a\fR" 4
.IX Item "-a"
Audible ping.
.IP "\fB\-A\fR" 4
.IX Item "-A"
Adaptive ping.  A new client ping request is sent as soon as a client ping response is received.  If a ping response is not received within the interval period, a new ping request is sent.  Minimal interval is 200msec for not super-user.  On networks with low rtt this mode is essentially equivalent to flood mode.
.Sp
\&\fB2ping\fR\-specific notes: This behavior is somewhat different to the nature of \fBping\fR's adaptive ping, but the result is roughly the same.
.IP "\fB\-c\fR \fIcount\fR" 4
.IX Item "-c count"
Stop after sending \fIcount\fR ping requests.
.Sp
\&\fB2ping\fR\-specific notes: This option behaves slightly differently from \fBping\fR.  If both \fB\-c\fR and \fB\-w\fR are specified, satisfaction of \fB\-c\fR will cause an exit first.  Also, internally, \fB2ping\fR exits just before sending \fIcount\fR+1 pings, to give time for the ping to complete.
.IP "\fB\-f\fR" 4
.IX Item "-f"
Flood ping. For every ping sent a period \*(L".\*(R" is printed, while for ever ping received a backspace is printed. This provides a rapid display of how many pings are being dropped.  If interval is not given, it sets interval to zero and outputs pings as fast as they come back or one hundred times per second, whichever is more.  Only the super-user may use this option with zero interval.
.Sp
\&\fB2ping\fR\-specific notes: Detected outbound/inbound loss responses are printed as \*(L">\*(R" and \*(L"<\*(R", respectively.  Receive errors are printed as \*(L"E\*(R".  Due to the asynchronous nature of \fB2ping\fR, successful responses (backspaces) may overwrite these loss and error characters.
.IP "\fB\-i\fR \fIinterval\fR" 4
.IX Item "-i interval"
Wait \fIinterval\fR seconds between sending each ping.  The default is to wait for one second between each ping normally, or not to wait in flood mode.  Only super-user may set interval to values less 0.2 seconds.
.IP "\fB\-I\fR \fIinterface \s-1IP\s0\fR" 4
.IX Item "-I interface IP"
Set source \s-1IP\s0 address.  When pinging IPv6 link-local address this option is required.  When in listener mode, this option may be specified multiple to bind to multiple \s-1IP\s0 addresses.  When in client mode, this option may only be specified once, and all outbound pings will be bound to this source \s-1IP\s0.
.Sp
\&\fB2ping\fR\-specific notes: This option only takes an \s-1IP\s0 address, not a device name.  Note that in listener mode, if the machine has an interface with multiple \s-1IP\s0 addresses and an request comes in via a sub \s-1IP\s0, the reply still leaves via the interface's main \s-1IP\s0.  So this option must be used if you would like to respond via an interface's sub-IP.
.IP "\fB\-l\fR \fIpreload\fR" 4
.IX Item "-l preload"
If \fIpreload\fR is specified, \fB2ping\fR sends that many packets not waiting for reply.  Only the super-user may select preload more than 3.
.IP "\fB\-p\fR \fIpattern\fR" 4
.IX Item "-p pattern"
You may specify up to 16 \*(L"pad\*(R" bytes to fill out the packets you send.  This is useful for diagnosing data-dependent problems in a network.  For example, \fB\-p ff\fR will cause the sent packet pad area to be filled with all ones.
.Sp
\&\fB2ping\fR\-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 (\fB\-\-min\-packet\-size\fR=\fImin\fR), no padding will be sent.
.IP "\fB\-q\fR" 4
.IX Item "-q"
Quiet output.  Nothing is displayed except the summary lines at startup time and when finished.
.IP "\fB\-s\fR \fIpacketsize\fR" 4
.IX Item "-s packetsize"
\&\fBping\fR compatibility, this will set \fB\-\-min\-packet\-size\fR to this plus 8 bytes.
.IP "\fB\-v\fR" 4
.IX Item "-v"
Verbose output.  In \fB2ping\fR, this prints decodes of packets that are sent and received.
.IP "\fB\-V\fR" 4
.IX Item "-V"
Show version and exit.
.IP "\fB\-w\fR \fIdeadline\fR" 4
.IX Item "-w deadline"
Specify a timeout, in seconds, before \fB2ping\fR exits regardless of how many pings have been sent or received.  Due to blocking, this may occur up to one second after the deadline specified.
.Sp
\&\fB2ping\fR\-specific notes: This option behaves slightly differently from \fBping\fR.  If both \fB\-c\fR and \fB\-w\fR are specified, satisfaction of \fB\-c\fR will cause an exit first.
.PP
\&\fB2ping\fR\-specific options:
.IP "\fB\-?\fR, \fB\-\-help\fR" 4
.IX Item "-?, --help"
Print a synposis and exit.
.IP "\fB\-6\fR, \fB\-\-ipv6\fR" 4
.IX Item "-6, --ipv6"
Bind/connect as IPv6.
.IP "\fB\-\-auth\fR=\fIkey\fR" 4
.IX Item "--auth=key"
Set a shared key, send cryptographic hashes with each packet, and require cryptographic hashes from peer packets signed with the same shared key.
.IP "\fB\-\-auth\-digest\fR=\fIdigest\fR" 4
.IX Item "--auth-digest=digest"
When \fB\-\-auth\fR is used, specify the digest type to compute the cryptographic hash.  Valid options are \fBhmac\-md5\fR (default), \fBhmac\-sha1\fR and \fBhmac\-sha256\fR.  hmac\-md5 requires \fBDigest::MD5\fR, and the \s-1SHA\s0 digests require \fBDigest::SHA\fR.
.IP "\fB\-\-debug\fR" 4
.IX Item "--debug"
Print (lots of) debugging information.
.IP "\fB\-\-inquire\-wait\fR=\fIsecs\fR" 4
.IX Item "--inquire-wait=secs"
Wait at least \fIsecs\fR seconds before inquiring about a lost packet.  Default is 10 seconds.  \s-1UDP\s0 packets can arrive delayed or out of order, so it is best to give it some time before inquiring about a lost packet.
.IP "\fB\-\-listen\fR" 4
.IX Item "--listen"
Start as a listener.  The listener will not send out ping requests at regular intervals, and will instead wait for the far end to initiate ping requests.  A listener is required as the remote end for a client.
.IP "\fB\-\-min\-packet\-size\fR=\fImin\fR" 4
.IX Item "--min-packet-size=min"
Set the minimum total payload size to \fImin\fR bytes, default 128.  If the payload is smaller than \fImin\fR bytes, padding will be added to the end of the packet.
.IP "\fB\-\-max\-packet\-size\fR=\fImax\fR" 4
.IX Item "--max-packet-size=max"
Set the maximum total payload size to \fImax\fR bytes, default 512, absolute minimum 64.  If the payload is larger than \fImax\fR bytes, information will be rearranged and sent in future packets when possible.
.IP "\fB\-\-no\-3way\fR" 4
.IX Item "--no-3way"
Do not perform 3\-way pings.  Used most often when combined with \fB\-\-listen\fR, as the listener is usually the one to determine whether a ping reply should become a 3\-way ping.
.Sp
Strictly speaking, a 3\-way ping is not necessary for determining directional packet loss between the client and the listener.  However, the extra leg of the 3\-way ping allows for extra chances to determine packet loss more efficiently.  Also, with 3\-way ping disabled, the listener will receive no client performance indicators, nor will the listener be able to determine directional packet loss that it detects.
.IP "\fB\-\-no\-match\-packet\-size\fR" 4
.IX Item "--no-match-packet-size"
When sending replies, 2ping will try to match the packet size of the received packet by adding padding if necessary, but will not exceed \fB\-\-max\-packet\-size\fR.  \fB\-\-no\-match\-packet\-size\fR disabled this behavior, always setting the minimum to \fB\-\-min\-packet\-size\fR.
.IP "\fB\-\-no\-send\-version\fR" 4
.IX Item "--no-send-version"
Do not send the current running version of 2ping with each packet.
.IP "\fB\-\-notice\fR=\fItext\fR" 4
.IX Item "--notice=text"
Arbitrary notice text to send with each packet.  If the remote peer supports it, this may be displayed to the user.
.IP "\fB\-\-packet\-loss\fR=\fIout:in\fR" 4
.IX Item "--packet-loss=out:in"
Simulate random packet loss outbound and inbound.  For example, \fI25:10\fR means a 25% chance of not sending a packet, and a 10% chance of ignoring a received packet.  A single number without colon separation means use the same percentage for both outbound and inbound.
.IP "\fB\-\-port\fR=\fIport\fR" 4
.IX Item "--port=port"
Use \s-1UDP\s0 port \fIport\fR.  With \fB\-\-listen\fR, this is the port to bind as, otherwise this is the port to send to.  Default is \s-1UDP\s0 port 15998.
.IP "\fB\-\-stats\fR=\fIinterval\fR" 4
.IX Item "--stats=interval"
Print a line of brief current statistics every \fIinterval\fR seconds.  The same line can be printed on demand by sending \s-1SIGQUIT\s0 to the 2ping process.
.SH "BUGS"
.IX Header "BUGS"
There are probably lots and lots and lots of unknown bugs.
.PP
By default, source \s-1IP\s0 logic doesn't work as expected, see \fB\-I\fR for details.  There appears to be no way to peg the source \s-1IP\s0 of reply \s-1UDP\s0 packets to the destination of the packet that is being replied to.  As a result, packets always go out the interface's main \s-1IP\s0 address if not specified manually.  (Please, prove the author wrong.)
.PP
This manpage isn't finished yet, and may never be.
.SH "AUTHOR"
.IX Header "AUTHOR"
\&\fB2ping\fR was written by Ryan Finnie <ryan@finnie.org>.
