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 the real user ID (as returned by L<getuid(2)>) and the effective user ID (as
  70 returned by L<geteuid(2)>) differ, the only argument allowed for this option is
  71 "-" (i.E<nbsp>e. standard input). This is meant to avoid security issues when
  72 I<oping> is installed with the SUID-bit.
  73
  74 =item B<-Q> I<qos>
  75
  76 Specify the I<Quality of Service> (QoS) for outgoing packets. This is a
  77 somewhat tricky option, since the meaning of the bits in the IPv4 header has
  78 been revised several times.
  79
  80 The currently recommended method is I<Differentiated Services> which is used in
  81 IPv6 headers as well. There are shortcuts for 13E<nbsp>predefined
  82 I<per-hop behaviors> (PHBs):
  83
  84 =over 4
  85
  86 =item B<be>
  87
  88 Selects the I<Best Effort> behavior. This is the default behavior.
  89
  90 =item B<ef>
  91
  92 Selects the I<Expedited Forwarding> (EF) per-hop behavior, as defined in
  93 I<RFCE<nbsp>3246>. This PHB is characterised by low delay, low loss and low
  94 jitter, i.e. high priority traffic.
  95
  96 =item  B<af>I<c>I<p>
  97
  98 Selects one of 12E<nbsp>differentiated services code points (DSCPs), which are
  99 organized in four I<classes> with three I<priorities> each. Therefore, I<c>
 100 must be a number betweenE<nbsp>1 throughE<nbsp>4 and I<p> must be a number
 101 betweenE<nbsp>1 throughE<nbsp>3, for example "af13", "af22" and "af41". In each
 102 class, the lower priority number takes precedence over the higher priority
 103 number.
 104
 105 =item B<cs>I<n>
 106
 107 Selects one of the eight I<Class Selector> PHBs. I<n> is a number
 108 betweenE<nbsp>0 throughE<nbsp>7. The class selectors have been defined to be
 109 compatible to the I<Precedence> field in the IPv4 header as defined in
 110 I<RFCE<nbsp>791>. Please note that "cs0" is synonymous to "be".
 111
 112 =back
 113
 114 The old definition of the same bits in the IPv4 header was as I<Type of
 115 Service> (ToS) field, specified in I<RFCE<nbsp>1349>. It defined four possible
 116 values which have appropriate aliases. Please note that this use of the bits is
 117 B<deprecated> and the meaning is limited to IPv4!
 118
 119 =over 4
 120
 121 =item B<lowdelay>
 122
 123 Minimize delay
 124
 125 =item B<throughput>
 126
 127 Maximize throughput
 128
 129 =item B<reliability>
 130
 131 Maximize reliability
 132
 133 =item B<mincost>
 134
 135 Minimize monetary cost
 136
 137 =back
 138
 139 Alternatively, you can also specify the byte manually. You can use either a
 140 decimal number (0-255), a hexadecimal number (0x00-0xff) or an octal number
 141 (00-0377) using the usual "0x" and "0" prefixes for hexadecimal and octal
 142 respectively.
 143
 144 The printed lines will contain information about the QoS field of received
 145 packets if either a non-standard QoS setting was used on outgoing packets or if
 146 the QoS byte of incoming packets is not zero. In other words, the QoS
 147 information is omitted if both, the outgoing and the incoming QoS bytes are
 148 zero. The received byte is always interpreted as
 149 I<Differentiated Services Code Point> (DSCP) and
 150 I<Explicit Congestion Notification> (ECN), even if the deprecated
 151 I<Type of Service> (ToS) aliases were used to specify the bits of outgoing
 152 packets.
 153
 154 =back
 155
 156 =head1 COLORS
 157
 158 If supported by the terminal, I<noping> will highlight the round-trip times
 159 (RTT) using the colors green, yellow and red. Green signals RTTs that are in
 160 the "expected" range, yellow marks moderately unusual times and times that
 161 differ a lot from the expected value are printed in red.
 162
 163 The information used to categorize round-trip times is the I<average>
 164 round-trip time and the I<standard deviation>. RTTs that differ from the
 165 average by less than the standard deviation are considered to be "normal" and
 166 are printed in green. Times that differ from the average more than the standard
 167 deviation but less than twice the standard deviation are considered "moderately
 168 unusual" and are printed in yellow. Times differing more than twice the
 169 standard deviation from the average are considered to be "unusual" and are
 170 printed in red.
 171
 172 =head1 SEE ALSO
 173
 174 L<ping(8)>, L<http://www.fping.com/>, L<liboping(3)>
 175
 176 =head1 AUTHOR
 177
 178 liboping is written by Florian octo Forster E<lt>octo at verplant.orgE<gt>.
 179 Its homepage can be found at L<http://verplant.org/liboping/>.
 180
 181 (c) 2005-2010 by Florian octo Forster.