--- /dev/null
+#!@@PERL@@
+
+=head1 NAME
+
+B<spong-status> - 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<spong-status>
+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<status|page>
+
+Command type being sent to B<spong-server>. Defaults to 'status'.
+
+=item B<--host> I<NAME>
+
+Name of the host being reported.
+
+=item B<--service> I<NAME>
+
+Name of the service being reported.
+
+=item B<--color> <COLOR>
+
+Status color being reported. COLOR may be ``green'', ``yellow'', or ``red''.
+
+=item B<--summary> I<TEXT>
+
+Summary text to be reported.
+
+
+=item B<--ttl> I<SECONDS>
+
+Time to live of status report in seconds.
+
+=item B<--message> I<TEXT>
+
+Detailed message text being reported.
+
+=item B<--file> I<FILENAME>
+
+Detailed message info read from file FILENAME. If FILENAME is S<'-'>, text is
+read from stdin.
+
+=back
+
+=head1 CONFIGURATION
+
+=head2 Configuration Files
+
+B<spong-cleanup> reads the standard spong.conf and spong.conf.E<lt>hostE<gt>
+configuration files.
+
+=head2 Configuration Variables
+
+=over
+
+=item $SPONGSERVER
+
+The host that at least the L<spong-server> and L<spong-message>
+programs are running on. Typically the L<spong-network> program runs on that
+host as well.
+
+=item $SPONG_UPDATE_PORT
+
+This variable defines the port that the L<spong-server> update process listens
+on. If this variable is not defined on the I<$SPONGSERVER> host, the
+L<spong-server> update process will not be started. The default value is 1998.
+
+=back
+
+=head1 FILES
+
+F<SPONGHOME/etc/spong.conf>, F<SPONGHOME/etc/spong.conf.E<lt>hostE<gt>>
+
+=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<spong-server>, L<spong.conf>, L<developer-guide>
+
+=head1 AUTHOR
+
+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 development until
+version 2.1. Stephen L Johnson took over development in October, 1999 with his
+changes which became Spong 2.5.
+
--- /dev/null
+#!@@PERL@@
+
+=head1 NAME
+
+B<spong> - 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
+
+<b>spong</b> [--summary [hostlist] | --problems [hostlist] | --history
+[hostlist] | --host host | --services host | --stats host
+<br>
+| --config host | --info host | --service host:service ] [--brief | --standard
+| --full ]
+
+=end html
+
+=head1 DESCRIPTION
+
+The B<spong> program interfaces with the B<spong-server> to display the
+collected information; in text format. The B<spong> 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<spong> 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<spong-server> 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<HOSTLIST>]
+
+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<HOSTLIST>
+if not specified all hosts defined in F<spong.hosts> are displayed.
+
+=item B<--problems> [I<HOSTLIST>]
+
+Shows a summary of all the problems (services that are red) for the all
+the hosts in <HOSTLIST>. If I<HOSTLIST> is not specified, all hosts defined
+in F<spong.hosts> are displayed.
+
+=item B<--history> [I<HOSTLIST>]
+
+Show history information for the the list of hosts in I<HOSTLIST>. If
+I<HOSTLIST> is not specified, all hosts defined in F<spong.hosts> are
+displayed.
+
+=item B<--host> I<HOST>
+
+Shows all information available for the given I<HOST>
+
+=item B<--services> I<host>
+
+Shows detailed service information for the given I<HOST>.
+
+=item B<--stats> I<HOST>
+
+Show statistical information for the given I<HOST>. (Not currently
+implemented.)
+
+=item B<--config> I<HOST>
+
+Shows configuration information for the given I<HOST>. (Not currently
+implemented.)
+
+=item B<--info> I<HOST>
+
+Shows admin supplied text for the given I<HOST>.
+
+=item B<--service> I<HOST:SERVICE>
+
+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<spong.conf> 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<spong.conf.[host]> 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<spong.hosts>, L<spong.conf>
+
+ http://spong.sourceforge.net/ the Spong Home Page
+
+
+=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 development until
+version 2.1. Stephen L Johnson took over development in October, 1999 with his
+changes which became Spong 2.5.
+
--- /dev/null
+=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 <sjohnson@monsters.org>
--- /dev/null
+=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<Hosts> and B<Groups>, 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<Ack> link
+will bring up the L<www-spong-ack> CGI program in the Display frame. The page
+allows you to display, delete, or create Spong Acknowledgements. The I<Summary>
+link brigs up the host summary table of the currently select Host Group(s) in
+the Display frame. The <History> link displays the event history for all of
+the hosts in the current Host Group. And the <i>Help</i> 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<host name> is a link that will bring up the full status display
+for the host in the Display frame. The I<problem> 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<updated> field is the date and time that the
+status of that service updated. The I<contact> 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 <Summary> and I<History> displays. This
+title to the right of the <Group> link is the currently selected Host
+Group. Selecting the I<Group> 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<group name> 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 <Spong Groups> 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<Show Hosts> 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<spong.conf/"$SPONGSLEEP"> 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<Group Summary>.
+Most of the sub-pages have an action bar.
+
+=over
+
+=item Action Bar
+
+The I<Action Bar> on displays is directly under the title at the top
+of the page. The I<Connect to Host> link will start a telnet session
+to the host if clicked. The I<Acknowledge Problem> link will bring
+up the L<www-spong-ack> CGI program Display. The Host and Service fields will
+be filled in (if possible). The I<Contact Help> 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<admin-guide/"Custom Contacts"> 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<Host Services> 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 <Service Status> 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<Action Bar> 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<Delete> 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<Service Status> 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<admin-guide>.
+
+=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<Updated:> field which if the date and time of the last
+update of the status. The I<Duration> field shows the amount of time that the
+service has been in it's current status. And last is the I<Summary> 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<disk>
+service it will be the output of the B<df> command showing the mounted
+disk partitions and amount of space used on each disk and the for the I<cpu>
+service it will be a B<ps> 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<www-spong-ack> 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<Delete> 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 <www-spong-ack>
+documentation for more information.
+
+=back
+
+=head1 COMMAND LINE USER INTERFACE
+
+The command line interface is provided by the B<spong> program. It has all of
+the same displays that the Web Interface provides. The B<spong> program is run
+with 0, 1 or 2 parameters from a shell prompt. For more information run the
+B<spong> program with the --help parameters or see L<spong> 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 <F<sjohnson@monsters.org>>
+
projects / spong.git / commitdiff