From acbf919411bf1c23d0e32c9e1ccc1c6d0f5ec9d1 Mon Sep 17 00:00:00 2001 From: Stephen L Johnson Date: Thu, 14 Sep 2000 17:25:11 +0000 Subject: [PATCH] added files into CVS --- pod/spong-cleanup.pod | 102 +++++++++ pod/spong-message-mod-template.pod | 7 + pod/spong-status.pod | 127 +++++++++++ pod/spong.pod | 179 ++++++++++++++++ pod/todo.pod | 112 ++++++++++ pod/user-guide.pod | 324 +++++++++++++++++++++++++++++ 6 files changed, 851 insertions(+) create mode 100644 pod/spong-cleanup.pod create mode 100644 pod/spong-message-mod-template.pod create mode 100644 pod/spong-status.pod create mode 100644 pod/spong.pod create mode 100644 pod/todo.pod create mode 100644 pod/user-guide.pod diff --git a/pod/spong-cleanup.pod b/pod/spong-cleanup.pod new file mode 100644 index 0000000..2429752 --- /dev/null +++ b/pod/spong-cleanup.pod @@ -0,0 +1,102 @@ +=head1 NAME + +B - perform nightly maintenance to the spong database + +=head1 SYNOPSIS + +B + +=head1 DESCRIPTION + +This program performs routine, regular maintenance 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 + +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.EhostE +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/pod/spong-message-mod-template.pod b/pod/spong-message-mod-template.pod new file mode 100644 index 0000000..865425b --- /dev/null +++ b/pod/spong-message-mod-template.pod @@ -0,0 +1,7 @@ +=head1 NAME + +spong-message-mod-template - how to build spong message template + +=head1 DESCRIPTION + +Placeholder for now. diff --git a/pod/spong-status.pod b/pod/spong-status.pod new file mode 100644 index 0000000..809e9a9 --- /dev/null +++ b/pod/spong-status.pod @@ -0,0 +1,127 @@ +#!@@PERL@@ + +=head1 NAME + +B - send various 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 create your own extern spong client programs or +integrate existing monitoring program or scripts in Spong. B +hides all of the details of the Spong Client/Server communication protocol. + +=head1 OPTIONS + +=over + +=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 --ttl 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/pod/spong.pod b/pod/spong.pod new file mode 100644 index 0000000..b943f48 --- /dev/null +++ b/pod/spong.pod @@ -0,0 +1,179 @@ +#!@@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't 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. + +=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 legend 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 available 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 currently +implemented.) + +=item B<--info> I + +Shows admin supplied text for the given 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. + +=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 host name 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 + + 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/pod/todo.pod b/pod/todo.pod new file mode 100644 index 0000000..f57a3b4 --- /dev/null +++ b/pod/todo.pod @@ -0,0 +1,112 @@ +=head1 Spong TODO / Wish list + +Here are the features/changes that I and others want to make to spong. They +are in no particular order, If you have any suggestions or comments, send +email to sjohnson@monsters.org. + +=over + +=item * + +Make web interface more configurable: (user selectable background colors/ +method, table shading scheme) (DONE) + +=item * + +Add option to use style sheets on Web Interface. + +=item * + +Client support (spong-client) for NT (DONE) + +=item * + +Server support (spong-server, spong-network, spong-display) support for NT + +=item * + +Make spong-network more parallel, have it perform checks from a pool of +children, that way if a system can not be ping'ed - it will not slow up the rest +of the checks. + +=item * + +Make spong-network check more often on hosts that do not respond on the +first try (DONE) + +=item * + +Add some limited event correlation to spong-network to not report service +problems is a parent router/switch is unreachable. + +=item * + +Optimize the communication between client and server - by pipelining +reports through a single channel and perhaps compressing the data before +sending it. + +=item * + +Make it so that you can click on a host and find out status, history, +configuration (inventory), and statistics. (starting to branch out). (DONE via +configurable ToolBars in Web Interface) + +=item * + +Integrate gstats (statistics collection) program. "spong-stats" (Ed Hill) + +=item * + +Add an inventory/configuration module. "spong-config" (DONE via +configurable ToolBars in Web Interface and packages called SysSymm) + +=item * + +Continue modularizing to move towards Object Oriented as much as possible. + +=item * + +Customizable notify messages in spong-message. (DONE) + +=item * + +Add control ports to spong-client,spong-network, and spong-server to +ultimately allow the programs to be control and configured remotely + +=item * + +Add stats package to record and display status update information in RRD +Tool databases. "spong-rrd" (DONE) + +=item * + +Add SSL to Client/Server protocol for verification and security + +=item * + +Be able to display hosts sorted and sectioned by groups. (DONE) + +=item * + +Add "Sticky" events that can stay around until cleared or time limit expires. + +=item * + +Add event handling API into spong-server for event handler modules + +=item * + +Add summary status type to be able to send summary status messages to other +Spong servers + +=item * + +Add support for multiple Spong-Servers and fail-over capabilities for high +availability (multiple Spong-Servers - DONE) + +=back + +=head1 AUTHOR + +Most recently updated on July 28, 2000 +Stephen L Johnson diff --git a/pod/user-guide.pod b/pod/user-guide.pod new file mode 100644 index 0000000..8f7f74a --- /dev/null +++ b/pod/user-guide.pod @@ -0,0 +1,324 @@ +=head1 NAME + +user-guide - a user's guide to using Spong + +=head1 DESCRIPTION + +This the user's guide to using spong. It has an overview of the operation of +the whole system and how the user fits into the scheme of things. Spong +acknowledgements, the web-base user interface and the character based +interfaced will be covered in detail. + +=head1 SPONG OVERVIEW + +=head1 WEB USER INTERFACE + +The Spong web display has two different modes that can be configured by the +Administrator: 2 frame or 3 frames. The two modes are essentially the same +from the user's point of view. The 3 frame mode added a header frame at the +top of the windows in addition to the two side by side display frame. + +The display frames are 2 side by side frames, The left frame is commonly called +the Command frame. It will contains a summary of any hosts that currently have +any problems (i.e. any service that is red.) The right Display frame will +contain various displays that are select from previous displays or the links on +the Command frame. + +=head2 Status Colors + +Though out many of the displays the status of a host or a service is expressed +as a color. This will be in the form of a blocks, a strip, or an icons. This is +a list of the colors and their meaning. + +=over + +=item GREEN + +For a service, green means that it is responding normally, or it is within +normal parameters. For a host, green means that all services are OK and +there are active acknowledgements or over-due service status reported. + +=item YELLOW + +For a service, yellow generally means that something minor is wrong and +may need attention, or a parameter is slightly out of bounds. For a host, +yellow mean that one or services are at a warning status. + +=item RED + +For a service, red means that is something is critically wrong for a service, +such as a network service not responding or a parameter is radically out +of bounds. For a host, red means that one or more services are at a critical +status. + +=item PURPLE + +For a service, purple means it's status report is overdue. The last time +that the service has been updated is too old. this can be due to network +problems or a Spong Client program has stopped for some reason. For +a host, is means that one of more service status reports are over due. + +=item BLUE + +For hosts and services, this means that there is an active acknowledgment +on the service or host. While a service is acknowledged, no notifications +will be sent to, but events will still be written to the history log file. + +=back + +=head2 Display Modes + +There are two main viewing modes for the Spong web interface + +=head1 FRAMES + +=head2 Header Frame + +In the 3 frame mode of operation this will be displayed across the top +of the web page. This frame is static. It holds a tool bar. + +The tool bar has controls to switch between the Groups and Hosts view modes +of the two Display frames. The tool bar may also have other controls added +by your the Administrator. + +=head2 Command Frame + +The left Command frame is divided 5 or 6 sections from top to bottom: +Title,View Tool Bar, Action Bar, Main Section (problem host list), Host Group +selector and Last Update. The View Tool Bar is only displayed when the Web +display is configured in 2 frame mode. And the Host Group selector will not be +displayed in the Groups view mode. + +=over + +=item Title + +The section is simple the title Spong and the version number of the server. + +=item View Tool Bar + +This has two links, B and B, which are used to switch between +the Hosts and Groups viewing modes. This Tool Bar is only displayed is the +Web Interface is configured in 2 frame mode. + +=item Action Bar + +The section under the title section is the Command action bar. The I link +will bring up the L CGI program in the Display frame. The page +allows you to display, delete, or create Spong Acknowledgements. The I +link brigs up the host summary table of the currently select Host Group(s) in +the Display frame. The link displays the event history for all of +the hosts in the current Host Group. And the Help link will the Spong +HTML documentation. + +=item Main Section + +The main section of the Command frame is a list of all of the hosts that +have any problems (e.g. services that are red). If there are +no reported problems then this section will have "No Current Problems" +in green letters. If there are problems then a list of hosts will be displayed +along with name of the services that has the problem. The last date/time +that the service was updated and, is defined. A contact responsible for +the host. + +The I is a link that will bring up the full status display +for the host in the Display frame. The I field under the host +name is a link to the service display page for that host. It will be displayed on +the Display Frame. The I field is the date and time that the +status of that service updated. The I field (if present) is a link +that will bring up a custom CGI program that will allow you to send a message +to the people responsible that host. + +=item Group Section + +The Host Group section allows to select which group of hosts that you +want to display in the and I displays. This +title to the right of the link is the currently selected Host +Group. Selecting the I link brings up the Spong Group display +in the Display frame. On top of the page is a list of all of the predefined +host groups defined along with the display name and a summary description +of the group. + +If you click a I link, you change the group of hosts +that you are viewing. The web browser window will be redrawn to reflect +the new group of hosts. At the bottom of the display +is a section that allows you to select a custom group of hosts to display. +You select all of the hosts that you want to be in your custom group from +the list of hosts. Then click in the I button to redraw +the browser window and display the your customized group of hosts. + +This section will only be displayed in the Hosts view mode. + +=item Last Update + +The time stamp section at the bottom is the date and time that the entire +left frame was last updated. If refreshing is allowed by you or your system, +the frame will be automatically reload every $SPONGSLEEP (for spong-server) +seconds. See L for more information. + +=back + +=head2 Display Frame + +The right frame is the Display Frame. It is used to display various +informational displays and forms. The default display is the I. +Most of the sub-pages have an action bar. + +=over + +=item Action Bar + +The I on displays is directly under the title at the top +of the page. The I link will start a telnet session +to the host if clicked. The I link will bring +up the L CGI program Display. The Host and Service fields will +be filled in (if possible). The I link (if present) is a link +that will bring up a custom CGI program that will allow you to send a message +to the people responsible that host (see L for more information). + +=item Group Summary Display + +The Group Summary Display is a table that lists the hosts and services of the +current selected group of hosts. The name of the selected group is displayed +at the top of the display. In the Groups view mode, the hosts will be grouped +into separate tables by host groups. + +Each host is a row in the table with services being the columns of the table. +The current status of each service is a colored block or a icon depending on +how spong-service is configured. The statuses are represented by the color: +RED - critical, YELLOW - warning, GREEN - normal, PURPLE - status is output of +date, BLUE - service has active acknowledgement, NOTHING - service is not +checked. + +The host name in the first column is a link to I display the +host. The service names in the first row of the table are links to Help page +for that service. The Help page has a description of the service and the +ramifications if the service is in a warning or critical status. The service +status colored block or icon is a link to the display for +the host/service. + +=item Host Services Display + +This display shows most of the available information about the host. The +display is divided into several sections. From top to bottom they are : +Title (Host Name), Action Bar, Overall Status, Acknowledgements, Services +Table, Information, History. + +=over + +=item Title + +The is the name of the Host being displayed. + +=item Action Bar + +The I is discussed above. + +=item Overall Status + +This a bar this displays the current overall status of the host. The over +status is the highest order color of all of the service statuses according +to the following hierarchy: BLUE, RED, YELLOW, GREEN, PURPLE. + +=item Acknowledgements + +If there are any Acknowledgements for the host they will be listed here. +Each acknowledgement will have the service that is acknowledged, the expiration +date, and the message. There is a I link for each acknowledgement +also which will delete the acknowledgment when clicked. + +=item Services Table + +This is a summary table of all of the services that is checked on this host. +The table lists the service name, the current status of the service +(colored-block or icon) , the time (in 23 hour format) of the last update, and +the summary message of message status. The service name and the current status +colored-block/icon are links that will bring of the I display +for the service. + +=item Information + +If there is any addition information defined for the host, it will be displayed +in this section. This information is unique to each host. There can be a +description of the functions of the host, embedded image or links to other +information sources. For further information see the L. + +=item History + +The recent event history of the host will be displayed in this section. +The events are displayed in reverse chronological orders divided into separate +days. Each event has the status color, time (in 24 hour format), host name, +service name, and message summary line of the event. + +=back + +=item Service Status Display + +This display shows all of the information available for the service/host. It is +divided into several sections: Title (Host Name/Service), Action Bar, Summary +Information, Detailed Information>. + +=over + +=item Title + +This is the name of the host and service being displayed. + +=item Action Bar + +This is discussed above. + +=item Summary Information + +This section shows summary information for the service. First is a colored bar +that shows the current status color of the service. See L<|"Status Colors"> for +details. Next is the I field which if the date and time of the last +update of the status. The I field shows the amount of time that the +service has been in it's current status. And last is the I field +which is a one line summary message about the status of the service. + + +=item Detailed Information + +This last section is detailed information about the status of the service. +The type of information depends of the service. For example, for the I +service it will be the output of the B command showing the mounted +disk partitions and amount of space used on each disk and the for the I +service it will be a B command output showing information about +the top 10 processes using a CPU. + +=back + +=item Acknowledge Problem Display + +This display is a form generated by the B CGI program. At top of +the form are instructions on how to fill out the form, next will be a list of +all of the current Acknowledgments created for the host. The list includes the +service that was ack'ed, the expiration date of the acknowledgement, and the +message text of the acknowledgment. There is also a I link that can be +used to delete the Acknowledgment if clicked. Below this if a form that can be +filled out to create a new Acknowledgment. See the +documentation for more information. + +=back + +=head1 COMMAND LINE USER INTERFACE + +The command line interface is provided by the B program. It has all of +the same displays that the Web Interface provides. The B program is run +with 0, 1 or 2 parameters from a shell prompt. For more information run the +B program with the --help parameters or see L documentation. + +=head1 ACKNOWLEDGMENTS + +Spong Acknowlegements are a mechanism that allows the user to notify the +spong-server that they know about the problem and no more notifications need to +be sent. Acknowledgments have a limited life time. After an acknowledgment has +expired, the spong-server will start sending out notifications if necessary. +Acknowledgments are created for a specific host and service, or all services can +be acknowledged by specifying 'all' for the service name. + +=head1 AUTHOR + +Stephen L Johnson > + -- 2.30.2