=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.

=item CLEAR

For hosts and service, this meaan that the status is unavailable for some
reason. The usual cause is the host being out of communication. Service checks
used by the L<spong-network|spong-network> program can be flagged with a
I<stop_after> flag. If a service with the I<stop_after> fails the remaining
checks will be skipped. And all of the remaining checks will have a I<clear>
status.

=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, CLEAR - status is unavailable,
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, PURPLE, GREEN, CLEAR.

=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>>