diff --git a/doc/fping.pod b/doc/fping.pod new file mode 100644 index 0000000..d675828 --- /dev/null +++ b/doc/fping.pod @@ -0,0 +1,240 @@ +=head1 NAME + +fping - send ICMP ECHO_REQUEST packets to network hosts + +=head1 SYNOPSIS + +B [ I ] [ I ] + +=head1 DESCRIPTION + +B is a program like B which uses the Internet Control Message +Protocol (ICMP) echo request to determine if a target host is responding. +B differs from B in that you can specify any number of targets on the +command line, or specify a file containing the lists of targets to ping. +Instead of sending to one target until it times out or replies, B will +send out a ping packet and move on to the next target in a round-robin fashion. +In the default mode, if a target replies, it is noted and removed from the list +of targets to check; if a target does not respond within a certain time limit +and/or retry limit it is designated as unreachable. B also supports +sending a specified number of pings to a target, or looping indefinitely (as in +B ). Unlike B, B is meant to be used in scripts, so its +output is designed to be easy to parse. + +=head1 OPTIONS + +=over 5 + +=item B<-a> + +Show systems that are alive. + +=item B<-A> + +Display targets by address rather than DNS name. + +=item B<-b> I + +Number of bytes of ping data to send. The minimum size (normally 12) allows +room for the data that B needs to do its work (sequence number, +timestamp). The reported received data size includes the IP header (normally +20 bytes) and ICMP header (8 bytes), so the minimum total size is 40 bytes. +Default is 56, as in B. Maximum is the theoretical maximum IP datagram +size (64K), though most systems limit this to a smaller, system-dependent +number. + +=item B<-B> I + +In the default mode, B sends several requests to a target before giving +up, waiting longer for a reply on each successive request. This parameter is +the value by which the wait time is multiplied on each successive request; it +must be entered as a floating-point number (x.y). The default is 1.5. + +=item B<-c> + +Number of request packets to send to each target. In this mode, a line is +displayed for each received response (this can suppressed with B<-q> or B<-Q>). +Also, statistics about responses for each target are displayed when all +requests have been sent (or when interrupted). + +=item B<-C> + +Similar to B<-c>, but the per-target statistics are displayed +in a format designed for automated response-time statistics gathering. For +example: + + % fping -C 5 -q somehost + somehost : 91.7 37.0 29.2 - 36.8 + +shows the response time in milliseconds for each of the five requests, with the +C<-> indicating that no response was received to the fourth request. + +=item B<-d> + +Use DNS to lookup address of return ping packet. This allows you to give fping +a list of IP addresses as input and print hostnames in the output. + +=item B<-e> + +Show elapsed (round-trip) time of packets. + +=item B<-f> + +Read list of targets from a file. This option can only be used by the root +user. Regular users should pipe in the file via stdin: + + % fping < targets_file + +=item B<-g> + +Generate a target list from a supplied +IP netmask, or a starting and ending IP. Specify the netmask or start/end +in the targets portion of the command line. If a network with netmask is +given, the network and broadcast addresses will be excluded. +ex. To ping the network 192.168.1.0/24, the specified command line could look like either: + + fping -g 192.168.1.0/24 + +or + + fping -g 192.168.1.1 192.168.1.254 + +=item B<-h> + +Print usage message. + +=item B<-i> I + +The minimum amount of time (in milliseconds) between sending a ping packet +to any target (default is 25). + +=item B<-l> + +Loop sending packets to each target indefinitely. Can be interrupted with +Ctrl-C; statistics about responses for each target are then displayed. + +=item B<-m> + +Send pings to each of a target host's multiple interfaces. + +=item B<-n> + +Same as -d. + +=item B<-p> + +In looping or counting modes (B<-l>, B<-c>, or B<-C>), this parameter sets +the time in milliseconds that B waits between successive packets to +an individual target. Default is 1000. + +=item B<-q> + +Quiet. Don't show per-target results, +just set final exit status. + +=item B<-Q> I + +Like B<-q>, but show summary results every n seconds. + +=item B<-r> I + +Retry limit (default 3). This is the number of times an attempt at pinging +a target will be made, not including the first try. + +=item B<-s> + +Print cumulative statistics upon exit. + +=item B<-S> I + +Set source address. + +=item B<-I> I + +Set the interface (requires SO_BINDTODEVICE support) + +=item B<-t> I + +Initial target timeout in milliseconds (default 500). In the default mode, this +is the amount of time that B waits for a response to its first request. +Successive timeouts are multiplied by the backoff factor. + +=item B<-T> I + +Ignored (for compatibility with fping 2.4). + +=item B<-u> + +Show targets that are unreachable. + +=item B<-O> I + +Set the typ of service flag (TOS). I can be either decimal or hexadecimal +(0xh) format. + +=item B<-v> + +Print B version information. + +=item B<-H> I + +Set the IP TTL field (time to live hops). + +=back + +=head1 AUTHORS + +=over 4 + +=item * + +Roland J. Schemers III, Stanford University, concept and versions 1.x + +=item * + +RL "Bob" Morgan, Stanford University, versions 2.x + +=item * + +David Papp, versions 2.3x and up + +=item * + +David Schweikert, versions 3.0 and up + +=back + +B> + +=head1 DIAGNOSTICS + +Exit status is 0 if all the hosts are reachable, 1 if some hosts +were unreachable, 2 if any IP addresses were not found, 3 for invalid command +line arguments, and 4 for a system call failure. + +=head1 RESTRICTIONS + +If certain options are used (i.e, a low value for B<-i> and B<-t>, and a high value +for B<-r>) it is possible to flood the network. This program must be installed as +setuid root in order to open up a raw socket, or must be run by root. In order +to stop mere mortals from hosing the network, normal users can't specify the following: + +=over 4 + +=item * + +B<-i> I, where I < 10 msec + +=item * + +B<-r> I, where I > 20 + +=item * + +B<-t> I, where n < 250 msec + +=back + +=head1 SEE ALSO + +C