WardenWatchdog - pridany podrobne komentare

src/contrib/wardenWatchdog/WardenWatchdog.conf

@@ -13,17 +13,17 @@ $server_conf = '/opt/warden-server/etc/warden-server.conf';
 $domain_name = "warden-dev.cesnet.cz";
 
 #-------------------------------------------------------------------------------
-# email_subject -
+# email_subject - ...
 #-------------------------------------------------------------------------------
 $email_subject = "Kontrola stavu udalosti warden serveru na stroji $domain_name";
 
 #-------------------------------------------------------------------------------
-# email_server_conf -
+# email_server_conf - path and params of an email server for reports sending
 #-------------------------------------------------------------------------------
 $email_server_conf = '|/usr/sbin/sendmail -oi -t';
 
 #-------------------------------------------------------------------------------
-# sql_precondition -
+# sql_precondition - array of procedures which are executed "before" main action
 #-------------------------------------------------------------------------------
 @sql_precondition = ('DROP FUNCTION IF EXISTS iptest;', 'CREATE FUNCTION iptest(ip VARCHAR(15)) RETURNS TINYINT(1) DETERMINISTIC
 BEGIN
@@ -52,8 +52,13 @@ BEGIN
 END;');
 
 #-------------------------------------------------------------------------------
-# sql_queries -
-#              {query => ; text => ; contact => }
+# sql_queries - array of hashes of actions for the WardenWatchdog script.
+#               Each action has three followin parts:
+#               query   => sql query of an action (check) on Warden database
+#               text    => body of an email which is send to a admin of an client
+#                          in case of nonempty check result
+#               contact => contact for message, which overrides contact collumn
+#                          in a database table.
 #-------------------------------------------------------------------------------
 @sql_queries = (
  {query => "SELECT hostname, service, MAX(received) FROM events WHERE valid = 't' GROUP BY hostname, service ORDER BY MAX(received) ASC;", text => "Uvedeny klient, nebo klienti jiz delsi dobu nereportovali zadne udalosti do Wardenu. Je mozne, ze nefunguji spravne.", contact => 'jakubcegan@cesnet.cz, ph@cesnet.cz'},
@@ -62,6 +67,6 @@ END;');
  {query => "SELECT hostname, service, received, source, count(source) AS c, min(received), max(received) FROM events WHERE valid = 't' AND source_type = 'IP' AND iptest(source) GROUP BY hostname, service, source ORDER BY c DESC;", text => "Uvedeni klient, nebo klienti odesilaji udalosti se zdrojovou adresou, ktera by se nemela objevit v internetu (privatni rozsah), nebo je neplatna (prazdny oktet, oktet je vetsi nez 255, apod.). kvuli omezeni verzi MySQL serveru funguje zatim pouze pro IPv6.", contact => 'jakubcegan@cesnet.cz, ph@cesnet.cz'});
 
 #-------------------------------------------------------------------------------
-# sql_postcondition -
+# sql_postcondition - array of procedures which are executed "after" main action
 #-------------------------------------------------------------------------------
 @sql_postcondition = ('DROP FUNCTION IF EXISTS iptest;');

src/contrib/wardenWatchdog/WardenWatchdog.pm

@@ -9,7 +9,7 @@
 package WardenWatchdog;
 
 #use Data::Dumper;
-#use WardenConf;
+use WardenConf;
 use strict;
 use warnings;
 use DBI;
@@ -18,6 +18,21 @@ use DateTime;
 use Email::Simple;
 use Sys::Hostname;
 
+#-------------------------------------------------------------------------------
+# sendmail_wrapper
+#
+# Simple wrapper function for an mailserver.
+#
+# Input:
+#     message    = prepared message
+#     email_conf = configuration of a mailserver
+#
+# Output: -
+#
+# Return:
+#   On Success (1)
+#   On Failure (0, 'Error message')
+#-------------------------------------------------------------------------------
 sub sendmail_wrapper{
 
   my $message    = shift;
@@ -35,6 +50,27 @@ sub sendmail_wrapper{
 # Array of hashes
 #{query => ; text => ; contact => }
 
+
+#-------------------------------------------------------------------------------
+# send_report
+#
+# Function for creating and sending of an Watchdog status report via email to
+# administrators of an clients.
+#
+# Input:
+#   Hash of parameters:
+#     contact    => email address of a message recipient
+#     domain     => domain name of server where script runs
+#     subject    => subject of an email
+#     text       => body of an email
+#     email_conf => configuration of a mailserver
+#
+# Output: -
+#
+# Return:
+#   On Success (1)
+#   On Failure (0, 'Error message')
+#-------------------------------------------------------------------------------
 sub send_report{
 
   my $input_data = shift;
@@ -75,6 +111,26 @@ sub send_report{
   return (1);
 }
 
+#-------------------------------------------------------------------------------
+# connect_to_DB
+#
+# Just simple database wrapper for Watchdog which creates db's handler.
+#
+# Input:
+#   Hash of parameters:
+#     platform => database platform name according to Perl DBI
+#     name     => name of a database
+#     hostname => database hostname
+#     user     => username
+#     passwd   => password
+#
+# Output:
+#   dbhRef = reference on a database handler
+#
+# Return:
+#   On Success (1)
+#   On Failure (0, 'Error message')
+#-------------------------------------------------------------------------------
 sub connect_to_DB {
 
   my $dbConf = shift;
@@ -96,7 +152,21 @@ sub connect_to_DB {
   }
 }
 
-
+#-------------------------------------------------------------------------------
+# update_procedures
+#
+# Function takes DB handler and executes all database procedures in the array.
+#
+# Input:
+#   dbhRef  = reference on a database handler
+#   procRef = reference on an array of database procedures
+#
+# Output: -
+#
+# Return:
+#   On Success (1)
+#   On Failure (0, 'Error message')
+#-------------------------------------------------------------------------------
 sub update_procedures{
 
   my $dbhRef  = shift;
@@ -115,6 +185,30 @@ sub update_procedures{
   return (1);
 }
 
+#-------------------------------------------------------------------------------
+# send_query
+#
+#
+#
+# Input:
+#   dbhRef    = reference on a database handler
+#   configRef = Hash of parameters:
+#     query   => sql query of an action (check) on Warden database
+#     text    => body of an email which is send to a admin of an client
+#                in case of nonempty check result
+#     contact => contact for message, which overrides contact collumn
+#                in a database table.
+#
+# Output:
+#   eventsRef = Hash of parameters:
+#     contact   = email address of an client administrator
+#     'contact' => predefined email text + information from database obtained
+#                  by a query
+#
+# Return:
+#   On Success (1)
+#   On Failure (0, 'Error message')
+#-------------------------------------------------------------------------------
 sub send_query{
 
   my $dbhRef    = shift;
@@ -150,11 +244,13 @@ sub send_query{
 
     while(my $result = $sth->fetchrow_hashref()){
       if (defined($config[$i]{contact})){
+        # override contact from 'requestor' collumn
         $contact = $config[$i]{contact};
       }
       else{
         $contact = $result->{'requestor'};
       }
+      # information header
       if($msg_text){
         $bad_events{$contact} .= $config[$i]{text} . "\n\n";
         $bad_events{$contact} .= join(" | ", map {$_ // "UNKNOWN" } keys %$result) . "\n";
@@ -174,7 +270,23 @@ sub send_query{
   return (1);
 }
 
-
+#-------------------------------------------------------------------------------
+# run
+#
+# Main module function which takes configure file, interval and performs Warden
+# database checks described in a configuration file. Results are send to client
+# administrators or on a defined addresses if they are set in a config.
+#
+# Input:
+#   conf_file = path to a config file with database procedures and other params
+#   period    = interval in days from now back to the past for database check
+#
+# Output: -
+#
+# Return:
+#   On Success (1)
+#   On Failure (0, 'Error message')
+#-------------------------------------------------------------------------------
 sub run{
 
   my $conf_file = shift;

src/contrib/wardenWatchdog/WardenWatchdog.t

 #!/usr/bin/perl
+#
+# WardenWatchdog.t
+#
+# Copyright (C) 2011-2012 Cesnet z.s.p.o
+#
+# Use of this source is governed by a BSD-style license, see LICENSE file.
 
 use strict;
 use warnings;

src/contrib/wardenWatchdog/wardenWatchdog.pl

@@ -17,6 +17,18 @@ FindBin::again();
 use lib "$FindBin::Bin";
 use WardenWatchdog;
 
+#-------------------------------------------------------------------------------
+# help
+#
+# Just print help and exit.
+#
+# Input: -
+#
+# Output: -
+#
+# Return:
+#   On Success (1)
+#-------------------------------------------------------------------------------
 sub help {
   my $help ="  USAGE: ./wardenWatchdog.pl -c '/path/WardenWatchdog.conf' -i 7