X-Git-Url: https://git.tokkee.org/?p=liboping.git;a=blobdiff_plain;f=src%2Fmans%2Foping.pod;h=5a90ce70f83bfe5e4865b379b91f0acff06ab452;hp=b005b32c55258a72b7550e232ef6b479821f5d77;hb=48bdd3100dd26d2c6b7e9c3683a2e1a98fc53f2f;hpb=34e8ca25fda9b46a058d3307d1c545e1da853014 diff --git a/src/mans/oping.pod b/src/mans/oping.pod index b005b32..5a90ce7 100644 --- a/src/mans/oping.pod +++ b/src/mans/oping.pod @@ -8,14 +8,22 @@ B [B<-4> | B<-6>] [B<-c> I] [B<-i> I] I [I [ B [B<-4> | B<-6>] [B<-c> I] [B<-i> I] B<-f> I +B [B<-4> | B<-6>] [B<-c> I] [B<-i> I] I [I [I ...]] + +B [B<-4> | B<-6>] [B<-c> I] [B<-i> I] B<-f> I + =head1 DESCRIPTION -oping uses ICMPv4 or ICMPv6 ECHO_REQUEST packets to measure a hosts +B uses ICMPv4 or ICMPv6 ECHO_REQUEST packets to measure a hosts reachability and the network latency. In contrast to the original L utility B can send ICMP packets to multiple hosts in parallel and wait -for all ECHO_RESPONSE packets to arrive. In contrast to the -B utility (URL is listed in L<"SEE ALSO">) B can use both, IPv4 -and IPv6 transparently and side by side. +for all ECHO_RESPONSE packets to arrive. In contrast to the B utility +(URL is listed in L<"SEE ALSO">) B can use both, IPv4 and IPv6 +transparently and side by side. + +B is an ncurses-based front-end to I which displays ping +statistics online and highlights aberrant round-trip times if the terminal +supports colors. =head1 OPTIONS @@ -23,7 +31,7 @@ and IPv6 transparently and side by side. =item B<-4> -Force the use of IPv4. +Force the use of IPv4. =item B<-6> @@ -38,6 +46,12 @@ Send (and receive) I ICMP packets, then stop and exit. Send one ICMP packet (per host) each I seconds. This can be a floating-point number to specify sub-second precision. +=item B<-w> I + +Specifies the time to wait for an C packet before giving up, in +seconds. This can be a floating point number for sub-second precision. Defaults +to B<1.0> seconds. + =item B<-t> I Set the IP Time to Live to I. This must be a number between (and @@ -58,20 +72,270 @@ Set the outgoing network device to use. Instead of specifying hostnames on the command line, read them from I. If I is B<->, read from C. -If the real user ID (as returned by L) and the effective user ID (as +If I is installed with the SetUID-bit, it will set the effective UID to +the real UID before opening the file. In the special (but common) case that +I is owned by the super-user (UIDE0), this means that privileges +are temporarily dropped before opening the file, in order to prevent users from +reading arbitrary files on the system. + +If your system doesn't provide I (this was an optional +feature before POSIXE2001), the behavior is different because it is not +possible to I drop privileges. The alternative behavior is: If the +real user ID (as returned by L) and the effective user ID (as returned by L) differ, the only argument allowed for this option is -"-" (i.Ee. standard input). This is meant to avoid security issues when -I is installed with the SUID-bit. +"-" (i.e. standard input). + +=item B<-O> I + +Write measurements in I (CSV) format to I. +This option writes three columns per row: wall clock time in (fractional) +seconds since epoch, hostname and the round trip time in milliseconds. + +=item B<-Q> I + +Specify the I (QoS) for outgoing packets. This is a +somewhat tricky option, since the meaning of the bits in the IPv4 header has +been revised several times. + +The currently recommended method is I which is used in +IPv6 headers as well. There are shortcuts for various predefined +I (PHBs): + +=over 4 + +=item B + +Selects the I behavior. This is the default behavior. + +=item B + +Selects the I (EF) per-hop behavior, as defined in +I3246>. This PHB is characterised by low delay, low loss and low +jitter, i.e. high priority traffic. + +=item B + +Selects the I (VA) per-hop behavior, as defined in +I5865>. This traffic class is meant for I (VoIP) +traffic which uses I (CAC) for reserving network +capacity. + +=item BII

+ +Selects one of 12Edifferentiated services code points (DSCPs), which are +organized in four I with three I each. Therefore, I +must be a number betweenE1 throughE4 and I

