=head1 NAME

admin-guide - Spong Administrator's Guide

=head1 DESCRIPTION

This document is for Spong Administrator. It details how to install and 
configure the Spong Server and Spong Client programs.

=head1 INSTALLATION

=head2 Installation - Server

To build and install the spong server do the following on the machine 
that is to be the Spong Server. It is suggest that your have web server 
running on the same machine for the spong web display program. It is not
required, but it will simplify the installation.

=over 8

=item *

Edit the "build" script, and set the variables at the top of that script
according to where you want spong installed, and where certain programs
that spong relies on are located.


=item *

Check to make sure there is a config/spong.conf.E<lt>osE<gt> file corresponding
to your operating system, if not - create one. This file contains paths and
command line arguments to helper programs that are used to determine things
like disk usage, etc... If you have to create your own spong.conf.E<lt>osE<gt>
file, then please email it to me so that I can add it to the distribution.


=item *

Make sure you are in the directory that you unpacked spong in and type: 
C<./build> C<os> where E<lt>osE<gt> is the name corresponding to your
operating system. You can type C<./build help> to generate a list of
valid operating system strings.

When the build completes, you will be left with some new directories
in the folder that you unpacked spong in. The build process takes the spong
source (and documentation), and replaces some "tokens" with values that
you have supplied at the top of the build script. The build process also
creates a spong.conf file, and generates various types of documentation
based on the POD files that come with spong.


=item *

Now, type C<./build install>. Note that the install process makes
no assumptions about what user you want to run spong as (you B<don't>
have to run it as root). This means that you have to be a little more careful
when you install spong (making sure it has the correct permissions, and
that you have permission to copy the www pages into your web server's document
tree).


=item *

Now edit the spong.conf, spong.hosts, spong.group and spong.messages files
that you just installed and season to taste. You should now be able to
read the manual pages for each.


=back

Now you will have the executables and configuration files in place
on the server. You need to start the spong-server and spong-network programs.
The spong-server program will listen for reports from various agents, and
the spong-network program will start testing the hosts you have defined
for any problems. After starting those programs, you should start seeing
files show up in the I<$SPONGDB> directory that you defined in the spong.conf
file.

B<NOTE - HOSTNAMES:> Part of spong-server's status message authentication has
to do with host names. B<spong-server> checks the host name in a status message
against the hosts defined in the spong.hosts file. The the status message host
name is not found, spong-server will silently drop the messages.

So it is important that your serves are able to resolve their fully qualified
domain name. To do this check there is a little Perl test program
B<gethost-test> from in the F</utils> directory of the Spong distribution. Just
run it from a command line by entering C<perl gethost-test.> It tests to see is
the host can resolve it's fully qualified domain name.  If it can't then it
will advise you on ways to fix the problem. See also Question 2 in the L<Spong FAQ|spong-faq>.

=head2 Installation - Client

For each client machine you will need to install the the package just like a 
the server installation described above. After the C<./build install> step
is done, you can remove a number of directories that are not needed by 
spong-client. (Assuming a standard installation directory). 

=over

=item www/

=item cgi-bin/

=back

