From 6be012d1ed15503e139d48d1bffdb306ca46defd Mon Sep 17 00:00:00 2001 From: Stephen L Johnson Date: Mon, 15 May 2000 03:30:10 +0000 Subject: [PATCH] added updated documentation in pod format --- src/spong-network.pl | 219 ++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 218 insertions(+), 1 deletion(-) diff --git a/src/spong-network.pl b/src/spong-network.pl index 6f90a8b..d212fd9 100755 --- a/src/spong-network.pl +++ b/src/spong-network.pl @@ -1,4 +1,25 @@ -#!/usr/bin/perl +#!@@PERL@@ + +=head1 NAME + +B - report network service informtion to spong server. + +=head1 SYNOPSIS + +B [B<--debug> I] [B<--kill|--restart|--nosleep|--refresh] + [F] + +=head1 DESCRIPTION + +This checks network connectivity and network service availabity to various +machines you want to monitor. It reports the status of the network services +that it monitors to the spong server. Everything happens again after sleeping +for a time period you have defined in your configuration file. This program +typically runs on your spong server machine (although it can be run on any host +- although I would suggest one with good network connectivity). + +=cut + # # Spong network monitoring script. This runs various tests against IP based # network services (like nntp, smtp, http, pop, etc...) If it can not @@ -500,3 +521,199 @@ sub config_funcs { } } +__END__ + +The program checks a series of network services that are configured serparately +for each host. B also can be very agressive in checking for +network service that are down. You can configure multiple rechecks to guard +against transistional failues. + +=head2 Running the program + +You should start this program in your system startup file, and it should be +running constantly. If no parameters are specified, B forks +and detaches itself to run as a daemon. + +If you provide the B<--debug> I flag, then debugging information will be +printed to stdout, otherwise output will only be produced if there is a +problem. Where I is a number from 1 - 9. A higher number means more +verbosity in the debugging output. + +If you provide the B<--restart> flag, a signal will be sent to the B +process that is currently running that will cause it to reload it's +configuration files. If you provide the B<--kill> flag, a signal will be sent +to the running spong-client process causing it to exit. + +The B<--nosleep> or B<--refresh> flag causes the program to cycle through all +of the checks once then exit. These flags can be used to run spong-client as a +cron job (B), but it recommended that you run the program +continuously. + + +=head2 Format of update messages + +It sends a message for each check to the spong server and reports the +following: + +=over 4 + +=item * hostname (where is this report coming from) + +=item * service name ("disk", "cpu", "procs", "logs", "local") + +=item * color ("red", "yellow", "green") + +=item * a one line summary + +=item * a more detailed message providing additional detail. + +=back + +The color is determined by comparing the current status of that +service against thresholds defined in the configuration file. If +they are greater then the level you have defined for a warning, then the color +is yellow. If they are greater then the critical level you have defined then +the color is red. + +The one line summary provides information that might be useful at a glance when +looking at the overall system status (such as a brief report on the load, +number of users, and uptime). + +The more detailed message contains information such as the output of +the ping command from the check ping module or the data read after testing +a network service. + +=head2 Configuration Files + +=over + +=item spong.conf + +By default this reads the L file on startup. You can +specify an alternate config file via a command line option and it will read +that file instead. If you change values in the configuration file you will need +to restart this program for those changes to be re-read. + +=item spong.conf.[hostname] + +After reading the configuration file that you specify (or the default), +it then reads the F file where [hostname] is the +hostname of the machine that you are running on. Since these configuration +files are just standard perl code that gets imported, the variables that you +define in the host specific config file will take precedence over the standard +configuration settings. + +=item spong.hosts + +B reads all of the host that are to be check from the +L<%HOSTS|spong.hosts/"%HOSTS"> variable in the L file. The +list of services to be check for each host is alread read from F. + +=back + +=head2 Configuration Variables + +From F: + +=over + +=item $SPONGSLEEP, $SPONGSERVER, $SPONG_UPDATE_PORT + +Some basic spong configuration options that define how long to sleep (in +seconds) before checking the status of a service again, the hostname of the +spong server, and the port number that the spong server listens + +=item $SPONGSLEEP{'DEFAULT'}, $SPONGSLEEP{'spong-network'} + +This the new method for specifying the $SPONGSLEEP interval for Spong programs. +If there is not $SPONGSLEEP{} entry for the program, it will use the +I<$SPONGSLEEP{'DEFAULT'}> value. If no value is then found, B +fall back to using $SPONGSLEEP. + +=item $SPONGTMP + +The directory that Spong programs use for temporary store and work files. It +should be different a directory than F for operation and securiy reasons. + +=item $SPONG_LOG_FILE + +If set to I<1>, B will log errors to a log file in I<$SPONGTMP> +named F. + +=item $SPONG_LOG_SYSLOG + +If set to I<1>, B will log errors to the syslog using the +I facility and the I priority. + +=back + +From F: + +=over + +=item %HOSTS + +All of the host names defined in %HOSTS are the list of hosts that +B will check. The services defined in the I attribute +are the list of services that will be check for each host. The I service +is prependied to the list of services unless 'noping' is defined. + +=back + +=head2 Network Checks + +The check are actually a setup of modules that are called in series by +B. Upon initialization, B will load the all of +the modules that will be used from the F +directory. As each module is initialized, it registers itself with the plugins +registry (see the L). Spong comes with a +standard set of network check modules, see L<"network-modules> for more +information. + +The list of network checks and the order the are performed that are performed +for a host are defined in the I attribute of the host's entry in the +L<%HOST|spong.hosts/"%HOSTS"> variable. The I service is appended by +default to all of the lists of services to be check for a host. If the +metaservice name of I is defined for a host, the ping check will no be +done for the host. + +=head1 FILES + +F, F, F + +=head1 DEPENDENCIES + +Perl v5.005_03 or greater is required. + +=head1 BUGS + +The check_dns module uses the Net::DNS Perl module. On some systems the +Net::DNS module will fail and start reporting false DNS lookup failures. The +cause is unknown at present. This will cause dns check for all hosts to fail +and be reported as a critical status. The fix is to restart B +(i.e. B ), + +A work-around is to regularly do restart B, such as from a +cron job. + +=head1 SEE ALSO + +L, L, L, L, +L + +=head1 AUTHOR + +Ed Hill >, Unix System Administrator, The University of +Iowa + +Stephen L Johnson > + +=head1 HISTORY + +Based on code/ideas from Sean MacGuire (BB), and Helen Harrison (Pong). Ed Hill +original converted Big Brother (http://www.bb4.com) into Perl which diverged +from Big Brother to become Spong. Ed Hill continued Spong develop until version +2.1. Stephen L Johnson took over development in October, 1999 with his changes +which became Spong 2.5. + + -- 2.30.2