From 1e682b0948593a3b78efc9af15d2c9c8358f6f72 Mon Sep 17 00:00:00 2001 From: Stephen L Johnson Date: Wed, 10 Jan 2001 16:31:42 +0000 Subject: [PATCH] doc updates on clear status and general administration --- pod/admin-guide.pod | 138 +++++++++++++++++++++++++++++++++----------- pod/user-guide.pod | 9 +++ 2 files changed, 114 insertions(+), 33 deletions(-) diff --git a/pod/admin-guide.pod b/pod/admin-guide.pod index e3c9f94..68bdf58 100755 --- a/pod/admin-guide.pod +++ b/pod/admin-guide.pod @@ -7,7 +7,7 @@ admin-guide - Spong Administrator's Guide 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 @@ -108,20 +108,28 @@ FhostE> 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 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 + +

+ +=end html + =over 8 =item $WWWSPONG @@ -148,31 +156,50 @@ See also L. =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 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 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 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 + +

+ +=end html + =item Web Server Configuration -On the web server side of thing your will have to configure two items: the F directory and the F CGI directory +=begin html + +

+ +=end html + +On the web server side of thing your will have to configure two items: the +F directory and the F CGI directory + +=begin html + +

+ +=end html =over 8 =item Spong CGI Directory -The F directory must be setup as a CGI directory and aliased +The F 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: @@ -180,7 +207,7 @@ line would be: =item Spong HTML Directory -The F directory must be aliased into the desired location within +The F directory must be alias-ed into the desired location within the web server document tree. If you want the F directory to be under http://www.example.org/spong/ on an Apache web server, use this configuration line: @@ -191,7 +218,7 @@ 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 @@ -206,11 +233,7 @@ the programs will log errors to a log file and/or syslog , respectively. The file are named F in the I<$SPONGTMP> directory and the entries are logged to syslog under the USER facility with a priority of ERR. - -=over - -=item B - +=head2 B 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 @@ -220,21 +243,21 @@ I and I 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 will call B with the -B<--debug> parameter if B<--debug> was specified in the command line. +a notification is indicated, B will call B with +the B<--debug> parameter if B<--debug> level is at least 3. -=item B +=head2 B B will print out the check that is being performed along with the status and the summary message. -=item B +=head2 B B 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 +=head2 B spong-message can be tested outside of spong-server to test your notification configurations. Your run spong-message with the following parameters: @@ -252,8 +275,6 @@ the number of seconds since 00:00 01/01/1970). Just pick a big number. =back -=back - B will print out the current rule number (starting with 0). The the success or failure of all of the checks of the matching attributes. @@ -263,6 +284,8 @@ people being notified and how they are being notified. B 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 @@ -285,8 +308,7 @@ 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 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 @@ -319,7 +341,6 @@ looks for the the following files: where EhostnameE is the name of a host as defined in spong.hosts. See L for most information. - B 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 @@ -331,7 +352,6 @@ B display command (see L). 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, @@ -356,7 +376,7 @@ 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 Bar +=head2 Customized Action Bars / Tool Bars The Action Bar of the Host and Service Status Displays (see L for more details) can be customized with the I<$WWW_ACTIONBAR_CUSTOM> @@ -364,15 +384,15 @@ configuration parameter (see L). 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 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 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 @@ -385,12 +405,64 @@ 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 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@ list. +=head1 SPONG-NETWORK + +=head2 Service Checks + +The service checks for a host are controlled by the I attribute +of the host's entry in the L configuration file. I is a +list of services that will checks. The services are checked in the order they +are listed in I. + +The services listed in I are actually L, and meta-services names. The +L do the actual network +service checks and meta-service names alter the default behavior of the +L program. + +At present there is only one meta-service: I. +L default behavior is to prepend a I on to +the list in the I attribute. Putting I in the list stops +this behavior. + +=head2 Service Check Flags + +=over + +=item stop_after + +The I flag (the colon (':') ) can be appended to one, or +more, services in the I attribute for a host. If the check service +with the flag fails, all remaining services are skipped and set +with the B status. + +This I flag is used to signal dependencies within the list +of tests specified in a I 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 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 flag +will cause the remaining services to be reported as B/not-available. + +Similarly, the web server need to be running for a web-application to run. So +the B check is placed before the B check in I and it is +flagged with the I flag. + +=back + =head1 SEE ALSO L, L, L diff --git a/pod/user-guide.pod b/pod/user-guide.pod index 29e1e75..3a14798 100644 --- a/pod/user-guide.pod +++ b/pod/user-guide.pod @@ -64,6 +64,15 @@ 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 program can be flagged with a +I flag. If a service with the I fails the remaining +checks will be skipped. And all of the remaining checks will have a I +status. + =back =head2 Display Modes -- 2.30.2