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<-Q> I<qos>
  89
  90 Specify the I<Quality of Service> (QoS) for outgoing packets. This is a
  91 somewhat tricky option, since the meaning of the bits in the IPv4 header has
  92 been revised several times.
  93
  94 The currently recommended method is I<Differentiated Services> which is used in
  95 IPv6 headers as well. There are shortcuts for various predefined
  96 I<per-hop behaviors> (PHBs):
  97
  98 =over 4
  99
 100 =item B<be>
 101
 102 Selects the I<Best Effort> behavior. This is the default behavior.
 103
 104 =item B<ef>
 105
 106 Selects the I<Expedited Forwarding> (EF) per-hop behavior, as defined in
 107 I<RFCE<nbsp>3246>. This PHB is characterised by low delay, low loss and low
 108 jitter, i.e. high priority traffic.
 109
 110 =item B<va>
 111
 112 Selects the I<Voice Admitted> (VA) per-hop behavior, as defined in
 113 I<RFCE<nbsp>5865>. This traffic class is meant for I<Voice over IP> (VoIP)
 114 traffic which uses I<Call Admission Control> (CAC) for reserving network
 115 capacity.
 116
 117 =item  B<af>I<c>I<p>
 118
 119 Selects one of 12E<nbsp>differentiated services code points (DSCPs), which are
 120 organized in four I<classes> with three I<priorities> each. Therefore, I<c>
 121 must be a number betweenE<nbsp>1 throughE<nbsp>4 and I<p> must be a number
 122 betweenE<nbsp>1 throughE<nbsp>3, for example "af13", "af22" and "af41". In each
 123 class, the lower priority number takes precedence over the higher priority
 124 number.
 125
 126 =item B<cs>I<n>
 127
 128 Selects one of the eight I<Class Selector> PHBs. I<n> is a number
 129 betweenE<nbsp>0 throughE<nbsp>7. The class selectors have been defined to be
 130 compatible to the I<Precedence> field in the IPv4 header as defined in
 131 I<RFCE<nbsp>791>. Please note that "cs0" is synonymous to "be".
 132
 133 =back
 134
 135 The old definition of the same bits in the IPv4 header was as I<Type of
 136 Service> (ToS) field, specified in I<RFCE<nbsp>1349>. It defined four possible
 137 values which have appropriate aliases. Please note that this use of the bits is
 138 B<deprecated> and the meaning is limited to IPv4!
 139
 140 =over 4
 141
 142 =item B<lowdelay>
 143
 144 Minimize delay
 145
 146 =item B<throughput>
 147
 148 Maximize throughput
 149
 150 =item B<reliability>
 151
 152 Maximize reliability
 153
 154 =item B<mincost>
 155
 156 Minimize monetary cost
 157
 158 =back
 159
 160 Alternatively, you can also specify the byte manually. You can use either a
 161 decimal number (0-255), a hexadecimal number (0x00-0xff) or an octal number
 162 (00-0377) using the usual "0x" and "0" prefixes for hexadecimal and octal
 163 respectively.
 164
 165 The printed lines will contain information about the QoS field of received
 166 packets if either a non-standard QoS setting was used on outgoing packets or if
 167 the QoS byte of incoming packets is not zero. In other words, the QoS
 168 information is omitted if both, the outgoing and the incoming QoS bytes are
 169 zero. The received byte is always interpreted as
 170 I<Differentiated Services Code Point> (DSCP) and
 171 I<Explicit Congestion Notification> (ECN), even if the deprecated
 172 I<Type of Service> (ToS) aliases were used to specify the bits of outgoing
 173 packets.
 174
 175 =item B<-m> I<mark>
 176
 177 I<Linux only> Sets the I<mark> (an integer number) on outgoing packets. This
 178 can be used by L<iptables(8)> and other networking infrastructure for filtering
 179 and routing.
 180
 181 =item B<-u>|B<-U>
 182
 183 I<noping only> B<-u> forces UTF-8 output, B<-U> disables UTF-8 output. If
 184 neither is given, the codeset is automatically determined from the locale.
 185
 186 =item B<-g> B<none>|B<prettyping>|B<boxplot>|B<histogram>
 187
 188 I<noping only> Selects the graph to display.
 189
 190 =over 4
 191
 192 =item B<none>
 193
 194 Do not show a graph.
 195
 196 =item B<prettyping>
 197
 198 Show a graph with time on the x-axis, the y-axis shows the round-trip time.
 199 This is the default graph.
 200
 201 If your terminal supports unicode and colors, they are used to improve
 202 the precision of the data shown: a green box is drawn for round-trip times up
 203 to one third of the configured timeout, the height representing the RTT. Longer
 204 RTTs will start to fill the box yellow (with a green background) and then red
 205 (with a yellow background). Lost packages are drawn as a bold red explamation
 206 mark.
 207
 208 =item B<boxplot>
 209
 210 Show a I<box plot> where the x-axis, i.e. the width of the window, is the
 211 round-trip time. The entire width of the window it the ping interval, set with
 212 the B<-i> option.
 213
 214 The box is sized so it contains 50% of the replies. The vertical line shows the
 215 median. The whiskers are sized to contain 95% of the replies -- 2.5% below the
 216 whiskers and 2.5% above.
 217
 218   |----------[#####|##########]--------------------------------------------|
 219   ^          ^     ^          ^                                            ^
 220  2.5%       25%   50%        75%                                         97.5%
 221
 222 =item B<histogram>
 223
 224 Show a I<histrogram> of the round-trip times. The width of the window is taken
 225 as round-trip time from 0ms on the left to the I<interval> (the B<-i> option,
 226 default 1000ms) on the right.
 227
 228 The height of the graph is scaled so that the most-used buckets vertically fills
 229 the line. The buckets are colored green up to and including the 80th
 230 percentile, yellow up to and including the 95th percentile and red for the
 231 remainder.
 232
 233 =back
 234
 235 =item B<-P> I<percent>
 236
 237 Configures the latency percentile to report. I<percent> must be a number
 238 between zero and 100, exclusively in both cases. In general, defaults to B<95>.
 239 If B<-c> is given and a number less than 20, this would be the same as the
 240 maximum. In this case the default is chosen so that it excludes the maximum,
 241 e.g. if B<-cE<nbsp>5> is given, the default is I<80>. The calculated percentile
 242 is based on the last 900 packets (15 minutes with the default interval).
 243
 244 =item B<-Z> I<percent>
 245
 246 If any hosts have a drop rate higher than I<percent>, where I<percent> is a
 247 number between zero and 100 inclusively, exit with a non-zero exit status.
 248 Since it is not possible to have a higher drop rate than 100%, passing this
 249 limit will effectively disable the feature (the default). Setting the option to
 250 zero means that the exit status will only be zero if I<all> replies for I<all>
 251 hosts have been received.
 252
 253 The exit status will indicate the number of hosts with more than I<percent>
 254 packets lost, up to a number of 255 failing hosts.
 255
 256 =back
 257
 258 =head1 COLORS
 259
 260 If supported by the terminal, I<noping> will highlight the round-trip times
 261 (RTT) using the colors green, yellow and red. Green signals RTTs that are in
 262 the "expected" range, yellow marks moderately unusual times and times that
 263 differ a lot from the expected value are printed in red.
 264
 265 The information used to categorize round-trip times is the I<percentile>. RTTs
 266 in the 80th percentile are considered to be "normal" and are printed in green.
 267 RTTs within the 95th percentile are considered "moderately unusual" and are
 268 printed in yellow. RTTs above that are considered to be "unusual" and are
 269 printed in red.
 270
 271 =head1 SEE ALSO
 272
 273 L<ping(8)>, L<http://fping.org/>, L<liboping(3)>
 274
 275 =head1 AUTHOR
 276
 277 liboping is written by Florian "octo" Forster E<lt>ff at octo.itE<gt>.
 278 Its homepage can be found at L<http://noping.cc/>.
 279
 280 Copyright (c) 2005-2011 by Florian "octo" Forster.