From: Stephen L Johnson Date: Wed, 24 May 2000 20:59:45 +0000 (+0000) Subject: added/updated documentation in perl pod format X-Git-Tag: spong-2_7-alpha7~22 X-Git-Url: http://git.etc.gen.nz/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=2b15c129ae35a5c6b945a1dea062f1437ed86909;p=spong.git added/updated documentation in perl pod format --- diff --git a/src/spong-ack.pl b/src/spong-ack.pl index b49e89d..4a2619d 100755 --- a/src/spong-ack.pl +++ b/src/spong-ack.pl @@ -1,4 +1,26 @@ #!@@PERL@@ + +=head1 NAME + +B - Spong acknowledgment tool + +=head1 SYNOPSIS + +B [B<--debug>] [B<--batch>] host services time [message] + +B [B<--debug>] B<--delete> ack-id + +=head1 DESCRIPTION + +When a spong evet occurs (or will occur), you can use this tool to acknowledge +that you know that there is a problem. You can provide text that will be seen +by others looking at the event (via a spong display program). You can specify +at time limit that the problem will occur. If a problem has been acknowledged, you +will no longer received notifications of the problem, and the display programs will +show the status of the service as "blue". + +=cut + # # Spong acknowledgment tool. When a spong event occurs (or will occur), you # can use this tool to acknowledge that you know there is a problem. You can @@ -291,3 +313,135 @@ _EOF_ exit(0); } +__END__ + +=head1 OPTIONS + +=over + +=item B<--debug> + +Print debugging statements. This option can be specified while creating or deleting acks. + +=item B<--batch> + +Print the ack-id instead of the normal output. The primary use of this parameter +is for scripts. An ack can be created when a job that runs causes a service to +temporarily exceed it's normally limits, or if a service is taken down for an +unknown or irregular length of time. + +=item B<--delete> + +Delete a previously created ack. + +=back + +Here is a descirption of the arguments for creating acks: + +=over + +=item host + +The host having the problem(s) you are acknowledging. + +=item service + +The service or services (seperated by ".") or I services that your are +acknowledging. + +=item time + +The that the acknowledgement will late. This can be an offet "+1h, +3a,d +1w" or +an absolute date and/or time indicator "12/25/1997 14:00:00. The date needs to be +a 4 digit year, and the time needs to be in 24 hour format. + +=item message + +An optional message that will appear to those viewing the state of the host with a +spong display program. If the value is "-", then the message will read from STDIN. + +=back + +Here is a description of the arguments for deleting acks: + +=over + +=item ack-id + +The acknowledgment id to delete. The id can be obtained by using the B<--batch> +parameter when creating the acknowledgment, or by using the L command +with the B<--brief> and B<--ack> parameters. + +=over + +=head1 CONFIGURATION + +=head2 Configuration Files + +B reads the standard spong.conf and spong.conf.EhostE +configuration files. + +=head2 Configuration Variables + +=over + +=item $SPONGSERVER + +The host that at least the L and L +programs are running on. Typically the L program runs on that +host as well. + +=item $SPONG_UPDATE_PORT + +This variable defines the port that the L update process listens +on. If this variable is not defined on the I<$SPONGSERVER> host, the +L update process will not be started. The default value is 1998. + +=back + +=head1 FILES + +F, FhostE> + +=head1 EXAMPLES + + spong-ack mailhub.my-inc.com all '05/27/2000 06:00:00' 'Server is being upgraded' + + spong-ack www5.my-inc.com http +1h 'Web server is randomly dying. Investigating.' + +In a shell script: + + ... + HOST=`hostname` + ACKID=`spong-ack --batch $HOST cpu +8h 'Database exports are running'` + ... + # Database exports are done here + ... + spong-ack --delete $ACKID + ... + +=head1 DEPENDENCIES + +Perl v5.005_03 or greater is required. + +=head1 BUGS + +No know bugs. + +=head1 SEE ALSO + +L, L, L + +=head1 AUTHOR + +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 development until +version 2.1. Stephen L Johnson took over development in October, 1999 with his +changes which became Spong 2.5. + + diff --git a/src/spong-cleanup.pl b/src/spong-cleanup.pl index da5abe6..cd6d20d 100755 --- a/src/spong-cleanup.pl +++ b/src/spong-cleanup.pl @@ -1,4 +1,40 @@ #!@@PERL@@ + +=head1 NAME + +B - perform nightly mantenance to the spong database + +=head1 SYNOPSIS + +B + +=head1 DESCRIPTION + +This program performs routine, regular maintenace of the spong database. + +=over + +=item + +* Cleans out any history older then 7 days. It moves the old history for +each host into the L<$SPONG_ARCHIVE|spong.conf/"$SPONG_ARCHIVE"> directory. If +you don't think you would ever want to get at that history, then you can just +change the script so that it is deleted. + +=item + +* Removes any acknowledgements that are no longer valid. + +=item + +* Removes any services that don't seem to be reported any more (if you +stop monitoring something on a machine - the old entry will still hang around +and show up as purple). + +=back + +=cut + # # This program performs nightly maintanence to the spong database. # @@ -163,3 +199,75 @@ sub load_config_files { } } } + +__END__ + +The B program should be run every night as a cronjob. This will +ensure that database queries are speedy especially the History Log displays. + +=head1 CONFIGURATION + +=head2 Configuration Files + +B reads the standard spong.conf and spong.conf.Ehost +configuration files. + +=head2 Configuration Variables + +=over + +=item $SPONGDB + +This defines the directory where the Spong database will be stored. Each host +will have a subdirectory in this directory which is named for the host. + +=item $SPONG_ARCHIVE + +The directory where to put old history file entries for each host. Each host +has it's own file in this directory. + +=item $OLD_HISTORY + +This is the number of days of history to keep for each host in the +spong-server database. Any old history is append to the file for the host under +the I<$SPONG_ARCHIVE> directory. + +=item $OLD_SERVICE + +This is the number of days to retain stale service status (i.e. purple +status) entries in the spong-server database. Any service service status +entries older than <$OLD_SERVICE> days old are deleted from the +database. + +=back + +=head1 FILES + +F, F + +=head1 DEPENDENCIES + +Perl v5.005_03 or greater is required. + +=head1 BUGS + +None know bugs. + +=head1 SEE ALSO + +L, F + +=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 development until +version 2.1. Stephen L Johnson took over development in October, 1999 with his +changes which became Spong 2.5. diff --git a/src/spong-client.pl b/src/spong-client.pl index c5fac20..23817eb 100755 --- a/src/spong-client.pl +++ b/src/spong-client.pl @@ -344,6 +344,30 @@ of the checks once then exit. These flags can be used to run spong-client as a cron job (B), this reduced the effectiveness of the L module. +=head2 Client Checks + +The checks are actually a set of modules that are called in series by +B. The list of modules to run are defined in the I<$CHECKS> +configuration variable. Upon initialization, B will load the +modules defined in I<$CHECKS> from the F +directory. As each modules is initialized, it registers itself with the the +plugins registery (see the L). Spong comes +with a standard set of client checks, see L for more +information. + +=head2 Extending Functionality + +B, please refer to the L section of the Developer Guide. + +If you want to check some service which is not being checked by spong-client, +then you can define a C<&check_local()> function in your +config file (either in your standard L config file or your host specific L +file - but not both!). That function can do anything you want, but at the +end needs to call the C<&status()> function to report +what you have found to the spong server. + +=head1 CONFIGURATION + =head2 Configuration Files By default this reads the L file on startup. You can @@ -466,28 +490,6 @@ me know what OS you are running on, and what the correct value should be. =back -=head2 Client Checks - -The checks are actually a set of modules that are called in series by -B. The list of modules to run are defined in the I<$CHECKS> -configuration variable. Upon initialization, B will load the -modules defined in I<$CHECKS> from the F -directory. As each modules is initialized, it registers itself with the the -plugins registery (see the L). Spong comes -with a standard set of client checks, see L for more -information. - -=head2 Extending Functionality - -B, please refer to the L section of the Developer Guide. - -If you want to check some service which is not being checked by spong-client, -then you can define a C<&check_local()> function in your -config file (either in your standard L config file or your host specific L -file - but not both!). That function can do anything you want, but at the -end needs to call the C<&status()> function to report -what you have found to the spong server. - =head1 FILES @@ -522,6 +524,6 @@ Stephen L Johnson > 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. +from Big Brother to become Spong. Ed Hill continued Spong development until +version 2.1. Stephen L Johnson took over development in October, 1999 with his +changes which became Spong 2.5. diff --git a/src/spong-message.pl b/src/spong-message.pl index a42518c..9d5f746 100755 --- a/src/spong-message.pl +++ b/src/spong-message.pl @@ -776,6 +776,8 @@ B alerts people via the messaging modules that are installed. New messaging functions can be easily created. See the L section in the I. +=head1 CONFIGURATION + =head2 Configuration Files =over @@ -966,6 +968,6 @@ Stephen L Johnson > 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. +from Big Brother to become Spong. Ed Hill continued Spong development until +version 2.1. Stephen L Johnson took over development in October, 1999 with his +changes which became Spong 2.5. diff --git a/src/spong-network.pl b/src/spong-network.pl index d212fd9..323b120 100755 --- a/src/spong-network.pl +++ b/src/spong-network.pl @@ -583,6 +583,25 @@ 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 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 CONFIGURATION + =head2 Configuration Files =over @@ -660,23 +679,6 @@ 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 @@ -712,8 +714,8 @@ Stephen L Johnson > 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. +from Big Brother to become Spong. Ed Hill continued Spong development until +version 2.1. Stephen L Johnson took over development in October, 1999 with his +changes which became Spong 2.5. diff --git a/src/spong-server.pl b/src/spong-server.pl index 5dfb89c..430eb2a 100755 --- a/src/spong-server.pl +++ b/src/spong-server.pl @@ -1,4 +1,26 @@ #!@@PERL@@ + +=head1 NAME + +B - save status information reported by spong programs + +=head1 SYNOPSIS + +B [B<--debug> I] [B<--kill|--restart>] [F] + +=head1 DESCRIPTION + +The B is the central core program of Spong. The program received +status reports from various spong clients (specifically B and +various B program running). If the message is worth notifying +someone about, it calls the B program. The status messages +messages are stored into an internal datebase with significatnt changes being +logged into a history event log. Queries from spong interface programs (like +B and B) seeking to display the data in the B will +fork and detach itself from the console to run as a daemon. + +If you provide the B<--debug> I flag then debugging information will be +printed to stderr. The I is an integer from 1 to 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. It will release reload it's +configuration and restart. If the B<--kill> flag if provided, a signal will +be sent to the running B process causing it to exit. + +An alternate configuration file can be specified on the command line. This +file will be read instead of the default F configuration file. + +=head2 Theory of Operation + +The B has a main process that spawns a number of child processes +to handle all of the work. There are a query process which handles queries into +the Spong database, an update process which handles Spong formatted update +messages (see L), a BBSERVER +update process which handled Big Brother client update messages, and possibly +other process are more feature are added in the future. The main process +monitors each of the child processes. It will restart any child process that +dies for any reason. + +Each time a connection comes in, the child process is forks off to handle the +the above tasks. The main child process goes back to waiting for more +connections. + +=head2 Data Modules + +The B has a plugin module facility similar to the other +Spong programs. One or more modules can be installed in the +F directory. The modules are loaded are run-time by +B. As each module is initialized is registers itself with +the plugins registry. + +Each module is called in turn after all of the normal processing is done for +incoming status messages. This allows you access to data of a status message +tht will eventually be discarded. Data modules can do virtually anything that +you desire with the incoming data. The data can be written to a log or +database or feed to another application for further filter or processing. + +Two sample data modiules are located in the F +directory of the Spong distribution. The two modules (B and +B work in conjunction with a software package named RRD Tool to +log disk and cpu information into Round Robin Databases. The modules are +included as examples. They are not of must use by themselves. See the +B package (http://spong.sourceforge.net/downloads.html) for a +complete package that utilizes data modules. + +=head2 Big Brother (BBSERVER) Emulation + +=head1 CONFIGURATION + +=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 idefined in the +L<%HOSTS|spong.hosts/"%HOSTS"> variable in the L file. +B uses this list of servers to validate incoming status and +control messages. And the list is used in format of database queries. + +=item spong.groups + +The L file defines groups of hosts. B uses these +host groups to filter and format the data returned in database queries. + +=back + +From F: + + +Yes there are a lot of variables. But all of the variables have defined +default values. Most of these variables are used customizing the client +web and text interfaces. + +=over + +=item $SPONG_UPDATE_PORT + +This variable defines the port that the Spong update process listens on. If +This variable is not defined the Spong update process will not be started. +The default value is 1998. + +=item $SPONG_UPDATE_PORT + +This varirable defines the port that the Spong query process listens on. If +this varirable is not defined the Spong query process will not be started. The +default value is 1999. + +=item $SPONG_BB_UPDATE_PORT + +This variable defines the port that the Big Brother BBSERVER emulation +process listens on. If this variable is not defined the Big Brother BBSERVER +emluation process will not be started. The default value is 1984. + +=item $SPONGSLEEP (Depreciated) + +This variable is used by B to determine how old a service's +status can be before it is considered stale. It's status will be reported +as 'purple'. The exact time to live a message is 2 * $SPONGSLEEP. (This +variable is depreciated in favor of the new $SPONGSLEEP{} variables.) + +=item $SPONGSLEEP{'DEFAULT'}, $SPONGSLEEP{'spong-server'} + +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 $SPONGDB + +This defined the directory where the Spong database will be stored. Each host +will have a subdirectory in this directory which is named for the host. + +=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 $SPONGSTATUS + +If this variable is set to 1, it will enable the storing of the update +status message information for each event that is generated in the history +log. This status message information is access via the web interface by +click on the status color or icon link of an event in a History Listing. + +=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. + +=item $SPONG_SERVER_ALARM + +This variable defined the maximum amount of time (in seconds) that a incoming +connection of a status message can last. Once the time limit is exceeded +B will terminated the connection. This action can be disables +by setting the variable to zero (0). + +=item $WWW_FQDN + +Set this variable to 1 to display the fully qualified domain name (FQDN) of +hosts in Spong client displays. Otherwise only the first element of the FQDN +will be displayed. + +=back + +From F: + +=over + +=item %HOSTS + +All of the host names defined in %HOSTS are the list of hosts that +B will accept status messages for. Any status messsage for an +unknown host will be logged as an error and discarded. + += back + +From F: + +=over + +=item %GROUPS + +The host groups that are defined in this variable are used to filter and +format data queries of the Spong database. + +=back + +=head1 FILES + +F, F, F, F + +=head1 DEPENDENCIES + +Perl v5.005_03 or greater is required. + +=head1 BUGS + +No know bugs. + +=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 development until +version 2.1. Stephen L Johnson took over development in October, 1999 with his +changes which became Spong 2.5. + + diff --git a/src/spong-status.pl b/src/spong-status.pl index 7a64ac6..450fe00 100755 --- a/src/spong-status.pl +++ b/src/spong-status.pl @@ -1,4 +1,26 @@ #!@@PERL@@ + +=head1 NAME + +B - send vaious type of messages to a spong-server + +=head1 SYNOPSIS + + spong-status [--help] + spong-status [--ttl #] (--file name | --message "message text") CMD HOST + SERVICE COLOR "SUMMARY TEXT" + spong-status [--cmd cmd] --host name --service name --color color + --summary text (--message text | -f filename) + [--ttl seconds] + +=head1 DESCRIPTION + +This program allows you to creat your own extern spong client programs or +integrate existing monitoring program or scripts in Spong. B +hids all of the details of the Spong Client/Server communication protocol. + +=cut + # # This program can be used to send Status update messages to the Spong Server # from shell scripts or other external programs. @@ -95,7 +117,7 @@ Usage: spong-status [--help] spong-status [--ttl #] (--file name | --message "message text") CMD HOST SERVICE COLOR "SUMMARY TEXT" spong-status [--cmd cmd] --host name --service name --color color - --summary text (--message text | -f filename) + --summary text [--message text | -f filename] [--ttl seconds] @@ -138,3 +160,109 @@ sub load_config_files { } } +__END__ + +=head1 OPTIONS + +=item B<--help> + +Print the help text + +=item B<--cmd> I + +Command type being sent to B. Defaults to 'status'. + +=item B<--host> I + +Name of the host being reported. + +=item B<--service> I + +Name of the service being reported. + +=item B<--color> + +Status color being reported. COLOR may be ``green'', ``yellow'', or ``red''. + +=item B<--summary> I + +Summary text to be reported. + + +=item B<--ttl> I + +Time to live of status report in seconds. + +=item B<--message> I + +Detailed message text being reported. + +=item B<--file> I + +Detailed message info read from file FILENAME. If FILENAME is S<'-'>, text is +read from stdin. + +=back + +=head1 CONFIGURATION + +=head2 Configuration Files + +B reads the standard spong.conf and spong.conf.EhostE +configuration files. + +=head2 Configuration Variables + +=over + +=item $SPONGSERVER + +The host that at least the L and L +programs are running on. Typically the L program runs on that +host as well. + +=item $SPONG_UPDATE_PORT + +This variable defines the port that the L update process listens +on. If this variable is not defined on the I<$SPONGSERVER> host, the +L update process will not be started. The default value is 1998. + +=back + +=head1 FILES + +F, FhostE> + +=head1 EXAMPLES + + spong-status --cmd status --host www.my-inc.com --service fping --color yellow + --summary "Host contacted. Response time more then 30 ms" + --file /tmp/fping.out + + spong-status --tttl 86400 --message "Backup failed for /usr,/var" page + www.my-inc.com red backup "Backup failed" + +=head1 DEPENDENCIES + +Perl v5.005_03 or greater is required. + +=head1 BUGS + +No know bugs. + +=head1 SEE ALSO + +L, L, L + +=head1 AUTHOR + +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 development until +version 2.1. Stephen L Johnson took over development in October, 1999 with his +changes which became Spong 2.5. + diff --git a/src/spong.pl b/src/spong.pl index a457d61..3b7537e 100755 --- a/src/spong.pl +++ b/src/spong.pl @@ -1,4 +1,48 @@ #!@@PERL@@ + +=head1 NAME + +B - character based Spong client interface program + +=head1 SYNOPSIS + +=begin text + + spong [--summary [hostlist] | --problems [hostlist] | + --history [hostlist] | --host host | + --services host | --stats host | --config host | + --info host | --service host:service] + [ --brief | --standard | --full ] + +=end text + +=begin html + +spong [--summary [hostlist] | --problems [hostlist] | --history +[hostlist] | --host host | --services host | --stats host +
                           +| --config host | --info host | --service host:service ] [--brief | --standard +| --full ] + +=end html + +=head1 DESCRIPTION + +The B program interfaces with the B to display the +collected information; in text format. The B program does not have all +of the functionality of the web-based interface. It's designed to be used from +character based consoles. The B program doesn not have to load onto the +same machine that spong-server is running on. You load this program onto any +machine. It is a good ideal to load this onto machines, when possible, to allow +the administrator of the machine to query the B when alert of +received. + +When run with any parameters, spong will display a table that lists +the hosts and services. All of the displays are text based with the legends +at the top. + +=cut + # # This program is used to display information collected by the spong server to # simple character based terminals. It provides the same type of interface @@ -212,3 +256,139 @@ sub load_config_files { } } +__END__ + +=head1 OPTIONS + +=over + +=item B<--summary> [I] + +Summarize the status of hosts, in HOSTLIST, in a table that lists +the hosts and services, and the current status is a single letter with +the meaning defined in the ledgend at the top of the display. If I +if not specified all hosts defined in F are displayed. + +=item B<--problems> [I] + +Shows a summary of all the problems (services that are red) for the all +the hosts in . If I is not specified, all hosts defined +in F are displayed. + +=item B<--history> [I] + +Show history information for the the list of hosts in I. If +I is not specified, all hosts defined in F are +displayed. + +=item B<--host> I + +Shows all information availiable for the given I + +=item B<--services> I + +Shows detailed service information for the given I. + +=item B<--stats> I + +Show statistical information for the given I. (Not currently +implemented.) + +=item B<--config> I + +Shows configuration information for the given I. (Not currenly +implemented.) + +=item B<--info> I. + +=item B<--service> I + +Shows detailed information for the given HOST/SERVICE. + +=item B<--brief> + +Display output in a brief format. + +=item B<--standard> + +Display output in standard format (the default) + +=item B<--full> + +Display the maximum amount of information possible. + +=head1 CONFIGURATION + +=head2 Configuration Files + +By default the L file is read on startup. It defines some specific +variable that you probably don't need to override. + +After reading the configuration file, then reads the +F 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. + +=head2 Configuration Variables + +Here are a list of variables in the spong.conf file that are applicable +to the spong-server program: + +=over + +=item $SPONGSERVER + +The make of the server that spong-server is running on. + +=item $SPONG_QUERY_PORT + +The port number that spong-server listens at for database queries. + +=back + +=head1 FILES + +=over + +=item spong.conf + +Configuration file. This contains variables that detail spong and OS specific +definitions used by spong-server. + +=back + +=head1 DEPENDENCIES + +Perl v5.005_03 or greater is required. + +=head1 BUGS + +The B<--stats>, B<--config>, and B<--info> parameters are currently +not implemented in the spong-server. When specified they will just generate +a blank HTML page. + +=head1 SEE ALSO + +L + + http://spong.sourceforge.net/ the Spong Home Page + + +=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 development until +version 2.1. Stephen L Johnson took over development in October, 1999 with his +changes which became Spong 2.5. + diff --git a/src/www-spong-ack.pl b/src/www-spong-ack.pl index e6b6649..0d2a662 100755 --- a/src/www-spong-ack.pl +++ b/src/www-spong-ack.pl @@ -1,4 +1,24 @@ #!@@PERL@@ + +=head1 NAME + +B - WWW (CGI) based spong acknowledgment tool + +=head1 SYNOPSIS + +http://spong-server.my-inc.com/spong/www-spong-ack + +=head DESCRIPTION + +Then a spong event occurs (or will occur), you can use this tool to acknowledge +that your know there is a problem. You can provide text that will be seen by others +looking at the event (via a spong display program). You can specify a time limit +that the problem will occur. If a probblem has been acknowledged, you will no longer +receive notifications of the problem, and the spong display programs will show the +of the service(s) as "blue". + +=cut + # # WWW based spong acknowledgment tool. When a spong event occurs (or will # occur), you can use this tool to acknowledge that you know there is a @@ -548,4 +568,79 @@ _EOM_ return "can not connect to spong server" if ! $ok; } +__END__ + +=head2 Theory of Operation + +The B program is designed to interact with the L +Spong display program, but it the program can be used if it is invoked directly. + +When the program is initially invoked it will list all of the acknowledments at +the top of the page in the "Current Acknowledgments" section. The host/service +and the expiration date/time of the acks are displayed. A I link is +provided for every ack. that will delete that particular ack. when selected. + +Below in the "New Acknowledgment" section is a form form for creating a new +acknowledgment. The hostname is selected from the drop-down box. The service(s) +to be acknowledged is entered in service field. The duration of the event is +entered in one of serveral formats into the duration field. Your e-mail addres +should be entered into the e-mail address field. It is only used to show who +created the ack. And a message about the aknowledgement can be entered. Once +all of the infomation is entered, press the 'Create' button to create the +acknowledgement. + +=head1 CONFIGURATION + +=head2 Configuration Files + +B reads the standard spong.conf and spong.conf.EhostE +configuration files. + +=head2 Configuration Variables + +=over + +=item $SPONGSERVER + +The host that at least the L and L +programs are running on. Typically the L program runs on that +host as well. + +=item $SPONG_UPDATE_PORT + +This variable defines the port that the L update process listens +on. If this variable is not defined on the I<$SPONGSERVER> host, the +L update process will not be started. The default value is 1998. + +=back + +=head1 FILES + +F, FhostE> + +=head1 DEPENDENCIES + +Perl v5.005_03 or greater is required. + +A working web server that can run CGI programs. + +=head1 BUGS + +No know bugs. + +=head1 SEE ALSO + +L, L, L, L + +=head1 AUTHOR + +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 development until +version 2.1. Stephen L Johnson took over development in October, 1999 with his +changes which became Spong 2.5. diff --git a/src/www-spong.pl b/src/www-spong.pl index 4fd1f2f..4c2b54b 100755 --- a/src/www-spong.pl +++ b/src/www-spong.pl @@ -1,4 +1,50 @@ -#!/usr/bin/perl +#!@@PERL@@ + +=head1 NAME + +B - display spong system status via the web or general static HTML pages +of system status + +=head1 SYNOPSIS + +B [ + S [I] |> + S [I] |> + S [] |> + S I |> + S I |> + S I |> + S I |> + S I< host> |> + S I> + ] + S<[--brief | --standard | --full ]> + +=head1 DESCRIPTION + +The B program interfaces with the spong-server to display the +collected information in HTML format. B can be run in two modes: as +a CGI program and from the command line. + +When run as a CGI program it does not have to loaded onto the same machine that +spong-server is runnning. It queries the spong-server through it's query port. +it will display information via a web page that reloads itself at regular +intervals. When run with no parameters it created a page with two or three +frames. In tree frames mode there will be a top title frame spanning the entire +page thas has an action bar to switch views. The remain frames are displayed +below. The left frame displays a summary of systems along with their +associated problems (services that are red). The right panel is a table that +lists the hosts and services, and the current status is a colored block or an +icon depending on how spong-server is configured. For further information on +how to use the web interface see . + +When run from a command line, www-spong generates HTML pages that are printed +to the console. This mode can be used to generate static HTML pages. If +www-spong is run without any parameters a page that contains a summary display +for all hosts is generated. + +=cut + # # This program is used to display information collected by the spong server to # people using web based clients. This provides the same type of interface to @@ -773,3 +819,150 @@ _EOM_ return "Can't connect to spong server!"; } +__END__ + +=head1 OPTIONS + +=over + +=item B<--summary> [I] + +Summarize the status of hosts, in hostlist, in a table that lists +the hosts and services, and the current status is a colored block or an +icon depending on how spong-server is configured. If hostlist if not specified +all hosts defined in spong.hosts are displayed. + +=item B<--grp-summary> + +Summary the status of all by Host Groups defined in the L file. +Each Host Group is displayed in a table that lists the hosts and services, and +the current status is a colored block or an icon depending on how spng-server +is configured. + +=item B<--problems> [I] + +Shows a summary of all the problems (services that are red) for the all +the hosts in hostlist. If hostlist is not specified, all hosts defined +in spong.hosts are displayed. + +=item B<--grp-problems> + +Shows a summary of all of the problems (services that are red) for all Host Groups +defined in the L file. + +=item B<--history> [I] + +Show history information for the the list of hosts in hostlist. If host +list is not specified, all hosts defined in spong.hosts are displayed. + +=item B<--host> I + +Shows all information availiable for the given host. + +=item B<--services> I + +Shows detailed service information for the given host. + + +=item B<--stats> I + +Show statistical information for the given host. + +=item B<--config> I + +Shows configuration information for the given host. + +=item B<--info> I + +Shows admin supplied text for the given host. + +=item B<--service> I + +Shows detailed information for the given host/service. + +=item B<--brief> + +Display output in a brief format. + +=item B<--standard> + +Display output in standard format (the default). + +=item B<--full> + +Display the maximum amount of information possible. + +=back + +=head1 CONFIGURATION + +=head2 Configuration Files + +By default the L file is read on startup. It defines some specific +variable that you probably don't need to override. + +After reading the configuration file, then reads the +F 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. + +=head2 Configuration Variables + +Here are a list of variables in the spong.conf file that are applicable +to the spong-server program: + +=over + +=item $SPONGSERVER + +The make of the server that spong-server is running on. + +=item $SPONG_QUERY_PORT + +The port number that spong-server listens at for database queries. + +=back + +=head1 FILES + +=over + +=item spong.conf + +Configuration file. This contains variables that detail spong and OS specific +definitions used by spong-server. + +=back + +=head1 DEPENDENCIES + +Perl v5.005_03 or greater is required. + +=head1 BUGS + +The B<--stats>, B<--config>, and B<--info> parameters are currently +not implemented in the spong-server. When specified they will just generate +a blank HTML page. + +=head1 SEE ALSO + +L, L, L + + http://spong.sourceforge.net/ the Spong Home Page + +=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 development until +version 2.1. Stephen L Johnson took over development in October, 1999 with his +changes which became Spong 2.5. +