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<va>
  97
  98 Selects the I<Voice Admitted> (VA) per-hop behavior, as defined in
  99 I<RFCE<nbsp>5865>. This traffic class is meant for I<Voice over IP> (VoIP)
 100 traffic which uses I<Call Admission Control> (CAC) for reserving network
 101 capacity.
 102
 103 =item  B<af>I<c>I<p>
 104
 105 Selects one of 12E<nbsp>differentiated services code points (DSCPs), which are
 106 organized in four I<classes> with three I<priorities> each. Therefore, I<c>
 107 must be a number betweenE<nbsp>1 throughE<nbsp>4 and I<p> must be a number
 108 betweenE<nbsp>1 throughE<nbsp>3, for example "af13", "af22" and "af41". In each
 109 class, the lower priority number takes precedence over the higher priority
 110 number.
 111
 112 =item B<cs>I<n>
 113
 114 Selects one of the eight I<Class Selector> PHBs. I<n> is a number
 115 betweenE<nbsp>0 throughE<nbsp>7. The class selectors have been defined to be
 116 compatible to the I<Precedence> field in the IPv4 header as defined in
 117 I<RFCE<nbsp>791>. Please note that "cs0" is synonymous to "be".
 118
 119 =back
 120
 121 The old definition of the same bits in the IPv4 header was as I<Type of
 122 Service> (ToS) field, specified in I<RFCE<nbsp>1349>. It defined four possible
 123 values which have appropriate aliases. Please note that this use of the bits is
 124 B<deprecated> and the meaning is limited to IPv4!
 125
 126 =over 4
 127
 128 =item B<lowdelay>
 129
 130 Minimize delay
 131
 132 =item B<throughput>
 133
 134 Maximize throughput
 135
 136 =item B<reliability>
 137
 138 Maximize reliability
 139
 140 =item B<mincost>
 141
 142 Minimize monetary cost
 143
 144 =back
 145
 146 Alternatively, you can also specify the byte manually. You can use either a
 147 decimal number (0-255), a hexadecimal number (0x00-0xff) or an octal number
 148 (00-0377) using the usual "0x" and "0" prefixes for hexadecimal and octal
 149 respectively.
 150
 151 The printed lines will contain information about the QoS field of received
 152 packets if either a non-standard QoS setting was used on outgoing packets or if
 153 the QoS byte of incoming packets is not zero. In other words, the QoS
 154 information is omitted if both, the outgoing and the incoming QoS bytes are
 155 zero. The received byte is always interpreted as
 156 I<Differentiated Services Code Point> (DSCP) and
 157 I<Explicit Congestion Notification> (ECN), even if the deprecated
 158 I<Type of Service> (ToS) aliases were used to specify the bits of outgoing
 159 packets.
 160
 161 =back
 162
 163 =head1 COLORS
 164
 165 If supported by the terminal, I<noping> will highlight the round-trip times
 166 (RTT) using the colors green, yellow and red. Green signals RTTs that are in
 167 the "expected" range, yellow marks moderately unusual times and times that
 168 differ a lot from the expected value are printed in red.
 169
 170 The information used to categorize round-trip times is the I<average>
 171 round-trip time and the I<standard deviation>. RTTs that differ from the
 172 average by less than the standard deviation are considered to be "normal" and
 173 are printed in green. Times that differ from the average more than the standard
 174 deviation but less than twice the standard deviation are considered "moderately
 175 unusual" and are printed in yellow. Times differing more than twice the
 176 standard deviation from the average are considered to be "unusual" and are
 177 printed in red.
 178
 179 =head1 SEE ALSO
 180
 181 L<ping(8)>, L<http://www.fping.com/>, L<liboping(3)>
 182
 183 =head1 AUTHOR
 184
 185 liboping is written by Florian octo Forster E<lt>octo at verplant.orgE<gt>.
 186 Its homepage can be found at L<http://verplant.org/liboping/>.
 187
 188 (c) 2005-2010 by Florian octo Forster.