must be a number +betweenE1 throughE3, for example "af13", "af22" and "af41". In each +class, the lower priority number takes precedence over the higher priority +number. + +=item BI + +Selects one of the eight I PHBs. I is a number +betweenE0 throughE7. The class selectors have been defined to be +compatible to the I field in the IPv4 header as defined in +I791>. Please note that "cs0" is synonymous to "be". =back +The old definition of the same bits in the IPv4 header was as I (ToS) field, specified in I1349>. It defined four possible +values which have appropriate aliases. Please note that this use of the bits is +B and the meaning is limited to IPv4! + +=over 4 + +=item B + +Minimize delay + +=item B + +Maximize throughput + +=item B + +Maximize reliability + +=item B + +Minimize monetary cost + +=back + +Alternatively, you can also specify the byte manually. You can use either a +decimal number (0-255), a hexadecimal number (0x00-0xff) or an octal number +(00-0377) using the usual "0x" and "0" prefixes for hexadecimal and octal +respectively. + +The printed lines will contain information about the QoS field of received +packets if either a non-standard QoS setting was used on outgoing packets or if +the QoS byte of incoming packets is not zero. In other words, the QoS +information is omitted if both, the outgoing and the incoming QoS bytes are +zero. The received byte is always interpreted as +I (DSCP) and +I (ECN), even if the deprecated +I (ToS) aliases were used to specify the bits of outgoing +packets. + +=item B<-m> I + +I Sets the I (an integer number) on outgoing packets. This +can be used by L and other networking infrastructure for filtering +and routing. + +=item B<-u>|B<-U> + +I B<-u> forces UTF-8 output, B<-U> disables UTF-8 output. If +neither is given, the codeset is automatically determined from the locale. + +=item B<-g> B|B|B|B + +I Selects the graph to display. + +=over 4 + +=item B + +Do not show a graph. + +=item B + +Show a graph with time on the x-axis, the y-axis shows the round-trip time. +This is the default graph. + +If your terminal supports unicode and colors, they are used to improve +the precision of the data shown: a green box is drawn for round-trip times up +to one third of the configured timeout, the height representing the RTT. Longer +RTTs will start to fill the box yellow (with a green background) and then red +(with a yellow background). Lost packages are drawn as a bold red explamation +mark. + +=item B + +Show a I where the x-axis, i.e. the width of the window, is the +round-trip time. The entire width of the window it the ping interval, set with +the B<-i> option. + +The box is sized so it contains 50% of the replies. The vertical line shows the +median. The whiskers are sized to contain 95% of the replies -- 2.5% below the +whiskers and 2.5% above. + + |----------[#####|##########]--------------------------------------------| + ^ ^ ^ ^ ^ + 2.5% 25% 50% 75% 97.5% + +=item B + +Show a I of the round-trip times. The width of the window is taken +as round-trip time from 0ms on the left to the I (the B<-i> option, +default 1000ms) on the right. + +The height of the graph is scaled so that the most-used buckets vertically fills +the line. The buckets are colored green up to and including the 80th +percentile, yellow up to and including the 95th percentile and red for the +remainder. + +=back + +=item B<-b> + +Audible bell. Print a ASCII BEL character (\a or 0x07) when a packet +is received before the timeout occurs. This can be useful in order to +monitory hosts' connectivity without looking physically at the +console, for example to trace network cables (start audible beep, +disconnect cable N: if beep stops, the cable was in use) or to tell +when a host returns from a reboot. + +This relies on the terminal bell to be functional. To enable the +terminal bell, use the following instructions. + +=over 4 + +=item + +the visual bell is disabled in your terminal emulator, with the +vb +commandline flag or the following in your .Xresources: + + XTerm*visualBell: false + +=item + +the PC speaker module is loaded in your kernel: + + modprobe pcspkr + +=item + +X11 has the terminal bell enabled: + + xset b on; xset b 100 + +=item + +and finally, if you are using PulseAudio, that the module-x11-bell +module is loaded with a pre-loaded sample defined in your pulseaudio +configuration: + + load-sample-lazy x11-bell /usr/share/sounds/freedesktop/stereo/complete.oga + load-module module-x11-bell sample=x11-bell + +=back + +=item B<-P> I + +Configures the latency percentile to report. I must be a number +between zero and 100, exclusively in both cases. In general, defaults to B<95>. +If B<-c> is given and a number less than 20, this would be the same as the +maximum. In this case the default is chosen so that it excludes the maximum, +e.g. if B<-cE5> is given, the default is I<80>. The calculated percentile +is based on the last 900 packets (15 minutes with the default interval). + +=item B<-Z> I + +If any hosts have a drop rate higher than I, where I is a +number between zero and 100 inclusively, exit with a non-zero exit status. +Since it is not possible to have a higher drop rate than 100%, passing this +limit will effectively disable the feature (the default). Setting the option to +zero means that the exit status will only be zero if I replies for I +hosts have been received. + +The exit status will indicate the number of hosts with more than I +packets lost, up to a number of 255 failing hosts. + +=back + +=head1 COLORS + +If supported by the terminal, I will highlight the round-trip times +(RTT) using the colors green, yellow and red. Green signals RTTs that are in +the "expected" range, yellow marks moderately unusual times and times that +differ a lot from the expected value are printed in red. + +The information used to categorize round-trip times is the I. RTTs +in the 80th percentile are considered to be "normal" and are printed in green. +RTTs within the 95th percentile are considered "moderately unusual" and are +printed in yellow. RTTs above that are considered to be "unusual" and are +printed in red. + +=head1 INTERACTIVE KEYBOARD CONTROLS + +When running I, the type of graph being displayed can be +changed by using the B key. A new host can be added at any time +with the B key. + =head1 SEE ALSO -L, L, L +L, L, L + +=head1 LICENSE + +I and I are licensed under the GPL 2. +No other version of the license is applicable. =head1 AUTHOR -liboping is written by Florian octo Forster Eocto at verplant.orgE. -Its homepage can be found at L. +liboping is written by Florian "octo" Forster Eff at octo.itE. +Its homepage can be found at L. -(c) 2005-2009 by Florian octo Forster. +Copyright (c) 2005-2017 by Florian "octo" Forster.