-#!/usr/bin/perl
+#!@@PERL@@
+
+=head1 NAME
+
+B<spong-network> - report network service informtion to spong server.
+
+=head1 SYNOPSIS
+
+B<spong-network> [B<--debug> I<n>] [B<--kill|--restart|--nosleep|--refresh]
+ [F<config_file>]
+
+=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
}
}
+__END__
+
+The program checks a series of network services that are configured serparately
+for each host. B<spong-network> 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<spong-network> forks
+and detaches itself to run as a daemon.
+
+If you provide the B<--debug> I<n> flag, then debugging information will be
+printed to stdout, otherwise output will only be produced if there is a
+problem. Where I<n> 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<spong-network>
+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<depreciated>), 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<spong.conf|spong.conf> 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<spong.conf.[hostname]> 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<spong-network> reads all of the host that are to be check from the
+L<%HOSTS|spong.hosts/"%HOSTS"> variable in the L<spong.hosts> file. The
+list of services to be check for each host is alread read from F<spong.hosts>.
+
+=back
+
+=head2 Configuration Variables
+
+From F<spong.conf>:
+
+=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<spong-client>
+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</tmp> for operation and securiy reasons.
+
+=item $SPONG_LOG_FILE
+
+If set to I<1>, B<spong-network> will log errors to a log file in I<$SPONGTMP>
+named F<spong-network.log>.
+
+=item $SPONG_LOG_SYSLOG
+
+If set to I<1>, B<spong-network> will log errors to the syslog using the
+I<USER> facility and the I<ERR> priority.
+
+=back
+
+From F<spong.hosts>:
+
+=over
+
+=item %HOSTS
+
+All of the host names defined in %HOSTS are the list of hosts that
+B<spong-network> will check. The services defined in the I<services> attribute
+are the list of services that will be check for each host. The I<ping> 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<spong-network>. Upon initialization, B<spong-network> will load the all of
+the modules that will be used from the F<LIBDIR/Spong/Network/plugins>
+directory. As each module is initialized, it registers itself with the plugins
+registry (see the L<Developer Guide|developer-guide>). 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<services> attribute of the host's entry in the
+L<%HOST|spong.hosts/"%HOSTS"> variable. The I<ping> service is appended by
+default to all of the lists of services to be check for a host. If the
+metaservice name of I<noping> is defined for a host, the ping check will no be
+done for the host.
+
+=head1 FILES
+
+F<spong.conf>, F<spong.conf.hostname>, F<spong.hosts>
+
+=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<spong-network>
+(i.e. B<spong-network --restart> ),
+
+A work-around is to regularly do restart B<spong-network>, such as from a
+cron job.
+
+=head1 SEE ALSO
+
+L<spong-server>, L<spong.conf>, L<spong.hosts>, L<network-modules>,
+L<developer-guide>
+
+=head1 AUTHOR
+
+Ed Hill <F<ed-hill@uiowa.edu>>, Unix System Administrator, The University of
+Iowa
+
+Stephen L Johnson <F<sjohnson@monsters.org>>
+
+=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.
+
+
projects / spong.git / commitdiff