From: Stephen L Johnson Date: Tue, 9 Nov 1999 00:19:02 +0000 (+0000) Subject: Initial import X-Git-Tag: start~24 X-Git-Url: http://git.etc.gen.nz/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=52ac3471a399e679014b329b23914e417c8b519b;p=spong.git Initial import --- diff --git a/www/docs/spong-network.html b/www/docs/spong-network.html new file mode 100755 index 0000000..d302ed9 --- /dev/null +++ b/www/docs/spong-network.html @@ -0,0 +1,236 @@ + + + + + + spong-network + + + +

+NAME

+spong-network - report network service information to spong server. +

+SYNOPSIS

+spong-network [--debug] [--kill|--restart|--nosleep|--refresh] [config_file] +

+DESCRIPTION

+This does two things, first it checks network connectivity to various machines +that you want to monitor (via ping). It then tries to connect to the services +that are running on each host to make sure they are available. 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). +

Besides checking connectivity (first using tcp echo, and then ICMP ping +if that fails), the following TCP/UDP based services can be checked. +

+    * dns    (asks the bind server to resolve its own name)
+
+
+    * ftp    (checks for a 220 return code)
+
+
+    * pop3   (checks for a "OK" return string)
+
+
+    * smtp   (checks for a 220 return code)
+
+
+    * nntp   (checks for a 200 return code)
+
+
+    * imap   (checks for a "OK" return string)
+
+
+    * http   (checks for a 200-300 return code)
+
+    * ssh    (checks for "SSH" in return string)
+
+
+
+
+
+
+

+The DNS check will only be performed if you have the Perl Net::DNS module +installed on your system. This module does not come with spong, but can +be downloaded at http://www.perl.com/CPAN/. +

For each of these network services, the following information is reported +to the spong server. +

+   * hostname (the host the service is running on)
+
+
+   * service name ("ftp", "pop3", "smtp", ...)
+
+
+   * color ("red", "yellow", "green")
+
+
+   * a one line summary
+
+
+   * a more detailed message providing additional detail.
+
+
+
+
+
+
+
+

+These checks are modular in nature.New checks can be added or old checks +replaced with newer versions. See Client +Modules in the Developers Guide. +

For most services, the color is determined by comparing the return value +of the service against an expected string. For some services (like http) +there are some additional smarts built in to determine the status of the +service. +

The spong-network program can also check multiple interfaces on a given +host. See spong.hosts for instructions +on how to set this up in your spong.hosts file. +

The one line summary provides information that might be useful at a +glance when looking at the overall system status (such as the response +time of the service). The more detailed message contains information such +as the output of the service. +

You should start this program in your system startup file, and it should +be running constantly. The program will daemonize by default unless one +of the flags below is given. +

If you provide the --debug flag, then debugging information will be +printed to stdout and the program will be forced to run in the fore ground, +otherwise output will only be produced if there is a problem. +

If you provide the --restart flag, a signal will be sent to the spong-network +process that is currently running that will cause it to reload it's configuration +files. If you provide the --kill flag, a signal will be sent to the running +spong-network process causing it to exit. The --nosleep and --refresh flags +caus the program to cycle through all of the checks one +
and then exit. These flags can be used to run spong-network +from cron. +
+

+CONFIGURATION

+The configuration of the spong-network program is two fold, the first part +is the /usr/local/etc/spong/spong.hosts +file. This file defines the host that you want to monitor and the network +services running on that host (all hosts are checked for connectivity via +ping). See spong.hosts for additional +information. +

The second part of the configuration is the /usr/local/etc/spong/spong.conf +file which defines some specific variables that you probably don't need +to override. By default the /usr/local/etc/spong/spong.conf +file is read 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. +

After reading the configuration file that you specify (or the default), +it then reads the /usr/local/etc/spong/spong.conf.[host] file where +[host] 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. +

Here are a list of variables in the spong.conf file that are applicable +to the spong-network program: +

+$SPONGSLEEP, $SPONGSERVER, $SPONGPORT: + 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 +on.
+%HTTPDOCS, %HTTPPORT: + These variables provide some parameters when checking http based +servers. The %HTTPDOCS variable is keyed by host (or the string +``ALL'' for all hosts), and contains as a value, a list of documents to +check on that host. The default setting is to search for the ``/robots.txt'' +file on all hosts.
+$PING, $TRACEROUTE, $GREP: + These variables are OS specific variables, which are hopefully set +correctly for your machine, if they are not - please send me email letting +me know what OS you are running on, and what the correct value should be.

+ +

+FILES

+ +

+/usr/local/etc/spong/spong.conf: +Configuration file. This contains variables that detail spong and OS specific +definitions used by spong-network. See spong.conf for additional +documentation.
+/usr/local/etc/spong/spong.hosts: +Host and human configuration file. This defines what hosts you are monitoring, +and what human you should contact if there is a problem. See spong.hosts +for additional documentation.

+ +

+DEPENDENCIES

+Perl v5.003 or greater is required. +

+BUGS

+It does everything sequentially, so if you have big connectivity problems, +it can take forever to make it through all the services. I should fork +off processes to do the checking, so that a down host doesn't slow down +the processing of other hosts. +

I should check connectivity a little better, check it once and then +back off, and keep backing off little by little until the host is reachable +again - like pong does... +

The http check is not configurable enough. +

+SEE ALSO

+the spong-server manpage , spong.hosts, spong.conf +

+AUTHORS

+Ed Hill (ed-hill@uiowa.edu), Unix +System Administrator, The University of Iowa +
Stephen L Johnson (stephen.johnson@mail.state.ar.us +or sjohnson@monsters.org) , +Unix Systems Administrator, DIS - State of Arkansas +

Based on code/ideas from Sean MacGuire (BB), and Helen Harrison (Pong). + +