The only configuration file that you have to edit is the F<etc/spong.conf> (and
F<etc/spong.conf.E<gt>hostE<gt>> files(s).

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

This is the URI path to the location of the B<www-spong> CGI program in the web
server's document tree. For example, if the URL of www-spong is going to be
C<http://www.example.org/spong/cgi-bin/www-spong>, you need to set I<$WWWSPONG>
to '/spong/cgi-bin/www-spong'. See also L</"Spong CGI Directory">.

=item $WWWACK

This is the URI path to the location of the B<www-spong-ack> CGI program in the
web server's document tree. For example, if the URL of www-spong is going to be
C<http://www.example.org/spong/cgi-bin/www-spong-ack>, you need to set
I<$WWWSPONG> to '/spong/cgi-bin/www-spong-ack'. See also
 L</"Spong CGI Directory">.

=item $WWWGIF

This is the URI path to the location of the SPONG/www/gifs/ directory in the
web server's document tree. If the location of the images directory is
C<http://www.example.org/spong/gifs/>, then $WWWGIF is set to '/spong/gifs'.
See also L</"Spong HTML Directory">.

=item $WWWHTML

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

=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 alias-ed
into the desired location. For example, for Apache a sample configuration
line would be:

  ScriptAlias /spong/cgi-bin/ /usr/local/spong/cgi-bin/

=item Spong HTML Directory

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:

  Alias /spong/ /usr/local/spong/www/

=back

=back

=head2 TCP Wrappers

The B<spong-server> can use the TCP Wrappers library to validate incoming
connection. The use of TCP Wrappers is optional. It is not required.

To use the TCP Wrappers library, the F<Authen::Libwrap> Perl module must be
installed on the Spong Server host. The F<Authen::Libwrap> module can be found
in the Comprehensive Perl Archive Network (http://www.cpan.org/). 

The service names for the F<hosts_allow> and F<hosts_deny> files are as follows

=over

=item spong-update

The service that Spong Client programs use to send status update messages.

=item spong-bb-update

The Big Brother (http://bb4.com) Server Emulation. BB Clients use this service
for sending status update messages.

=item spong-query

Service that Spong Display clients use for Spong Database queries

=over


=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
printed. The higher the number the more detail that is output.  This force the
program to run in the fore-ground, (if it daemonizes itself) and the program
will print out a lot of debugging statements. Also each program updates it's
command line buffer with the current status which can be viewed in the C<ps>
command.

If I<$SPONG_LOG_FILE> or I<$SPONG_LOG_SYSLOG> are set in the F<spong.conf> file
the programs will log errors to a log file and/or syslog , respectively. The
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.

=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
statements to the screen. The I<query> processing will print out all of the
database queries with the type of data requested and in what format. The
I<spong update> and I<Big Brother update> process will print out
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> level is at least 3.

=head2 B<spong-client>

B<spong-client> will print out the check that is being performed along with
the status and the summary message.

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

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

    spong-message --debug color host service time "Summary message"

where:

=over 

=item time

a number which is the date/time in epoch format (i.e.
the number of seconds since 00:00 01/01/1970). Just pick a big number.

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

After the rules matching phase, spong-message will then print out all of the
people being notified and how they are being notified. B<spong-message> can
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
web pages. If a header and/or footer template file exist, the contents of the
field will be display as a header or footer of every web page generated. The
header or footer files should be placed in the F</html> directory where the
Spong www/ directory was installed (the I<$IWWW> variable from the B<build>
program) and named "header.html" or "footer.html", respectively.

Place the HTML code that you want display into the template files.
You can also specify other HTML files to be included when the file is
display. Insert the string "B<!!WWWSHOW!!>/filename" into
the place that your desire the file named "filename" to be display. The
file to be include should placed into the same directory are the "header.html"
or "footer.html" file resides.

B<Note:> This customization feature is limited in the current release.
More substitution variables (i.e. hostname, service, status, etc)
will be added into future. As will the ability to select which type of
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 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
particular host. To use this feature, you first have to create an info
directory in a host's database directory (i.e.
L<$SPONGDB|spong.conf/"$SPONGDB">/hostname/info/).  Then you place the
documentation files that will displayed into that directory.  L<spong-server>
looks for the the following files:

=over 12

=item I<$SPONGDB>/E<lt>hostnameE<gt>/info/info.txt

=item I<$SPONGDB>/E<lt>hostnameE<gt>/info/info.html

=item I<$SPONGDB>/E<lt>hostnameE<gt>/info/info.brief.txt

=item I<$SPONGDB>/E<lt>hostnameE<gt>/info/info.standard.txt

=item I<$SPONGDB>/E<lt>hostnameE<gt>/info/info.full.txt

=item I<$SPONGDB>/E<lt>hostnameE<gt>/info/info.brief.html

=item I<$SPONGDB>/E<lt>hostnameE<gt>/info/info.standard.html

=item I<$SPONGDB>/E<lt>hostnameE<gt>/info/info.full.html

=back 

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>
will look for a F<info.txt> or F<info.html> file and then display that file as
a default.

The .txt files are used with text mode displays like those generated by the
B<spong> display command (see L<spong>). The .html files are used by the html
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,
the web page knows which host your are looking at when on your are looking at a
detailed status page. The spong-server generated a customize "Contact Staff"
link on a page's action bar that has the hostname and a message which contains
all of the current problems that system currently has.

The "Contact Staff" link URL consists of two parts. The first part is the
I<$WWWCONTACT> from the F<spong.conf> configuration file (see
L<spong.conf/"$WWWCONTACT">). It contains the URL to your contact
staff CGI program that you must supply (see below).  The second part of the are
the host name and the problem message passed as two form variables: I<host>
and I<message> respectively.

The I<$WWWCONTACT> CGI program needs to handle two form variables (I<host> and
I<message>) and a couple of fields on a form for the user to fill out. A TEXT
field should be used to the I<host> variable with a size of 50 characters of so
to handle big host names. The I<message> field should be placed in a TEXT AREA
field. The size of the TEXT AREA field should be limited if the destinations
are pager. Most alpha-pages have a message limit of 150-250 characters.  The
rest of the form should be populated with whatever fields that you need into
order to interface to your paging applications

=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>
configuration parameter (see L<spong.conf/"$WWW_ACTIONBAR_CUSTOM">). Any HTML
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
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
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 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
L<spong.conf>). The B<spong-server> the matches the I<REMOTE_ADDR>,
I<REMOTE_HOST>, and I<REMOTE_USER> fields in the CGI environment against the
list of REFRESH_ALLOW expressions.  If there is a match the session if ok'ed for
auto-refreshes. The server then checks the I<REMOTE_xxx> fields against the
list of REFRESH_DENY expressions.  A match here disallows auto-refresh even if
there was a previous match of a REFRESH_ALLOW expression.

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

=head1 AUTHOR

Stephen L Johnson <F<sjohnson@monsters.org>>