====== Xymon.pm ======

^ Author | [[ nelis@nlr.nl | wnelis ]] |
^ Compatibility | Xymon 4.x |
^ Requirements | Perl |
^ Download | http://sourceforge.net/projects/xymonconfigsync/ |
^ Last Update | 2009-04-10 |

===== Description =====

The Xymon configuration files, and especially bb-hosts, contain information which is often also available in a configuration database. It would be nice if changes in the database are automatically replicated in the configuration files: it would eliminate the need to enter a change multiple times. The information in the database is generally not sufficient to generate a Xymon configuration file completely, thus some sort of synchronization between them is needed. Module Xymon.pm offers a part of a synchronization solution: it allows one to read a Xymon configuration file, to add, delete or change elements in it and to rewrite the file.

Module Xymon.pm is to be used in a script which reads the configuration database, and updates the configuration file accordingly. This script is specific to each company: it depends on the servers and services monitored in Xymon, the information available in a configuration database and the local policies with respect to the use of that information.

===== Installation =====

Not really applicable: it is to be installed in the search path of Perl.

===== Source =====

The module is available at [[http://sourceforge.net/projects/xymonconfigsync/|sourceforge]]. To give an idea how it is used, the code snippet showing a way to generate a part of the Xymon host configuration file is shown below. In this example, an include file is generated in which printers are checked. The information about the printers, such as their name, IP address and location, is extracted from a database and is saved in hash %Ncm. As devmon is used to test the printers, the tests to be performed are specified in the devmon templates. The tags for a printer can be generated too, but in principle the tags are taken from the current include file. Thus manual modifications in the tests (tags) of a printer are maintained.

<hidden onHidden="Show Code ⇲" onVisible="Hide Code ⇱">
<code>
 sub BuildComment(@)    { return Xymon::CommentRecord->new( @_ )  ; }
 sub BuildEmptyLines($) { return Xymon::EmptyRecord->new( $_[0] ) ; }
 sub BuildLayout(@)     { return Xymon::LayoutRecord->new ( @_ )  ; }
 sub BuildHost(@)       { return Xymon::HostRecord->new( @_ )     ; }
 
 #
 # Update the Xymon tests of the printers. These tests can be generated
 # completely using information from the configuration database only. However,
 # manual modifications of the tests are maintained.
 #
 sub UpdatePrinter() {
   my $XMPrinterFil= '/home/xymon/server/etc/bb-hosts-printer' ;
   my %Printer= () ;			# List of printers
   my $OldFile= undef ;			# Ref to an existing bb-hosts file
   my $NewFile= undef ;			# Ref to rebuilded file
   my @Host ;				# List of references to one host
   my $AHost ;				# Ref to a host object
   my $Descr ;				# DESCR tag
   my ($AnIf,$Site,$Loc,$ph) ;		# Loop control variables
 
  #
  # %Ncm contains information of all devices. This information is retrieved from
  # the Network Configuration Management database. Build a list of printers and
  # group them by location.
  #
   foreach $AnIf ( keys %Ncm ) {
     next			unless $Ncm{$AnIf}{Category} eq "Printer" ;
     $Site= $Ncm{$AnIf}{Site} ;
     $Loc = $Ncm{$AnIf}{Room} ;
     $Printer{$Site}{$Loc}{$AnIf}= $Ncm{$AnIf} ;
   }  # of foreach
 
  #
  # Using the previously generated version of the file, if any, make a new
  # version of the printer tests.
  #
   $OldFile= $BbHosts->locateFile( $XMPrinterFil ) ;
   $NewFile= Xymon::HostFile->new( $XMPrinterFil ) ;
   $NewFile->addRecord( BuildLayout( "page Printer Printers" ) ) ;
   $NewFile->addRecord( BuildEmptyLines( 1 ) ) ;
   $NewFile->addRecord( BuildLayout( "title Printers" ) ) ;
   
   foreach $Site( sort keys %Printer ) {
     $NewFile->addRecord( BuildLayout( "subpage Printer" . ucfirst($Site) .
 		" Printers " . uc($Site) ) ) ;
     foreach $Loc ( sort keys %{$Printer{$Site}} ) {
       $NewFile->addRecord( BuildLayout( "  group $Loc" ) ) ;
       foreach $AnIf ( sort keys %{$Printer{$Site}{$Loc}} ) {
 	$ph= $Printer{$Site}{$Loc}{$AnIf} ;	# Ref to printer info
 	@Host= () ;  $AHost= undef ;
 	@Host= $OldFile->locateHostRecord( $AnIf, 0 ) if defined $OldFile ;
 	@Host= $BbHosts->locateHostRecord( $AnIf, 1 ) unless @Host ;
 	if ( @Host ) {
 	  foreach ( @Host ) {
 	    next		unless $_->isTagUsed( "prefer" ) ;
 	    $AHost= $_->clone ;		# Create copy of this host
 	    $_->delete ;			# Remove original
 	    last ;
 	  }  # of foreach
 	}  # of if
 	unless ( defined $AHost ) {
 	  $Descr= sprintf( "DESCR:\"%s:Room=%s\"", $$ph{Description}, $$ph{Room} ) ;
 	  $AHost= BuildHost( $$ph{IpAddress}, $AnIf, $Descr,
 		"DEVMON:model(any;printer)", "prefer" ) ;
 	}  # of unless
 	$NewFile->addRecord( $AHost ) ;
       }  # of foreach
     }  # of foreach
     $NewFile->addRecord( BuildEmptyLines( 1 ) ) ;
   }  # of foreach
  #
  # Save the new version if there is no old version or if it differs from
  # the old version.
  #
   if ( defined $OldFile ) {
     $NewFile->optimize ;
     if ( $OldFile->compare($NewFile) ) {
       $_->clearFlags		foreach ( @{$$OldFile{xfRecord}} ) ;
     } else {
       $BbHosts->replaceFile( $NewFile ) ;
   } else {      
     $NewFile->writeFile ;
   }  # of else
 }  # of UpdatePrinter
</code>
</hidden>

===== Known  Bugs and Issues =====

Module Xymon.pm is up to now only used to update the bb-hosts file.

===== To Do =====

===== Credits =====

===== Changelog =====

  * **2009-04-10**
    * Initial release