From 7d4eeb403a42179f75a833405fc29761e7c9b86d Mon Sep 17 00:00:00 2001 From: David Schweikert Date: Mon, 16 Jul 2012 00:53:11 +0200 Subject: [PATCH] convert man-page to pod, for easier editing --- .gitignore | 1 + ChangeLog | 5 +- doc/Makefile.am | 4 + doc/fping.8 | 227 ------------------------------------------------ 4 files changed, 8 insertions(+), 229 deletions(-) delete mode 100644 doc/fping.8 diff --git a/.gitignore b/.gitignore index 7920308..68464bf 100644 --- a/.gitignore +++ b/.gitignore @@ -18,3 +18,4 @@ missing src/*.o src/fping stamp-h1 +doc/fping.8 diff --git a/ChangeLog b/ChangeLog index ece5f2d..f86b7fe 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,7 +1,8 @@ UNRELEAESD David Schweikert - * version 3.3rc1 - * do not output icmp errors with -q (#1) + * Version 3.3rc1 + * Do not output icmp errors with -q (#1) * Man-page fix: TOS option typo (Thomas Liske) + * Convert man-page source to POD for easier maintenance 2012-05-29 David Schweikert * Version 3.2 diff --git a/doc/Makefile.am b/doc/Makefile.am index 36d8b25..5b873aa 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,2 +1,6 @@ man_MANS = fping.8 EXTRA_DIST = $(man_MANS) + +fping.8: fping.pod + pod2man $< >$@ + pod2man -c "" -s 8 -r "fping $(VERSION)" $< >$@ diff --git a/doc/fping.8 b/doc/fping.8 deleted file mode 100644 index bba349a..0000000 --- a/doc/fping.8 +++ /dev/null @@ -1,227 +0,0 @@ -.TH fping 8 -.SH NAME -fping \- send ICMP ECHO_REQUEST packets to network hosts -.SH SYNOPSIS -.B fping -[ \fIoptions\fR ] -[ \fIsystems...\fR ] - -.SH DESCRIPTION -.B fping -is a program like -.B ping(8) -which uses the Internet Control -Message Protocol (ICMP) echo request to determine if a target host is -responding. -.B fping -differs from ping 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 fping -will send out a ping packet and move -on to the next target in a round-robin fashion. -.PP -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 fping -also supports sending a specified number of pings to a target, or -looping indefinitely (as in -.B ping -). -.PP -Unlike -.B ping, -.B fping -is meant to be used in scripts, so its output is designed to be -easy to parse. -.SH OPTIONS -.IP \fB\-a\fR 5 -Show systems that are alive. -.IP \fB\-A\fR 5 -Display targets by address rather than DNS name. -.IP \fB\-b\fIn\fR 5 -Number of bytes of ping data to send. The minimum size (normally 12) -allows room for the data that -.B fping -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 ping. -Maximum is the theoretical maximum IP datagram size (64K), though most -systems limit this to a smaller, system-dependent number. -.IP \fB\-B\fIn\fR 5 -In the default mode, -.B fping -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. -.IP \fB\-c\fR 5 -Number of request packets to send to each target. In this mode, a -line is displayed for each received response (this can suppressed with -\-q or \-Q). Also, statistics about responses for each target are displayed -when all requests have been sent (or when interrupted). -.IP \fB-C\fR 5 -Similar to \-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 "\-" indicating that no response was received to the fourth -request. -.IP \fB\-d\fR 5 -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. -.IP \fB\-e\fR 5 -Show elapsed (round-trip) time of packets. -.IP \fB\-f\fR 5 -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 - -.IP \fB\-g\fR 5 -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 -.IP \fB\-h\fR 5 -Print usage message. -.IP \fB\-i\fIn\fR 5 -The minimum amount of time (in milliseconds) between sending a ping packet to any target (default is 25). -.IP \fB\-l\fR 5 -Loop sending packets to each target indefinitely. Can be interrupted -with Ctrl-C; statistics about responses for each target are then displayed. -.IP \fB\-m\fR 5 -Send pings to each of a target host's multiple interfaces. -.IP \fB\-n\fR 5 -Same as \-d. -.IP \fB\-p\fR 5 -In looping or counting modes (\-l, \-c, or \-C), this parameter sets the -time in milliseconds that -.B fping -waits between successive packets to an individual target. Default is -1000. -.IP \fB\-q\fR 5 -Quiet. Don't show per-target results, just set final exit status. -.IP \fB\-Q\fIn\fR 5 -Like \-q, but show summary results every n seconds. -.IP \fB\-r\fIn\fR 5 -Retry limit (default 3). This is the number of times an attempt at pinging -a target will be made, not including the first try. -.IP \fB\-s\fR 5 -Print cumulative statistics upon exit. -.IP \fB\-S\fIaddr\fR 5 -Set source address. -.IP \fB\-I\fIif\fR 5 -Set the interface (requires SO_BINDTODEVICE support) -.IP \fB\-t\fIn\fR 5 -Initial target timeout in milliseconds (default 500). In the default -mode, this is the amount of time that -.B fping -waits for a response to its first request. Successive timeouts are -multiplied by the backoff factor. -.IP \fB\-T\fIn\fR 5 -Ignored (for compatibility with fping 2.4). -.IP \fB\-u\fR 5 -Show targets that are unreachable. -.IP \fB\-O\fIn\fR 5 -Set the typ of service flag (TOS). \fIn\fR can be either decimal or hexadecimal (0xh) format. -.IP \fB\-v\fR 5 -Print -.B fping -version information. -.IP \fB-H\fIn\fR 5 -Set the IP TTL field (time to live hops). - -.SH EXAMPLES -The following perl script will check a list of hosts and send mail if -any are unreachable. It uses the open2 function which allows a program -to be opened for reading and writing. fping does not start pinging the -list of systems until it reads EOF, which it gets after INPUT is closed. -Sure the open2 usage is not needed in this example, but it's a good open2 -example none the less. -.nf - -#!/usr/bin/perl -require 'open2.pl'; - -$MAILTO = "root"; - -$pid = &open2("OUTPUT","INPUT","/usr/local/bin/fping -u"); - -@check=("slapshot","foo","foobar"); - -foreach(@check) { print INPUT "$_\\n"; } -close(INPUT); -@output=; - -if ($#output != -1) { - chop($date=`date`); - open(MAIL,"|mail -s 'unreachable systems' $MAILTO"); - print MAIL "\\nThe following systems are unreachable as of: $date\\n\\n"; - print MAIL @output; - close MAIL; -} - -.fi -Another good example is when you want to perform an action only on hosts -that are currently reachable. -.nf - -#!/usr/bin/perl - -$hosts_to_backup = `cat /etc/hosts.backup | fping -a`; - -foreach $host (split(/\\n/,$hosts_to_backup)) { - # do it -} - -.fi - -.SH AUTHORS -.nf -Roland J. Schemers III, Stanford University, concept and versions 1.x -RL "Bob" Morgan, Stanford University, versions 2.x -David Papp, versions 2.3x and up, -David Schweikert, versions 3.0 and up -fping website: http://www.fping.org -.fi -.SH 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. -.SH BUGS -Ha! If we knew of any we would have fixed them! -.SH RESTRICTIONS -If certain options are used (i.e, a low value for \-i and \-t, and a -high value for \-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 (when fping is installed setuid root) , normal users can't specify -the following: -.nf - - -i n where n < 10 msec - -r n where n > 20 - -t n where n < 250 msec - -.fi -.SH SEE ALSO -netstat(1), ping(8), ifconfig(8c)