.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" 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" ''
.    ds C`
.    ds C'
'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.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" 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 "OPING 8"
.TH OPING 8 "2017-05-11" "1.10.0" "liboping"
.\" 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"
oping \- send ICMP ECHO_REQUEST to network hosts
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBoping\fR [\fB\-4\fR | \fB\-6\fR] [\fB\-c\fR \fIcount\fR] [\fB\-i\fR \fIinterval\fR] \fIhost\fR [\fIhost\fR [\fIhost\fR ...]]
.PP
\&\fBoping\fR [\fB\-4\fR | \fB\-6\fR] [\fB\-c\fR \fIcount\fR] [\fB\-i\fR \fIinterval\fR] \fB\-f\fR \fIfilename\fR
.PP
\&\fBnoping\fR [\fB\-4\fR | \fB\-6\fR] [\fB\-c\fR \fIcount\fR] [\fB\-i\fR \fIinterval\fR] \fIhost\fR [\fIhost\fR [\fIhost\fR ...]]
.PP
\&\fBnoping\fR [\fB\-4\fR | \fB\-6\fR] [\fB\-c\fR \fIcount\fR] [\fB\-i\fR \fIinterval\fR] \fB\-f\fR \fIfilename\fR
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBoping\fR uses ICMPv4 or ICMPv6 \s-1ECHO_REQUEST\s0 packets to measure a hosts
reachability and the network latency. In contrast to the original \fIping\fR\|(8)
utility \fBoping\fR can send \s-1ICMP\s0 packets to multiple hosts in parallel and wait
for all \s-1ECHO_RESPONSE\s0 packets to arrive. In contrast to the \fBfping\fR utility
(\s-1URL\s0 is listed in \*(L"\s-1SEE ALSO\*(R"\s0) \fBoping\fR can use both, IPv4 and IPv6
transparently and side by side.
.PP
\&\fBnoping\fR is an ncurses-based front-end to \fIliboping\fR which displays ping
statistics online and highlights aberrant round-trip times if the terminal
supports colors.
.SH "OPTIONS"
.IX Header "OPTIONS"
.IP "\fB\-4\fR" 4
.IX Item "-4"
Force the use of IPv4.
.IP "\fB\-6\fR" 4
.IX Item "-6"
Force the use of IPv6.
.IP "\fB\-c\fR \fIcount\fR" 4
.IX Item "-c count"
Send (and receive) \fIcount\fR \s-1ICMP\s0 packets, then stop and exit.
.IP "\fB\-i\fR \fIinterval\fR" 4
.IX Item "-i interval"
Send one \s-1ICMP\s0 packet (per host) each \fIinterval\fR seconds. This can be a
floating-point number to specify sub-second precision.
.IP "\fB\-w\fR \fItimeout\fR" 4
.IX Item "-w timeout"
Specifies the time to wait for an \f(CW\*(C`ECHO REPLY\*(C'\fR packet before giving up, in
seconds. This can be a floating point number for sub-second precision. Defaults
to \fB1.0\fR seconds.
.IP "\fB\-t\fR \fIttl\fR" 4
.IX Item "-t ttl"
Set the \s-1IP\s0 Time to Live to \fIttl\fR. This must be a number between (and
including) 1\ and\ 255. If omitted, the value \fB64\fR is used.
.IP "\fB\-I\fR \fIaddress\fR" 4
.IX Item "-I address"
Set the source address to use. You may either specify an \s-1IP\s0 number or a
hostname. You \fBcannot\fR pass the interface name, as you can with \s-1GNU\s0's
\&\fIping\fR\|(8) \- use the \fB\-D\fR option for that purpose.
.IP "\fB\-D\fR \fIinterface name\fR" 4
.IX Item "-D interface name"
Set the outgoing network device to use.
.IP "\fB\-f\fR \fIfilename\fR" 4
.IX Item "-f filename"
Instead of specifying hostnames on the command line, read them from
\&\fIfilename\fR. If \fIfilename\fR is \fB\-\fR, read from \f(CW\*(C`STDIN\*(C'\fR.
.Sp
If \fIoping\fR is installed with the SetUID-bit, it will set the effective \s-1UID\s0 to
the real \s-1UID\s0 before opening the file. In the special (but common) case that
\&\fIoping\fR is owned by the super-user (\s-1UID\s0\ 0), this means that privileges
are temporarily dropped before opening the file, in order to prevent users from
reading arbitrary files on the system.
.Sp
If your system doesn't provide \fIsaved set-user IDs\fR (this was an optional
feature before \s-1POSIX\s0\ 2001), the behavior is different because it is not
possible to \fItemporarily\fR drop privileges. The alternative behavior is: If the
real user \s-1ID \s0(as returned by \fIgetuid\fR\|(2)) and the effective user \s-1ID \s0(as
returned by \fIgeteuid\fR\|(2)) differ, the only argument allowed for this option is
\&\*(L"\-\*(R" (i.e. standard input).
.IP "\fB\-O\fR \fIfilename\fR" 4
.IX Item "-O filename"
Write measurements in \fIComma Separated Values\fR (\s-1CSV\s0) format to \fIfilename\fR.
This option writes three columns per row: wall clock time in (fractional)
seconds since epoch, hostname and the round trip time in milliseconds.
.IP "\fB\-Q\fR \fIqos\fR" 4
.IX Item "-Q qos"
Specify the \fIQuality of Service\fR (QoS) for outgoing packets. This is a
somewhat tricky option, since the meaning of the bits in the IPv4 header has
been revised several times.
.Sp
The currently recommended method is \fIDifferentiated Services\fR which is used in
IPv6 headers as well. There are shortcuts for various predefined
\&\fIper-hop behaviors\fR (PHBs):
.RS 4
.IP "\fBbe\fR" 4
.IX Item "be"
Selects the \fIBest Effort\fR behavior. This is the default behavior.
.IP "\fBef\fR" 4
.IX Item "ef"
Selects the \fIExpedited Forwarding\fR (\s-1EF\s0) per-hop behavior, as defined in
\&\fI\s-1RFC\s0\ 3246\fR. This \s-1PHB\s0 is characterised by low delay, low loss and low
jitter, i.e. high priority traffic.
.IP "\fBva\fR" 4
.IX Item "va"
Selects the \fIVoice Admitted\fR (\s-1VA\s0) per-hop behavior, as defined in
\&\fI\s-1RFC\s0\ 5865\fR. This traffic class is meant for \fIVoice over \s-1IP\s0\fR (VoIP)
traffic which uses \fICall Admission Control\fR (\s-1CAC\s0) for reserving network
capacity.
.IP "\fBaf\fR\fIc\fR\fIp\fR" 4
.IX Item "afcp"
Selects one of 12\ differentiated services code points (DSCPs), which are
organized in four \fIclasses\fR with three \fIpriorities\fR each. Therefore, \fIc\fR
must be a number between\ 1 through\ 4 and \fIp\fR must be a number
between\ 1 through\ 3, for example \*(L"af13\*(R", \*(L"af22\*(R" and \*(L"af41\*(R". In each
class, the lower priority number takes precedence over the higher priority
number.
.IP "\fBcs\fR\fIn\fR" 4
.IX Item "csn"
Selects one of the eight \fIClass Selector\fR PHBs. \fIn\fR is a number
between\ 0 through\ 7. The class selectors have been defined to be
compatible to the \fIPrecedence\fR field in the IPv4 header as defined in
\&\fI\s-1RFC\s0\ 791\fR. Please note that \*(L"cs0\*(R" is synonymous to \*(L"be\*(R".
.RE
.RS 4
.Sp
The old definition of the same bits in the IPv4 header was as \fIType of
Service\fR (ToS) field, specified in \fI\s-1RFC\s0\ 1349\fR. It defined four possible
values which have appropriate aliases. Please note that this use of the bits is
\&\fBdeprecated\fR and the meaning is limited to IPv4!
.IP "\fBlowdelay\fR" 4
.IX Item "lowdelay"
Minimize delay
.IP "\fBthroughput\fR" 4
.IX Item "throughput"
Maximize throughput
.IP "\fBreliability\fR" 4
.IX Item "reliability"
Maximize reliability
.IP "\fBmincost\fR" 4
.IX Item "mincost"
Minimize monetary cost
.RE
.RS 4
.Sp
Alternatively, you can also specify the byte manually. You can use either a
decimal number (0\-255), a hexadecimal number (0x00\-0xff) or an octal number
(00\-0377) using the usual \*(L"0x\*(R" and \*(L"0\*(R" prefixes for hexadecimal and octal
respectively.
.Sp
The printed lines will contain information about the QoS field of received
packets if either a non-standard QoS setting was used on outgoing packets or if
the QoS byte of incoming packets is not zero. In other words, the QoS
information is omitted if both, the outgoing and the incoming QoS bytes are
zero. The received byte is always interpreted as
\&\fIDifferentiated Services Code Point\fR (\s-1DSCP\s0) and
\&\fIExplicit Congestion Notification\fR (\s-1ECN\s0), even if the deprecated
\&\fIType of Service\fR (ToS) aliases were used to specify the bits of outgoing
packets.
.RE
.IP "\fB\-m\fR \fImark\fR" 4
.IX Item "-m mark"
\&\fILinux only\fR Sets the \fImark\fR (an integer number) on outgoing packets. This
can be used by \fIiptables\fR\|(8) and other networking infrastructure for filtering
and routing.
.IP "\fB\-u\fR|\fB\-U\fR" 4
.IX Item "-u|-U"
\&\fInoping only\fR \fB\-u\fR forces \s-1UTF\-8\s0 output, \fB\-U\fR disables \s-1UTF\-8\s0 output. If
neither is given, the codeset is automatically determined from the locale.
.IP "\fB\-g\fR \fBnone\fR|\fBprettyping\fR|\fBboxplot\fR|\fBhistogram\fR" 4
.IX Item "-g none|prettyping|boxplot|histogram"
\&\fInoping only\fR Selects the graph to display.
.RS 4
.IP "\fBnone\fR" 4
.IX Item "none"
Do not show a graph.
.IP "\fBprettyping\fR" 4
.IX Item "prettyping"
Show a graph with time on the x\-axis, the y\-axis shows the round-trip time.
This is the default graph.
.Sp
If your terminal supports unicode and colors, they are used to improve
the precision of the data shown: a green box is drawn for round-trip times up
to one third of the configured timeout, the height representing the \s-1RTT.\s0 Longer
RTTs will start to fill the box yellow (with a green background) and then red
(with a yellow background). Lost packages are drawn as a bold red explamation
mark.
.IP "\fBboxplot\fR" 4
.IX Item "boxplot"
Show a \fIbox plot\fR where the x\-axis, i.e. the width of the window, is the
round-trip time. The entire width of the window it the ping interval, set with
the \fB\-i\fR option.
.Sp
The box is sized so it contains 50% of the replies. The vertical line shows the
median. The whiskers are sized to contain 95% of the replies \*(-- 2.5% below the
whiskers and 2.5% above.
.Sp
.Vb 3
\&  |\-\-\-\-\-\-\-\-\-\-[#####|##########]\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-|
\&  ^          ^     ^          ^                                            ^
\& 2.5%       25%   50%        75%                                         97.5%
.Ve
.IP "\fBhistogram\fR" 4
.IX Item "histogram"
Show a \fIhistrogram\fR of the round-trip times. The width of the window is taken
as round-trip time from 0ms on the left to the \fIinterval\fR (the \fB\-i\fR option,
default 1000ms) on the right.
.Sp
The height of the graph is scaled so that the most-used buckets vertically fills
the line. The buckets are colored green up to and including the 80th
percentile, yellow up to and including the 95th percentile and red for the
remainder.
.RE
.RS 4
.RE
.IP "\fB\-b\fR" 4
.IX Item "-b"
Audible bell. Print a \s-1ASCII BEL\s0 character (\ea or 0x07) when a packet
is received before the timeout occurs. This can be useful in order to
monitory hosts' connectivity without looking physically at the
console, for example to trace network cables (start audible beep,
disconnect cable N: if beep stops, the cable was in use) or to tell
when a host returns from a reboot.
.Sp
This relies on the terminal bell to be functional. To enable the
terminal bell, use the following instructions.
.RS 4
.IP "\(bu" 4
the visual bell is disabled in your terminal emulator, with the +vb
commandline flag or the following in your .Xresources:
.Sp
.Vb 1
\& XTerm*visualBell: false
.Ve
.IP "\(bu" 4
the \s-1PC\s0 speaker module is loaded in your kernel:
.Sp
.Vb 1
\& modprobe pcspkr
.Ve
.IP "\(bu" 4
X11 has the terminal bell enabled:
.Sp
.Vb 1
\& xset b on; xset b 100
.Ve
.IP "\(bu" 4
and finally, if you are using PulseAudio, that the module\-x11\-bell
module is loaded with a pre-loaded sample defined in your pulseaudio
configuration:
.Sp
.Vb 2
\& load\-sample\-lazy x11\-bell /usr/share/sounds/freedesktop/stereo/complete.oga
\& load\-module module\-x11\-bell sample=x11\-bell
.Ve
.RE
.RS 4
.RE
.IP "\fB\-P\fR \fIpercent\fR" 4
.IX Item "-P percent"
Configures the latency percentile to report. \fIpercent\fR must be a number
between zero and 100, exclusively in both cases. In general, defaults to \fB95\fR.
If \fB\-c\fR is given and a number less than 20, this would be the same as the
maximum. In this case the default is chosen so that it excludes the maximum,
e.g. if \fB\-c\ 5\fR is given, the default is \fI80\fR. The calculated percentile
is based on the last 900 packets (15 minutes with the default interval).
.IP "\fB\-Z\fR \fIpercent\fR" 4
.IX Item "-Z percent"
If any hosts have a drop rate higher than \fIpercent\fR, where \fIpercent\fR is a
number between zero and 100 inclusively, exit with a non-zero exit status.
Since it is not possible to have a higher drop rate than 100%, passing this
limit will effectively disable the feature (the default). Setting the option to
zero means that the exit status will only be zero if \fIall\fR replies for \fIall\fR
hosts have been received.
.Sp
The exit status will indicate the number of hosts with more than \fIpercent\fR
packets lost, up to a number of 255 failing hosts.
.SH "COLORS"
.IX Header "COLORS"
If supported by the terminal, \fInoping\fR will highlight the round-trip times
(\s-1RTT\s0) using the colors green, yellow and red. Green signals RTTs that are in
the \*(L"expected\*(R" range, yellow marks moderately unusual times and times that
differ a lot from the expected value are printed in red.
.PP
The information used to categorize round-trip times is the \fIpercentile\fR. RTTs
in the 80th percentile are considered to be \*(L"normal\*(R" and are printed in green.
RTTs within the 95th percentile are considered \*(L"moderately unusual\*(R" and are
printed in yellow. RTTs above that are considered to be \*(L"unusual\*(R" and are
printed in red.
.SH "INTERACTIVE KEYBOARD CONTROLS"
.IX Header "INTERACTIVE KEYBOARD CONTROLS"
When running \fInoping\fR, the type of graph being displayed can be
changed by using the \fBg\fR key.  A new host can be added at any time
with the \fBa\fR key.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIping\fR\|(8), <http://fping.org/>, \fIliboping\fR\|(3)
.SH "LICENSE"
.IX Header "LICENSE"
\&\fIoping\fR and \fInoping\fR are licensed under the \s-1GPL 2.\s0
No other version of the license is applicable.
.SH "AUTHOR"
.IX Header "AUTHOR"
liboping is written by Florian \*(L"octo\*(R" Forster <ff at octo.it>.
Its homepage can be found at <http://noping.cc/>.
.PP
Copyright (c) 2006\-2017 by Florian \*(L"octo\*(R" Forster.