src/mans/oping.pod

   1 =head1 NAME
   2
   3 oping - send ICMP ECHO_REQUEST to network hosts
   4
   5 =head1 SYNOPSIS
   6
   7 B<oping> [B<-4> | B<-6>] [B<-c> I<count>] [B<-i> I<interval>] I<host> [I<host> [I<host> ...]]
   8
   9 B<oping> [B<-4> | B<-6>] [B<-c> I<count>] [B<-i> I<interval>] B<-f> I<filename>
  10
  11 B<noping> [B<-4> | B<-6>] [B<-c> I<count>] [B<-i> I<interval>] I<host> [I<host> [I<host> ...]]
  12
  13 B<noping> [B<-4> | B<-6>] [B<-c> I<count>] [B<-i> I<interval>] B<-f> I<filename>
  14
  15 =head1 DESCRIPTION
  16
  17 B<oping> uses ICMPv4 or ICMPv6 ECHO_REQUEST packets to measure a hosts
  18 reachability and the network latency. In contrast to the original L<ping(8)>
  19 utility B<oping> can send ICMP packets to multiple hosts in parallel and wait
  20 for all ECHO_RESPONSE packets to arrive. In contrast to the B<fping> utility
  21 (URL is listed in L<"SEE ALSO">) B<oping> can use both, IPv4 and IPv6
  22 transparently and side by side.
  23
  24 B<noping> is an ncurses-based front-end to I<liboping> which displays ping
  25 statistics online and highlights aberrant round-trip times if the terminal
  26 supports colors.
  27
  28 =head1 OPTIONS
  29
  30 =over 4
  31
  32 =item B<-4>
  33
  34 Force the use of IPv4.
  35
  36 =item B<-6>
  37
  38 Force the use of IPv6.
  39
  40 =item B<-c> I<count>
  41
  42 Send (and receive) I<count> ICMP packets, then stop and exit.
  43
  44 =item B<-i> I<interval>
  45
  46 Send one ICMP packet (per host) each I<interval> seconds. This can be a
  47 floating-point number to specify sub-second precision.
  48
  49 =item B<-w> I<timeout>
  50
  51 Specifies the time to wait for an C<ECHO REPLY> packet before giving up, in
  52 seconds. This can be a floating point number for sub-second precision. Defaults
  53 to B<1.0> seconds.
  54
  55 =item B<-t> I<ttl>
  56
  57 Set the IP Time to Live to I<ttl>. This must be a number between (and
  58 including) 1E<nbsp>andE<nbsp>255. If omitted, the value B<64> is used.
  59
  60 =item B<-I> I<address>
  61
  62 Set the source address to use. You may either specify an IP number or a
  63 hostname. You B<cannot> pass the interface name, as you can with GNU's
  64 L<ping(8)> - use the B<-D> option for that purpose.
  65
  66 =item B<-D> I<interface name>
  67
  68 Set the outgoing network device to use.
  69
  70 =item B<-f> I<filename>
  71
  72 Instead of specifying hostnames on the command line, read them from
  73 I<filename>. If I<filename> is B<->, read from C<STDIN>.
  74
  75 If I<oping> is installed with the SetUID-bit, it will set the effective UID to
  76 the real UID before opening the file. In the special (but common) case that
  77 I<oping> is owned by the super-user (UIDE<nbsp>0), this means that privileges
  78 are temporarily dropped before opening the file, in order to prevent users from
  79 reading arbitrary files on the system.
  80
  81 If your system doesn't provide I<saved set-user IDs> (this was an optional
  82 feature before POSIXE<nbsp>2001), the behavior is different because it is not
  83 possible to I<temporarily> drop privileges. The alternative behavior is: If the
  84 real user ID (as returned by L<getuid(2)>) and the effective user ID (as
  85 returned by L<geteuid(2)>) differ, the only argument allowed for this option is
  86 "-" (i.e. standard input).
  87
  88 =item B<-O> I<filename>
  89
  90 Write measurements in I<Comma Separated Values> (CSV) format to I<filename>.
  91 This option writes three columns per row: wall clock time in (fractional)
  92 seconds since epoch, hostname and the round trip time in milliseconds.
  93
  94 =item B<-Q> I<qos>
  95
  96 Specify the I<Quality of Service> (QoS) for outgoing packets. This is a
  97 somewhat tricky option, since the meaning of the bits in the IPv4 header has
  98 been revised several times.
  99
 100 The currently recommended method is I<Differentiated Services> which is used in
 101 IPv6 headers as well. There are shortcuts for various predefined
 102 I<per-hop behaviors> (PHBs):
 103
 104 =over 4
 105
 106 =item B<be>
 107
 108 Selects the I<Best Effort> behavior. This is the default behavior.
 109
 110 =item B<ef>
 111
 112 Selects the I<Expedited Forwarding> (EF) per-hop behavior, as defined in
 113 I<RFCE<nbsp>3246>. This PHB is characterised by low delay, low loss and low
 114 jitter, i.e. high priority traffic.
 115
 116 =item B<va>
 117
 118 Selects the I<Voice Admitted> (VA) per-hop behavior, as defined in
 119 I<RFCE<nbsp>5865>. This traffic class is meant for I<Voice over IP> (VoIP)
 120 traffic which uses I<Call Admission Control> (CAC) for reserving network
 121 capacity.
 122
 123 =item  B<af>I<c>I<p>
 124
 125 Selects one of 12E<nbsp>differentiated services code points (DSCPs), which are
 126 organized in four I<classes> with three I<priorities> each. Therefore, I<c>
 127 must be a number betweenE<nbsp>1 throughE<nbsp>4 and I<p> must be a number
 128 betweenE<nbsp>1 throughE<nbsp>3, for example "af13", "af22" and "af41". In each
 129 class, the lower priority number takes precedence over the higher priority
 130 number.
 131
 132 =item B<cs>I<n>
 133
 134 Selects one of the eight I<Class Selector> PHBs. I<n> is a number
 135 betweenE<nbsp>0 throughE<nbsp>7. The class selectors have been defined to be
 136 compatible to the I<Precedence> field in the IPv4 header as defined in
 137 I<RFCE<nbsp>791>. Please note that "cs0" is synonymous to "be".
 138
 139 =back
 140
 141 The old definition of the same bits in the IPv4 header was as I<Type of
 142 Service> (ToS) field, specified in I<RFCE<nbsp>1349>. It defined four possible
 143 values which have appropriate aliases. Please note that this use of the bits is
 144 B<deprecated> and the meaning is limited to IPv4!
 145
 146 =over 4
 147
 148 =item B<lowdelay>
 149
 150 Minimize delay
 151
 152 =item B<throughput>
 153
 154 Maximize throughput
 155
 156 =item B<reliability>
 157
 158 Maximize reliability
 159
 160 =item B<mincost>
 161
 162 Minimize monetary cost
 163
 164 =back
 165
 166 Alternatively, you can also specify the byte manually. You can use either a
 167 decimal number (0-255), a hexadecimal number (0x00-0xff) or an octal number
 168 (00-0377) using the usual "0x" and "0" prefixes for hexadecimal and octal
 169 respectively.
 170
 171 The printed lines will contain information about the QoS field of received
 172 packets if either a non-standard QoS setting was used on outgoing packets or if
 173 the QoS byte of incoming packets is not zero. In other words, the QoS
 174 information is omitted if both, the outgoing and the incoming QoS bytes are
 175 zero. The received byte is always interpreted as
 176 I<Differentiated Services Code Point> (DSCP) and
 177 I<Explicit Congestion Notification> (ECN), even if the deprecated
 178 I<Type of Service> (ToS) aliases were used to specify the bits of outgoing
 179 packets.
 180
 181 =item B<-m> I<mark>
 182
 183 I<Linux only> Sets the I<mark> (an integer number) on outgoing packets. This
 184 can be used by L<iptables(8)> and other networking infrastructure for filtering
 185 and routing.
 186
 187 =item B<-u>|B<-U>
 188
 189 I<noping only> B<-u> forces UTF-8 output, B<-U> disables UTF-8 output. If
 190 neither is given, the codeset is automatically determined from the locale.
 191
 192 =item B<-g> B<none>|B<prettyping>|B<boxplot>|B<histogram>
 193
 194 I<noping only> Selects the graph to display.
 195
 196 =over 4
 197
 198 =item B<none>
 199
 200 Do not show a graph.
 201
 202 =item B<prettyping>
 203
 204 Show a graph with time on the x-axis, the y-axis shows the round-trip time.
 205 This is the default graph.
 206
 207 If your terminal supports unicode and colors, they are used to improve
 208 the precision of the data shown: a green box is drawn for round-trip times up
 209 to one third of the configured timeout, the height representing the RTT. Longer
 210 RTTs will start to fill the box yellow (with a green background) and then red
 211 (with a yellow background). Lost packages are drawn as a bold red explamation
 212 mark.
 213
 214 =item B<boxplot>
 215
 216 Show a I<box plot> where the x-axis, i.e. the width of the window, is the
 217 round-trip time. The entire width of the window it the ping interval, set with
 218 the B<-i> option.
 219
 220 The box is sized so it contains 50% of the replies. The vertical line shows the
 221 median. The whiskers are sized to contain 95% of the replies -- 2.5% below the
 222 whiskers and 2.5% above.
 223
 224   |----------[#####|##########]--------------------------------------------|
 225   ^          ^     ^          ^                                            ^
 226  2.5%       25%   50%        75%                                         97.5%
 227
 228 =item B<histogram>
 229
 230 Show a I<histrogram> of the round-trip times. The width of the window is taken
 231 as round-trip time from 0ms on the left to the I<interval> (the B<-i> option,
 232 default 1000ms) on the right.
 233
 234 The height of the graph is scaled so that the most-used buckets vertically fills
 235 the line. The buckets are colored green up to and including the 80th
 236 percentile, yellow up to and including the 95th percentile and red for the
 237 remainder.
 238
 239 =back
 240
 241 =item B<-b>
 242
 243 Audible bell. Print a ASCII BEL character (\a or 0x07) when a packet
 244 is received before the timeout occurs. This can be useful in order to
 245 monitory hosts' connectivity without looking physically at the
 246 console, for example to trace network cables (start audible beep,
 247 disconnect cable N: if beep stops, the cable was in use) or to tell
 248 when a host returns from a reboot.
 249
 250 This relies on the terminal bell to be functional. To enable the
 251 terminal bell, use the following instructions.
 252
 253 =over 4
 254
 255 =item
 256
 257 the visual bell is disabled in your terminal emulator, with the +vb
 258 commandline flag or the following in your .Xresources:
 259
 260  XTerm*visualBell: false
 261
 262 =item
 263
 264 the PC speaker module is loaded in your kernel:
 265
 266  modprobe pcspkr
 267
 268 =item
 269
 270 X11 has the terminal bell enabled:
 271
 272  xset b on; xset b 100
 273
 274 =item
 275
 276 and finally, if you are using PulseAudio, that the module-x11-bell
 277 module is loaded with a pre-loaded sample defined in your pulseaudio
 278 configuration:
 279
 280  load-sample-lazy x11-bell /usr/share/sounds/freedesktop/stereo/complete.oga
 281  load-module module-x11-bell sample=x11-bell
 282
 283 =back
 284
 285 =item B<-P> I<percent>
 286
 287 Configures the latency percentile to report. I<percent> must be a number
 288 between zero and 100, exclusively in both cases. In general, defaults to B<95>.
 289 If B<-c> is given and a number less than 20, this would be the same as the
 290 maximum. In this case the default is chosen so that it excludes the maximum,
 291 e.g. if B<-cE<nbsp>5> is given, the default is I<80>. The calculated percentile
 292 is based on the last 900 packets (15 minutes with the default interval).
 293
 294 =item B<-Z> I<percent>
 295
 296 If any hosts have a drop rate higher than I<percent>, where I<percent> is a
 297 number between zero and 100 inclusively, exit with a non-zero exit status.
 298 Since it is not possible to have a higher drop rate than 100%, passing this
 299 limit will effectively disable the feature (the default). Setting the option to
 300 zero means that the exit status will only be zero if I<all> replies for I<all>
 301 hosts have been received.
 302
 303 The exit status will indicate the number of hosts with more than I<percent>
 304 packets lost, up to a number of 255 failing hosts.
 305
 306 =back
 307
 308 =head1 COLORS
 309
 310 If supported by the terminal, I<noping> will highlight the round-trip times
 311 (RTT) using the colors green, yellow and red. Green signals RTTs that are in
 312 the "expected" range, yellow marks moderately unusual times and times that
 313 differ a lot from the expected value are printed in red.
 314
 315 The information used to categorize round-trip times is the I<percentile>. RTTs
 316 in the 80th percentile are considered to be "normal" and are printed in green.
 317 RTTs within the 95th percentile are considered "moderately unusual" and are
 318 printed in yellow. RTTs above that are considered to be "unusual" and are
 319 printed in red.
 320
 321 =head1 INTERACTIVE KEYBOARD CONTROLS
 322
 323 When running I<noping>, the type of graph being displayed can be
 324 changed by using the B<g> key.  A new host can be added at any time
 325 with the B<a> key.
 326
 327 =head1 SEE ALSO
 328
 329 L<ping(8)>, L<http://fping.org/>, L<liboping(3)>
 330
 331 =head1 LICENSE
 332
 333 I<oping> and I<noping> are licensed under the GPL 2.
 334 No other version of the license is applicable.
 335
 336 =head1 AUTHOR
 337
 338 liboping is written by Florian "octo" Forster E<lt>ff at octo.itE<gt>.
 339 Its homepage can be found at L<http://noping.cc/>.
 340
 341 Copyright (c) 2006-2017 by Florian "octo" Forster.