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<-t> I<ttl>
  50
  51 Set the IP Time to Live to I<ttl>. This must be a number between (and
  52 including) 1E<nbsp>andE<nbsp>255. If omitted, the value B<64> is used.
  53
  54 =item B<-I> I<address>
  55
  56 Set the source address to use. You may either specify an IP number or a
  57 hostname. You B<cannot> pass the interface name, as you can with GNU's
  58 L<ping(8)> - use the B<-D> option for that purpose.
  59
  60 =item B<-D> I<interface name>
  61
  62 Set the outgoing network device to use.
  63
  64 =item B<-f> I<filename>
  65
  66 Instead of specifying hostnames on the command line, read them from
  67 I<filename>. If I<filename> is B<->, read from C<STDIN>.
  68
  69 If I<oping> is installed with the SetUID-bit, it will set the effective UID to
  70 the real UID before opening the file. In the special (but common) case that
  71 I<oping> is owned by the super-user (UIDE<nbsp>0), this means that privileges
  72 are temporarily dropped before opening the file, in order to prevent users from
  73 reading arbitrary files on the system.
  74
  75 If your system doesn't provide I<saved set-user IDs> (this was an optional
  76 feature before POSIXE<nbsp>2001), the behavior is different because it is not
  77 possible to I<temporarily> drop privileges. The alternative behavior is: If the
  78 real user ID (as returned by L<getuid(2)>) and the effective user ID (as
  79 returned by L<geteuid(2)>) differ, the only argument allowed for this option is
  80 "-" (i.e. standard input).
  81
  82 =item B<-Q> I<qos>
  83
  84 Specify the I<Quality of Service> (QoS) for outgoing packets. This is a
  85 somewhat tricky option, since the meaning of the bits in the IPv4 header has
  86 been revised several times.
  87
  88 The currently recommended method is I<Differentiated Services> which is used in
  89 IPv6 headers as well. There are shortcuts for various predefined
  90 I<per-hop behaviors> (PHBs):
  91
  92 =over 4
  93
  94 =item B<be>
  95
  96 Selects the I<Best Effort> behavior. This is the default behavior.
  97
  98 =item B<ef>
  99
 100 Selects the I<Expedited Forwarding> (EF) per-hop behavior, as defined in
 101 I<RFCE<nbsp>3246>. This PHB is characterised by low delay, low loss and low
 102 jitter, i.e. high priority traffic.
 103
 104 =item B<va>
 105
 106 Selects the I<Voice Admitted> (VA) per-hop behavior, as defined in
 107 I<RFCE<nbsp>5865>. This traffic class is meant for I<Voice over IP> (VoIP)
 108 traffic which uses I<Call Admission Control> (CAC) for reserving network
 109 capacity.
 110
 111 =item  B<af>I<c>I<p>
 112
 113 Selects one of 12E<nbsp>differentiated services code points (DSCPs), which are
 114 organized in four I<classes> with three I<priorities> each. Therefore, I<c>
 115 must be a number betweenE<nbsp>1 throughE<nbsp>4 and I<p> must be a number
 116 betweenE<nbsp>1 throughE<nbsp>3, for example "af13", "af22" and "af41". In each
 117 class, the lower priority number takes precedence over the higher priority
 118 number.
 119
 120 =item B<cs>I<n>
 121
 122 Selects one of the eight I<Class Selector> PHBs. I<n> is a number
 123 betweenE<nbsp>0 throughE<nbsp>7. The class selectors have been defined to be
 124 compatible to the I<Precedence> field in the IPv4 header as defined in
 125 I<RFCE<nbsp>791>. Please note that "cs0" is synonymous to "be".
 126
 127 =back
 128
 129 The old definition of the same bits in the IPv4 header was as I<Type of
 130 Service> (ToS) field, specified in I<RFCE<nbsp>1349>. It defined four possible
 131 values which have appropriate aliases. Please note that this use of the bits is
 132 B<deprecated> and the meaning is limited to IPv4!
 133
 134 =over 4
 135
 136 =item B<lowdelay>
 137
 138 Minimize delay
 139
 140 =item B<throughput>
 141
 142 Maximize throughput
 143
 144 =item B<reliability>
 145
 146 Maximize reliability
 147
 148 =item B<mincost>
 149
 150 Minimize monetary cost
 151
 152 =back
 153
 154 Alternatively, you can also specify the byte manually. You can use either a
 155 decimal number (0-255), a hexadecimal number (0x00-0xff) or an octal number
 156 (00-0377) using the usual "0x" and "0" prefixes for hexadecimal and octal
 157 respectively.
 158
 159 The printed lines will contain information about the QoS field of received
 160 packets if either a non-standard QoS setting was used on outgoing packets or if
 161 the QoS byte of incoming packets is not zero. In other words, the QoS
 162 information is omitted if both, the outgoing and the incoming QoS bytes are
 163 zero. The received byte is always interpreted as
 164 I<Differentiated Services Code Point> (DSCP) and
 165 I<Explicit Congestion Notification> (ECN), even if the deprecated
 166 I<Type of Service> (ToS) aliases were used to specify the bits of outgoing
 167 packets.
 168
 169 =item B<-u>|B<-U>
 170
 171 I<noping only> B<-u> forces UTF-8 output, B<-U> disables UTF-8 output. If
 172 neither is given, the codeset is automatically determined from the locale.
 173
 174 =item B<-Z> I<percent>
 175
 176 If any hosts have a drop rate higher than I<percent>, where I<percent> is a
 177 number between zero and 100 inclusively, exit with a non-zero exit status.
 178 Since it is not possible to have a higher drop rate than 100%, passing this
 179 limit will effectively disable the feature (the default). Setting the option to
 180 zero means that the exit status will only be zero if I<all> replies for I<all>
 181 hosts have been received.
 182
 183 The exit status will indicate the number of hosts with more than I<percent>
 184 packets lost, up to a number of 255 failing hosts.
 185
 186 =back
 187
 188 =head1 COLORS
 189
 190 If supported by the terminal, I<noping> will highlight the round-trip times
 191 (RTT) using the colors green, yellow and red. Green signals RTTs that are in
 192 the "expected" range, yellow marks moderately unusual times and times that
 193 differ a lot from the expected value are printed in red.
 194
 195 The information used to categorize round-trip times is the I<average>
 196 round-trip time and the I<standard deviation>. RTTs that differ from the
 197 average by less than the standard deviation are considered to be "normal" and
 198 are printed in green. Times that differ from the average more than the standard
 199 deviation but less than twice the standard deviation are considered "moderately
 200 unusual" and are printed in yellow. Times differing more than twice the
 201 standard deviation from the average are considered to be "unusual" and are
 202 printed in red.
 203
 204 =head1 SEE ALSO
 205
 206 L<ping(8)>, L<http://www.fping.com/>, L<liboping(3)>
 207
 208 =head1 AUTHOR
 209
 210 liboping is written by Florian "octo" Forster E<lt>ff at octo.itE<gt>.
 211 Its homepage can be found at L<http://verplant.org/liboping/>.
 212
 213 Copyright (c) 2005-2011 by Florian "octo" Forster.