This document is for Spong Administrator. It details how to install and
configure the Spong Server and Spong Client programs.
-=head1 Installation
+=head1 INSTALLATION
=head2 Installation - Server
If you have a number of like clients with the same OS your can copy
the entire installation directory tree from an installed client to other
-clients. You can use tar+ftp, rcp, rdist or whatever mechamism you would
+clients. You can use tar+ftp, rcp, rdist or whatever mechanism you would
normally use. Just be sure the Spong installation directory into the same
location as the original client.
+=head1 CONFIGURATION
+
=head2 Configure Web Server
To use the Spong Web Display your need to configure you web server in
-conjuction with some configuration variable in the spong.conf configuration
+conjunction with some configuration variable in the spong.conf configuration
file.
=over 4
=item spong.conf
+=begin html
+
+<p>
+
+=end html
+
=over 8
=item $WWWSPONG
=item $WWWHTML
-This varirable is used as a part of the Spong online help/information system.
-The variable is different from the other B<$WWW> spong config varirables. This
-variable is set to the actual file location of the F<SPONG/www/html> direcotyr
+This variable is used as a part of the Spong online help/information system.
+The variable is different from the other B<$WWW> spong config variables. This
+variable is set to the actual file location of the F<SPONG/www/html> directory
on the file system. The Web Display programs reads the requested files, does
some token replacement, and send the files to the web server.
=item $WWDOCS
-This varirable is used as a part of the Spong online help/information system.
-The variable is different from the other B<$WWW> spong config varirables. This
+This variable is used as a part of the Spong online help/information system.
+The variable is different from the other B<$WWW> spong config variables. This
variable is set to the actual file location of the F<SPONG/www/docs> directory
on the file system. The Web Display programs reads the requested files, does
some token replacement, and send the files to the web server.
=back
+=begin html
+
+<p>
+
+=end html
+
=item Web Server Configuration
-On the web server side of thing your will have to configure two items: the F<SPONG/www> directory and the F<SPONG/cgi-bin/> CGI directory
+=begin html
+
+<p>
+
+=end html
+
+On the web server side of thing your will have to configure two items: the
+F<SPONG/www> directory and the F<SPONG/cgi-bin/> CGI directory
+
+=begin html
+
+<p>
+
+=end html
=over 8
=item Spong CGI Directory
-The F<SPONG/cgi-bin/> directory must be setup as a CGI directory and aliased
+The F<SPONG/cgi-bin/> directory must be setup as a CGI directory and alias-ed
into the desired location. For example, for Apache a sample configuration
line would be:
=item Spong HTML Directory
-The F<SPONG/www/> directory must be aliased into the desired location within
+The F<SPONG/www/> directory must be alias-ed into the desired location within
the web server document tree. If you want the F<SPONG/www> directory
to be under http://www.example.org/spong/ on an Apache web server, use this
configuration line:
=back
-=head2 Debugging Problems
+=head1 DEBUGGING
The general way to debug Spong programs is to use the B<--debug #> parameter.
The B<#> is a number from 1 to 9 that controls the amount of debugging that is
file are named F<program-name.log> in the I<$SPONGTMP> directory and the
entries are logged to syslog under the USER facility with a priority of ERR.
-
-=over
-
-=item B<spong-server>
-
+=head2 B<spong-server>
When spong-server is run with B<--debug #> the primary process will run in the
fore-ground and all of the child processes with write their debugging
host/service/color of every status message that is received.
The update processes will print out their actions concerning notifications. If
-a notification is indicated, B<spong-server> will call B<spong-message> with the
-B<--debug> parameter if B<--debug> was specified in the command line.
+a notification is indicated, B<spong-server> will call B<spong-message> with
+the B<--debug> parameter if B<--debug> level is at least 3.
-=item B<spong-client>
+=head2 B<spong-client>
B<spong-client> will print out the check that is being performed along with
the status and the summary message.
-=item B<spong-network>
+=head2 B<spong-network>
B<spong-network> will print out the current host that is being checking and the
name of the check as it performs them, along with the status and the summary
message.
-=item B<spong-message>
+=head2 B<spong-message>
spong-message can be tested outside of spong-server to test your notification
configurations. Your run spong-message with the following parameters:
=back
-=back
-
B<spong-message> will print out the current rule number (starting with 0).
The the success or failure of all of the checks of the matching
attributes.
potentially print out a large quantity of debugging. You may want to redirect
the output to a file while you are testing it.
+=head1 WWW-SPONG
+
=head2 Customizing Web Pages
Spong has a feature that allows users to customize some aspects of the Spong
pages the headers or footer will be placed (i.e. service status screen,
server display screen, history screen, problem screen, etc.)
-
-=head2 Expanded Host Status Web Pages (Information Files)
+=head2 Expanded Host Status Pages (Information Files)
This feature is one of Spong's best kept secrets. You can create additional
information files that will be displayed on all status displays for a
where E<lt>hostnameE<gt> is the name of a host as defined in spong.hosts. See
L<spong.hosts> for most information.
-
B<spong-server> first looks for a info.brief, info.standard or info.full file
depending on the type of display (brief, standard or full; and html or txt). If
the program finds one it will display that file. Otherwise, B<spong-server>
mode displays. The .html files can contain html code, URLs, embedded graphics,
Javascript, or anything that you display on a web page.
-
=head2 Custom Contacts
The web pages generated by Spong have "smart" "Contact Staff" links. That is,
rest of the form should be populated with whatever fields that you need into
order to interface to your paging applications
-=head2 Customized Action Bar
+=head2 Customized Action Bars / Tool Bars
The Action Bar of the Host and Service Status Displays (see L<user-guide>
for more details) can be customized with the I<$WWW_ACTIONBAR_CUSTOM>
code defined in this parameter will be included at the end of the Action Bars.
This parameter is preprocessed with the Perl C<eval> function before the
-contents are printed. This allows you to include complex perl variables or perl
+contents are printed. This allows you to include complex Perl variables or Perl
code. Because of the C<eval> processing you should use single quotes to enclose
-the contents of this parameter. This will prevent premature evaluation of perl
+the contents of this parameter. This will prevent premature evaluation of Perl
variables before the output.
If your do not need this customization, just leave B<$WWW_ACTIONBAR_CUSTOM>
undefined. Nothing will be added to the Action Bars.
-=head2 $WWW_REFRESH Logic
+=head2 Auto-Refresh
The default of the spong-server is to not allow auto-refreshes if
B<@WWW_REFRESH_ALLOW> and B<@WWW_REFRESH_DENY> variables are empty (see
For example, if I<@WWW_REFRESH_ALLOW> contains[ 'joe', '.*-support',
'^192.168.12.*', 'noc-display' ] and I<@WWW_REFRESH_DENY> contains
-['bill','mary']. If a web brower on a machine at ip address 192.168.12.143
+['bill','mary']. If a web browser on a machine at ip address 192.168.12.143
queries the spong-server web pages, the auto-refresh would be allowed because
it matches the '^192.168.12.*' expression of I<@WWW_REFRESH_ALLOW>. But if the
user was 'fred' at the same machine (192.168.12.143), auto-refresh would not be
enabled because 'fred' is in the I@<WWW_REFRESH_DENY> list.
+=head1 SPONG-NETWORK
+
+=head2 Service Checks
+
+The service checks for a host are controlled by the I<services> attribute
+of the host's entry in the L<spong.hosts> configuration file. I<services> is a
+list of services that will checks. The services are checked in the order they
+are listed in I<services>.
+
+The services listed in I<services> are actually L<spong-network
+modules|spong.network/"Network Checks">, and meta-services names. The
+L<spong-network modules|spong.network/"Network Checks"> do the actual network
+service checks and meta-service names alter the default behavior of the
+L<spong-network|spong-network> program.
+
+At present there is only one meta-service: I<noping>.
+L<spong-network|spong-network> default behavior is to prepend a I<ping> on to
+the list in the I<services> attribute. Putting I<noping> in the list stops
+this behavior.
+
+=head2 Service Check Flags
+
+=over
+
+=item stop_after
+
+The I<stop_after> flag (the colon (':') ) can be appended to one, or
+more, services in the I<services> attribute for a host. If the check service
+with the <stop_after> flag fails, all remaining services are skipped and set
+with the B<clear> status.
+
+This I<stop_after> flag is used to signal dependencies within the list
+of tests specified in a I<services> attribute. If the rpc portmapper service is
+down, the NFS and NIS services on the system would be down also. There would be
+no need to also check them.
+
+For example:
+
+ 'myhost.example.com' => { services => 'ping: ftp smtp http: webapp', },
+
+If the B<ping> check for the host failed, the most likely reason is the host is
+now out of communication with the Spong Network host. Checking the remaining
+network services is not necessary. They would be reported as down and an number
+of unnecessary notifications would have been sent out. The I<stop_after> flag
+will cause the remaining services to be reported as B<clear>/not-available.
+
+Similarly, the web server need to be running for a web-application to run. So
+the B<http> check is placed before the B<webapp> check in I<services> and it is
+flagged with the I<stop_after> flag.
+
+=back
+
=head1 SEE ALSO
L<spong-server>, L<www-spong>, L<spong.conf>
projects / spong.git / commitdiff