From e457c638c6ad83b87fbb0d6f2de1bcdae17c739a Mon Sep 17 00:00:00 2001 From: Stephen L Johnson Date: Tue, 12 Sep 2000 19:21:00 +0000 Subject: [PATCH] documentation updates --- pod/admin-guide.pod | 61 ++--- pod/developer-guide.pod | 92 ++++---- pod/spong-ack.pod | 149 ++++++++++++ pod/spong-client-mod-template.pod | 186 +++++++-------- pod/spong-client.pod | 258 ++++++++++++++++++++ pod/spong-intro.pod | 84 ++++--- pod/spong-message.pod | 364 +++++++++++++++++++++++++++++ pod/spong-network-mod-template.pod | 190 +++++++-------- pod/spong-network.pod | 214 +++++++++++++++++ pod/spong-server-mod-template.pod | 162 ++++++------- pod/spong-server.pod | 251 ++++++++++++++++++++ pod/spong.conf.pod | 81 ++++--- pod/spong.groups.pod | 37 +-- pod/spong.hosts.pod | 141 ++++++----- pod/spong.message.pod | 41 ++-- pod/spongfaq.pod | 21 +- pod/www-spong-ack.pod | 91 ++++++++ pod/www-spong.pod | 191 +++++++++++++++ 18 files changed, 2092 insertions(+), 522 deletions(-) create mode 100644 pod/spong-ack.pod create mode 100644 pod/spong-client.pod create mode 100644 pod/spong-message.pod create mode 100644 pod/spong-network.pod create mode 100644 pod/spong-server.pod create mode 100644 pod/www-spong-ack.pod create mode 100644 pod/www-spong.pod diff --git a/pod/admin-guide.pod b/pod/admin-guide.pod index 8f208ad..62f842c 100755 --- a/pod/admin-guide.pod +++ b/pod/admin-guide.pod @@ -13,18 +13,19 @@ configure the Spong Server and Spong Client programs. 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 machne for the spong web display program. It is not +running on the same machine for the spong web display program. It is not required, but it will simplify the installation. -=over +=over 8 -=item o +=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 o + +=item * Check to make sure there is a config/spong.conf.EosE file corresponding to your operating system, if not - create one. This file contains paths and @@ -32,10 +33,11 @@ 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.EosE file, then please email it to me so that I can add it to the distribution. -=item o + +=item * Make sure you are in the directory that you unpacked spong in and type: -C<./build EosE> where EosE is the name corresponding to your +C<./build > where EosE is the name corresponding to your operating system. You can type C<./build help> to generate a list of valid operating system strings. @@ -46,7 +48,8 @@ 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 o + +=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 @@ -55,14 +58,15 @@ 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 o + +=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 +=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. @@ -72,13 +76,13 @@ 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 Part of spong-server's status message authentification has +B Part of spong-server's status message authentication has to do with host names. B 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 +domain name. To do this check there is a little Perl test program B from in the F directory of the Spong distribution. Just run it from a command line by entering C It tests to see is the host can resolve it's fully qualified domain name. If it can't then it @@ -113,17 +117,17 @@ location as the original client. =head2 Debugging Problems The general way to debug Spong programs is to use the B<--debug #> parameter. -The B<#> is a number from 1 to 9 that contols the amount of debugging that is +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 ps +command line buffer with the current status which can be viewed in the C command. If I<$SPONG_LOG_FILE> or I<$SPONG_LOG_SYSLOG> are set in the F file 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 priorty of ERR. +entries are logged to syslog under the USER facility with a priority of ERR. =over @@ -135,11 +139,11 @@ 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 processing will print out all of the database queries with the type of data requested and in what format. The -I and I process will print out +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, will call B with the +a notification is indicated, B will call B with the B<--debug> parameter if B<--debug> was specified in the command line. =item B @@ -169,7 +173,9 @@ where: 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 +=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 @@ -190,14 +196,14 @@ Spong www/ directory was installed (the I<$IWWW> variable from the B program) and named "header.html" or "footer.html", respectively. Place the HTML code that you want display into the template files. -You can also specifiy other HTML files to be included when the file is +You can also specify other HTML files to be included when the file is display. Insert the string "B/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 This customization feature is limited in the current release. -More substiution variables (i.e. hostname, service, status, etc) +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.) @@ -245,7 +251,7 @@ a default. The .txt files are used with text mode displays like those generated by the B display command (see L). The .html files are used by the html -mode displays. The .html files can contain html code, URLs, embeded graphics, +mode displays. The .html files can contain html code, URLs, embedded graphics, Javascript, or anything that you display on a web page. @@ -257,7 +263,7 @@ 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's URL consists of two parts. The first part is the +The "Contact Staff" link URL consists of two parts. The first part is the I<$WWWCONTACT> from the F configuration file (see L). It contains the URL to your contact staff CGI program that you must supply (see below). The second part of the are @@ -275,11 +281,10 @@ order to interface to your paging applications =head2 Customized Action Bar -The Action Bar of the Host and Service Status Displays (see the L for more details) can be customized with the -I<$WWW_ACTIONBAR_CUSTOM> configuration parameter (see -L). Any HTML code -defined in this parameter will be included at the end of the Action 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> +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 @@ -290,7 +295,7 @@ 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 B<$WWW_REFRESH> Logic +=head2 $WWW_REFRESH Logic 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 @@ -307,7 +312,7 @@ For example, if I<@WWW_REFRESH_ALLOW> contains[ 'joe', '.*-support', 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. +enabled because 'fred' is in the I@ list. =head1 SEE ALSO diff --git a/pod/developer-guide.pod b/pod/developer-guide.pod index 35918a3..9710276 100755 --- a/pod/developer-guide.pod +++ b/pod/developer-guide.pod @@ -5,13 +5,13 @@ B - developer's guide to Spong =head1 DESCRIPTION This is the developer guild to Spong. It documents the inner workings of the -client and server programs. It also describes the plugin mechanism of the +client and server programs. It also describes the plug-in mechanism of the B and B so that new check modules can be developed for these programs. =head1 PROTOCOLS -This section deals with the low level communucation protocols that the clients +This section deals with the low level communication protocols that the clients use to talk with the B. The Spong and Big Brothers protocols almost identical. They vary only in the data format. @@ -21,7 +21,7 @@ The B listens in on port 1998 for status updates from clients. After a socket has been opened, the client program sends a message with the following format: - command host service color time[:ttl] summary (\n) + command host service color time[:TTL] summary (\n) detailed status message line 1 (\n) detailed status message line 2 (\n) ... @@ -29,7 +29,7 @@ following format: Where: -=over +=over 4 =item command @@ -56,24 +56,24 @@ The status color of the service (green - ok, yellow The date/time of the update message in epoch time format (i.e. the number of seconds since 01/01/70, 00:00 AM) -=item ttl +=item TTL This optional field is the time to live, in seconds, for the status message. Normally a will become stale (i.e. purple status) after 2 times $SPONGSLEEP -seconds which is the default. See L. This field will +override the default and keep the status message valid for a longer period of time. =item summary The status summary message field. A short and to the point message that -summarises the status being returned. +summarizes the status being returned. =item detailed status message The remained lines of the message which will be the detailed information of the -status. Typically it can be the output of the df command or the top processes -by CPU utilization or the detailed reponses of network checks. +status. Typically it can be the output of the C command or the top processes +by CPU utilization or the detailed responses of network checks. =back @@ -91,7 +91,7 @@ with the following format: Where: -=over +=over 4 =item command @@ -129,7 +129,7 @@ The status summary message field. The remained lines of the message which will be the detailed information of the status. Typically it can be the output of the df command or the top processes by CPU utilization -or the detailed reponses of network checks. +or the detailed responses of network checks. =back @@ -137,10 +137,10 @@ or the detailed reponses of network checks. B, B, B and B use various routines which are coded as modules. When the programs are -initializating, they determine which modules are going to be required. The +initializing, they determine which modules are going to be required. The programs then go out and load each of the modules from the library directory. -When the modules are loaded they register themselves with the plugins -registery. The plugin registry is the mechanism that the client programs use +When the modules are loaded they register themselves with the plug-ins +registry. The plug-in registry is the mechanism that the client programs use to keep track of the modules into order to run them. =head2 SERVER MODULES @@ -194,14 +194,14 @@ that 10 seconds be used for the alarm setting. The module should not call the Emain::status() function directly. B has a mechanism for rechecking services that are reported down -on an initial check. If the recheck mechanism is engauged, "red" statuses will +on an initial check. If the recheck mechanism is engaged, "red" statuses will be downgraded to "yellow" until a failure count threshold is reached. The the services will be reported as "red". After the status condition has been determined the check function should return -three parameterers: +three parameters: -=over +=over 4 =item STATUS @@ -220,7 +220,7 @@ more detailed information (can be multi-lined) These parameters are the same that will be passed to the Cmain::status()> command. See L<"Status Function"> for more information on these parameters. -The network modules have two support functions avaiable, +The network modules have two support functions available, Cmain::check_tcp()> and Cmain::check_simple()>, which can simplify simple TCP port checks. @@ -228,7 +228,7 @@ Cmain::check_tcp( host, port, data );> Where the arguments are: -=over +=over 4 =item HOST @@ -252,7 +252,7 @@ Cmain::check_simple( host, port, send, check, service)> Where the arguments are -=over +=over 4 =item HOST @@ -264,7 +264,7 @@ The name of the port to connect with. =item SEND -The messge to sent to the host after the port is opened. +The message to sent to the host after the port is opened. =item CHECK @@ -273,7 +273,7 @@ by the host. =item SERVICE -The name of the sevive being check. It is used in the summary +The name of the service being check. It is used in the summary and detailed status messages. The function Cmain::check_simple()> is a generic TCP port checking @@ -297,7 +297,7 @@ message to the contact. The messaging functions has access to these global variable in order format a notification message: -=over +=over 4 =item I<$color> @@ -314,7 +314,7 @@ epoch time or time()) =item I<$message> -A one line summary status line +A one line summary status line =item I<$duration> @@ -337,7 +337,7 @@ Cmain::email_mini_status( recipient, flags )> Where the arguments to the functions are: -=over +=over 4 =item RECIPIENT @@ -358,43 +358,43 @@ $hostname, and $summary from being placed on the "subject:" line. Creating the actual modules is very trivia to do. Create your module by following the appropriate template from below. -=over +=over 4 -=item o +=item * -L +L -=item o +=item * -L +L -=item o +=item * -L +L -=item o +=item * -L +L =back -Then place your template module file into the appropirate directory below. +Then place your template module file into the appropriate directory below. -=over +=over 4 -=item +=item * B - F -=item +=item * -B - F +B - F -=item +=item * B - F -=item +=item * B - F @@ -409,7 +409,7 @@ Emain::status( SERVERADDR, HOST, SERVICE, COLOR, SUMMARY, MESSAGE ) The arguments to the Cmain::status()> function are: -=over 8 +=over 4 =item SERVERADDR @@ -431,7 +431,7 @@ The color of the status being reported, either "green", "yellow", or "red". normal parameters. "yellow" denotes a warning status, a abnormal situation that has which may be need to be looked at or a parameter has changed (up or down) towards a critical level. "red" denotes an alert status, a critical situation -that has arised and needs immediate attenation or a parameter has changed (up +that has arisen and needs immediate attention or a parameter has changed (up or down) to a critical level. =item SUMMARY @@ -450,7 +450,7 @@ processes), report the names of those items that are abnormal, (i.e. =item MESSAGE This is the place to put detailed information about the status of the service. -Typically this will be the output of the system commands or function calls. For example, it could be the 10 jobs by cpu usage in a ps command, or the output +Typically this will be the output of the system commands or function calls. For example, it could be the 10 jobs by cpu usage in a C command, or the output of a df command for disk checking. There are no limitations on the contexts of the field. You can include URL's @@ -461,7 +461,7 @@ for the service in question. =head1 SEE ALSO -L, L, L, L, +L, L, L, L, L, L, L, L, L diff --git a/pod/spong-ack.pod b/pod/spong-ack.pod new file mode 100644 index 0000000..7798f8a --- /dev/null +++ b/pod/spong-ack.pod @@ -0,0 +1,149 @@ +=head1 NAME + +B - Spong acknowledgment tool + +=head1 SYNOPSIS + +B [B<--debug>] [B<--batch>] host services time [message] + +B [B<--debug>] B<--delete> ack-id + +=head1 DESCRIPTION + +When a spong event occurs (or will occur), you can use this tool to acknowledge +that you know that there is a problem. You can provide text that will be seen +by others looking at the event (via a spong display program). You can specify +at time limit that the problem will occur. If a problem has been acknowledged, +you will no longer received notifications of the problem, and the display +programs will show the status of the service as "blue". + +=head1 OPTIONS + +=over + +=item B<--debug> + +Print debugging statements. This option can be specified while creating or deleting acks. + +=item B<--batch> + +Print the ack-id instead of the normal output. The primary use of this parameter +is for scripts. An ack can be created when a job that runs causes a service to +temporarily exceed it's normally limits, or if a service is taken down for an +unknown or irregular length of time. + +=item B<--delete> + +Delete a previously created ack. + +=back + +Here is a description of the arguments for creating acks: + +=over + +=item host + +The host having the problem(s) you are acknowledging. + +=item service + +The service or services (separated by ".") or I services that your are +acknowledging. + +=item time + +The that the acknowledgement will late. This can be an offset "+1h, +3a,d +1w" or +an absolute date and/or time indicator "12/25/1997 14:00:00. The date needs to be +a 4 digit year, and the time needs to be in 24 hour format. + +=item message + +An optional message that will appear to those viewing the state of the host with a +spong display program. If the value is "-", then the message will read from STDIN. + +=back + +Here is a description of the arguments for deleting acks: + +=over + +=item ack-id + +The acknowledgment id to delete. The id can be obtained by using the B<--batch> +parameter when creating the acknowledgment, or by using the L command +with the B<--brief> and B<--ack> parameters. + +=back + +=head1 CONFIGURATION + +=head2 Configuration Files + +B reads the standard spong.conf and spong.conf.EhostE +configuration files. + +=head2 Configuration Variables + +=over + +=item $SPONGSERVER + +The host that at least the L and L +programs are running on. Typically the L program runs on that +host as well. + +=item $SPONG_UPDATE_PORT + +This variable defines the port that the L update process listens +on. If this variable is not defined on the I<$SPONGSERVER> host, the +L update process will not be started. The default value is 1998. + +=back + +=head1 FILES + +F, FhostE> + +=head1 EXAMPLES + + spong-ack mailhub.my-inc.com all '05/27/2000 06:00:00' 'Server is being upgraded' + + spong-ack www5.my-inc.com http +1h 'Web server is randomly dying. Investigating.' + +In a shell script: + + ... + HOST=`hostname` + ACKID=`spong-ack --batch $HOST cpu +8h 'Database exports are running'` + ... + # Database exports are done here + ... + spong-ack --delete $ACKID + ... + +=head1 DEPENDENCIES + +Perl v5.005_03 or greater is required. + +=head1 BUGS + +No know bugs. + +=head1 SEE ALSO + +L, L, L + +=head1 AUTHOR + +Stephen L Johnson > + +=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. + + diff --git a/pod/spong-client-mod-template.pod b/pod/spong-client-mod-template.pod index 7ff56b2..4d991ee 100755 --- a/pod/spong-client-mod-template.pod +++ b/pod/spong-client-mod-template.pod @@ -1,93 +1,93 @@ -=head1 NAME - -spong-client-mod-template - how to create modules for spong-client - -=head1 DESCRIPTION - -This document describes how to create your own plugin modules for -the B program. Your modules can be your own new custom check or -they can replacements for the core Spong modules. - -This template assumes that you are creating a new client check -called 'mailq'. The name of the file created should be 'check_mailq'. The -file name for B modules should always be 'check_' plus the -registry name (e.g. for the foo check, the registry name is 'foo' and the file -name is 'check_foo'). - -The line that has the assignment to I<$CHECKFUNC{'registry-name'}> is the -key to the registry mechanism. It's what ties the registry name to the -actual checking function. - -The registry name does not always have to match up to the service name as in -this case of out module 'mailq'. If you where creating a new and improved -function to check mail queues, you could create a module called 'my_mailq'. You -would use the registry name 'my_mailq', but you would use the service name -'mailq' in the Cstatus()> function when reporting your info back to -the server. - -check_mailq: - - # Register my routine with plugin registry - $CHECKFUNCS{'mailq'} = &check_mailq; - - # Sendmail mail queue check for mail servers. It checks the number of mail - # message queued against the $MAILQWARN AND $MAILQCRIT variables. - # It runs the command in the config variable $MAILQ to do it's check. - - sub check_mailq { - my($mqcnt, $message, $color, $summary ); - - open (FOO,"$MAILQ |"); - - $mqcnt = 0; - while (<FOO>) { - if (/Mail Queue\s+\((\d+)/) { $mqcnt = $1; } - - # Grab enough to get the first 10 entries. - if (++$lines <= 35) { $message .= $_ }; - } - close FOO; - - $color = "green"; - - if ($mqcnt > $MAILQWARN) { $color = "yellow"; } - if ($mqcnt > $MAILQCRIT) { $color = "red"; } - $summary = "Mail Queue count = $mqcnt" - - &main::debug("mailq - $color, $summary") - &main::status( $SPONGSERVER, $HOST, "mailq", $color, - $summary, $message ); - - } - - # I'm include perl code, I need this line. - 1; - -Please note the final line. It is always required for a module file. - -The I<$MAILQWARN> and I<$MAILQCRIT> variables are added to the F -or FhostnameE> configuration files. These variable define -the warning and alert threshold levels for your custom check. - -Configuration variable for your custom checks should be named to match them up -with the name of your customized check. In our case, we started our variable -names with MAILQ with matches up nicely with our module name of 'mailq'. Naming -the threshold variables $WARN_SPOOL_LEVEL and $CRIT_SPOOL_LEVEL would have made it unclear as to which check they belonged to. Keep the names similar, it will -make it easier on you and others to administer your setup in the future. - -=head1 SEE ALSO - -L, L, L - -=head1 AUTHOR - -Stephen L Johnson > - -=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. - +=head1 NAME + +spong-client-mod-template - how to create modules for spong-client + +=head1 DESCRIPTION + +This document describes how to create your own plug-in modules for +the B program. Your modules can be your own new custom check or +they can replacements for the core Spong modules. + +This template assumes that you are creating a new client check +called 'mailq'. The name of the file created should be 'check_mailq'. The +file name for B modules should always be 'check_' plus the +registry name (e.g. for the foo check, the registry name is 'foo' and the file +name is 'check_foo'). + +The line that has the assignment to I<$CHECKFUNC{'registry-name'}> is the +key to the registry mechanism. It's what ties the registry name to the +actual checking function. + +The registry name does not always have to match up to the service name as in +this case of out module 'mailq'. If you where creating a new and improved +function to check mail queues, you could create a module called 'my_mailq'. You +would use the registry name 'my_mailq', but you would use the service name +'mailq' in the Cstatus()> function when reporting your info back to +the server. + +check_mailq: + + # Register my routine with plug-in registry + $CHECKFUNCS{'mailq'} = &check_mailq; + + # Sendmail mail queue check for mail servers. It checks the number of mail + # message queued against the $MAILQWARN AND $MAILQCRIT variables. + # It runs the command in the config variable $MAILQ to do it's check. + + sub check_mailq { + my($mqcnt, $message, $color, $summary ); + + open (FOO,"$MAILQ |"); + + $mqcnt = 0; + while () { + if (/Mail Queue\s+\((\d+)/) { $mqcnt = $1; } + + # Grab enough to get the first 10 entries. + if (++$lines <= 35) { $message .= $_ }; + } + close FOO; + + $color = "green"; + + if ($mqcnt > $MAILQWARN) { $color = "yellow"; } + if ($mqcnt > $MAILQCRIT) { $color = "red"; } + $summary = "Mail Queue count = $mqcnt" + + &main::debug("mailq - $color, $summary") + &main::status( $SPONGSERVER, $HOST, "mailq", $color, + $summary, $message ); + + } + + # I'm include perl code, I need this line. + 1; + +Please note the final line. It is always required for a module file. + +The I<$MAILQWARN> and I<$MAILQCRIT> variables are added to the F +or FhostnameE> configuration files. These variable define +the warning and alert threshold levels for your custom check. + +Configuration variable for your custom checks should be named to match them up +with the name of your customized check. In our case, we started our variable +names with MAILQ with matches up nicely with our module name of 'mailq'. Naming +the threshold variables $WARN_SPOOL_LEVEL and $CRIT_SPOOL_LEVEL would have made it unclear as to which check they belonged to. Keep the names similar, it will +make it easier on you and others to administer your setup in the future. + +=head1 SEE ALSO + +L, L, L + +=head1 AUTHOR + +Stephen L Johnson > + +=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. + diff --git a/pod/spong-client.pod b/pod/spong-client.pod new file mode 100644 index 0000000..35c45b4 --- /dev/null +++ b/pod/spong-client.pod @@ -0,0 +1,258 @@ +=head1 NAME + +spong-client - report system information to spong server + +=head1 SYNOPSIS + +B [ B<--debug>|B<-d> I ] +[ B<--kill>|B<--restart>|B<--nosleep>|B<--norefresh> ] F + +=head1 DESCRIPTION + +This program is run on each Unix machine in which you want +to monitor local system attributes, and report that information to the +spong server. It runs one or more configured checks. It then sleeps for +a time period you have defined in your configuration file and does it all +again (it actually adds or subtracts a random amount of time - no more +then 10% of the total you have specified, to keep clients from sync'ing +up and overloading the spong-server). + +The checks are modular in nature. You can configure the number of checks +to run and the order in which to run to them. The list of checks that are +included are disk space, cpu load, running processes and log files. + +=head2 Format of update messages + +It sends a message for each check to the spong server and reports the +following: + +=over 4 + +=item * hostname (where is this report coming from) + +=item * service name ("disk", "cpu", "procs", "logs", "local") + +=item * color ("red", "yellow", "green") + +=item * a one line summary + +=item * a more detailed message providing additional detail. + +=back + + +The color is determined by comparing the current status of that service +against thresholds defined in the configuration file. If they are greater +then the level you have defined for a warning, then the color is yellow. +If they are greater then the critical level you have defined then the color +is red. + +The one line summary provides information that might be useful at a +glance when looking at the overall system status (such as a brief report +on the load, number of users, and uptime). + +The more detailed message contains information such as the complete +C output, or a listing of the top 10 processes sorted by CPU. + +=head2 Running the program + +You should start this program in your system startup file, and it should be +running constantly. If no parameters are specified, B forks +and detaches itself to run as a daemon. + +If you provide the B<--debug> I flag, then debugging information will be +printed to stdout, otherwise output will only be produced if there is a +problem. Where I is a number from 1 - 9. A higher number means more +verbosity in the debugging output. + +If you provide the B<--restart> flag, a signal will be sent to the spong-client +process that is currently running that will cause it to reload it's +configuration files. If you provide the B<--kill> flag, a signal will be sent +to the running spong-client process causing it to exit. + +The B<--nosleep> or B<--refresh> flag causes the program to cycle through all +of the checks once then exit. These flags can be used to run spong-client as a +cron job (B), this reduced the effectiveness of the B +module. + +=head2 Client Checks + +The checks are actually a set of modules that are called in series by +B. The list of modules to run are defined in the I<$CHECKS> +configuration variable. Upon initialization, B will load the +modules defined in I<$CHECKS> from the F +directory. As each modules is initialized, it registers itself with the the +plugins registry (see the L). + +=head2 Extending Functionality + +B, please refer to L. + +If you want to check some service which is not being checked by spong-client, +then you can define a C<&check_local()> function in your +config file (either in your standard L config file or your host specific L +file - but not both!). That function can do anything you want, but at the +end needs to call the C<&status()> function to report +what you have found to the spong server. + +=head1 CONFIGURATION + +=head2 Configuration Files + +By default this reads the L file on startup. You can +specify an alternate config file via a command line option and it will read +that file instead. If you change values in the configuration file you will need +to restart this program for those changes to be re-read. + +After reading the configuration file that you specify (or the default), +it then reads the F file where [hostname] is the +hostname 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 is a listing of the configuration variables applicable to the +B program. + +=over + +=item $SPONGSLEEP, $SPONGSERVER, $SPONG_UPDATE_PORT + +Some basic spong configuration options that define how long to sleep (in +seconds) before checking the status of a service again, the hostname of the +spong server, and the port number that the spong server listens + +=item $SPONGSLEEP{'DEFAULT'}, $SPONGSLEEP{'spong-client'} + +This the new method for specifying the $SPONGSLEEP interval for Spong programs. +If there is not $SPONGSLEEP{} entry for the program, it will use the +I<$SPONGSLEEP{'DEFAULT'}> value. If no value is then found, B +fall back to using $SPONGSLEEP. + +=item $SPONGTMP + +The directory that Spong programs use for temporary store and work files. It +should be different directory than F for operation and security reasons. + +=item $SPONG_LOG_FILE + +If set to I<1>, B will log errors to a log file in I<$SPONGTMP> +named F. + +=item $SPONG_LOG_SYSLOG + +If set to I<1>, B will log errors to the syslog using the +I facility and the B priority. + +=item $CHECKS + +A string that has the list of client check modules to run. If I<$CHECKS> is +missed or blank, spong-client defaults to "disk cpu processes logs". If the +C function is present then 'local' is appended. + +=item $CPUWARN, $CPUCRIT + +A number indicating the CPU load that triggers a problem (I<$CPUWARN> +triggers warnings - yellow, and I<$CPUCRIT> triggers alerts - red). + +=item @PROCSWARN, @PROCSCRIT + +A list of processes that should be running, if they are not running, then +trigger a problem (processes in I<@PROCSWARN> trigger a warning - yellow, and +processes in I<@PROCSCRIT> trigger an alert - red). + +=item $LOGCHECKS + +A list of hashes which defined checks to apply to log files. Each hash +contains the fields: + +=over + +=item logfile + +which is the full path to the log file to check + +=item checks + +a list of check to apply to the log file. + +=back + +Each check is a hash that contains the fields: + +=over + +=item pattern + +a Perl regular expression to be scanned for + +=item status + +the status color to reported lines matching pattern + +=item duration + +the duration (in seconds) that each event is to be reported to the server + +=item text + +a string which is the the text to be reported +back in the detailed message field of the status report (which can include +match position variables from I) + +=item id + +an optional key field to associated with each event generated. The default +key is the evaluated I field. An id key may be specified for the +for a check pattern. All hits of the pattern will be consolidated into one +event. The data of the last hit will be reported in the event. + +=back + +=item $DF, $UPTIME, $PS, $GREP + +These variables are OS specific variables, which are hopefully set +correctly for your machine, if they are not - please send me email letting +me know what OS you are running on, and what the correct value should be. + +=back + + +=head1 FILES + +F, F + +=head1 EXAMPLES + + spong-client --debug 5 --nosleep + spong-client --debug 5 + spong-client --restart + +=head1 DEPENDENCIES + +Perl v5.005_03 or greater is required. + +=head1 BUGS + +None know bugs. + +=head1 SEE ALSO + +L, F, F, L + +=head1 AUTHOR + +Ed Hill >, Unix System Administrator, The University of +Iowa + +Stephen L Johnson > + +=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. diff --git a/pod/spong-intro.pod b/pod/spong-intro.pod index 70da559..c945bef 100755 --- a/pod/spong-intro.pod +++ b/pod/spong-intro.pod @@ -43,7 +43,7 @@ verbose information to help diagnosis problems =item * -easily expandable via a plugin module facility +easily expandable via a plug-in module facility =back @@ -53,7 +53,7 @@ UniCenter, or any other commercial packages, and I have no intention of trying to turn it into one. It is not SNMP based, it communicates via simple TCP based messages. It is written in Perl, so hopefully it can be run on multiple systems (including NT - although it has not been ported yet - -but is on the todo list). +but is on the to-do list). I'm a strong believer in KISS (keep it simple stupid), and hopefully this package is as simple as possible (but no simpler). Spong is broken @@ -62,29 +62,41 @@ up into components that each do a specific thing. Listed are some of the =over -=item B +=item * + +L Text based query program, reports information about hosts that are monitored. -=item B +=item * + +L Web based query program, reports information about host that are monitored. -=item B +=item * + +L Program that runs on each monitored server. Reports host based information (disk, cpu, logs, etc.) -=item B +=item * + +L Reports on network based services (smtp, ping, http, etc.) -=item B +=item * + +L Collects information reported and responds to queries about that information. -=item B +=item * + +L Called by the B program to send out notifications when problems occur. @@ -108,20 +120,20 @@ This distribution contain the spong source, documentation, and gif images. =head1 SUPPORT -There are two mailings setup for Spong: spong-users and spong-annouce. +There are two mailings setup for Spong: spong-users and spong-announce. spong-users is for general discussions or getting help for Spong. You can -ubscribe by sending a message to spong-users-request@lists.sourceforge.net +subscribe by sending a message to spong-users-request@lists.sourceforge.net with the work subscribe in the message. Or be visiting the mailing lists -home page at F. +home page at F. -spong-annouce -is a low-volume mailing which will be used for annoucements and news concerning -Spong. It is moderated, but feel free to submit any pertinet items. You can -ubscribe by sending a message to spong-annouce-request@lists.sourceforge.net +spong-announce +is a low-volume mailing which will be used for announcements and news concerning +Spong. It is moderated, but feel free to submit any pertinent items. You can +subscribe by sending a message to spong-announce-request@lists.sourceforge.net with the work subscribe in the message. Or be visiting the mailing lists -home page at F. +home page at F. =head1 DEPENDENCES @@ -143,8 +155,8 @@ simple to setup and use. The documentation is provided in perl POD format (the old Perl pod format just didn't do all that I wanted). The installation process will create -HTML, text and man fomatted versions of the documentation. The HTML -documentation can be located anywhere. It's crosslinks should survive a move +HTML, text and man formatted versions of the documentation. The HTML +documentation can be located anywhere. It's cross-links should survive a move intact. There are four main documents that describe spong from different @@ -152,27 +164,35 @@ perspectives. =over -=item L +=item * + +L Frequently Asked Questions by users and their answers. -=item L +=item * + +L Geared towards the person who will be using the spong text or web based clients. This is the documentation that will be seen when the user clicks on the Help button provided in www-spong. -=item L +=item * + +L Written for the person who will be installing spong, and setting up the various configuration files. This provides a step by step installation process and gives some suggestions on things B can do that you might not have thought of. -=item L +=item * + +L Written for the person who wants to have B look differently, or what -to add some new feature in their version of spong, or whats to incorporate +to add some new feature in their version of spong, or wants to incorporate spong output in other programs. This details the B internals, and describes the various protocols that are used. @@ -219,7 +239,7 @@ spong-ack.pl text based acknowledgement program www-spong.pl web based spong display client -www-spong-ack.pl web based acknowledgement program +www-spong-ack.pl web based acknowledgement program docs: @@ -241,7 +261,7 @@ source kit. If either file is not available to you, send email to =head1 CHANGES The list of changes for the latest version of B can be found -at L +at I. =over @@ -255,9 +275,9 @@ database. NTP and SSH checks added to spong-network. =item Version 2.5 -First releae by Stephen L Johnson. Rules based notifications added, +First release by Stephen L Johnson. Rules based notifications added, a limited Big Brother Server emulation was to allow Big Bother Clients -to be used. A new log monitoring routnie which tracks last position read. +to be used. A new log monitoring routine which tracks last position read. Enhanced network checks to eliminate momentary network problems. =item Version 2.0 @@ -305,14 +325,14 @@ I'd also like to thank the many people who have contributed patches and comments, and where willing to try out spong and help me work out a few of the early problems. -=head2 by Stephen L johnson +=head2 by Stephen L Johnson I first found Big Brother and liked what it did. But I was put as a bit by -it being written in C and shell scripts. While purusing the Big Brother mailing +it being written in C and shell scripts. While perusing the Big Brother mailing lists archives I ran across references to Spong, and it being written in Perl. This was Spong 1.1 -I tried it out but there were some stablity problems. So I reluctantly dropped +I tried it out but there were some stability problems. So I reluctantly dropped Spong in favor of Big Brother. I didn't like some of the limitations of Big Brother, so I started hacking on the source code. To me it was akin to writing in assembler and getting a tooth pulled. I don't like either one. @@ -322,7 +342,7 @@ University of Iowa. I feel in love with Spong all over again. I asked Ed Hill if I could have Spong 2.1. He sent me the distribution and I started evaluating it again. -Spong 2.1 was a big improvement over Spong 1.1 in terms of stablility +Spong 2.1 was a big improvement over Spong 1.1 in terms of stability and features. I rolled the changes that I made to Big Brother into Spong 2.1 and I have been changing things ever since. @@ -354,6 +374,8 @@ spong-network has a memory leak when running on a Linux system and gligc 2.1.1. The program memory core size grows after each check cycle. The fix is to upgrade the glibc from version 2.1.1 to version 2.1.2. +=back + =head1 AUTHOR Ported by: diff --git a/pod/spong-message.pod b/pod/spong-message.pod new file mode 100644 index 0000000..794d27a --- /dev/null +++ b/pod/spong-message.pod @@ -0,0 +1,364 @@ +#!@@PERL@@ + +=head1 NAME + +B - send out alerts when there is a problem + +=head1 SYNOPSIS + +B [B<--debug>] [B<--file> I | B<--message> I<"detailed +message text">] I I I I