=============================================================================
rancid's custom notifications extensions               OpenNMS/RANCID Project

Copyright (c) 2009+ Rocco Rionero
Copyright (c) 2009+ The OpenNMS Group, Inc.
All rights reserved everywhere.

This program was developed and is maintained by Rocco RIONERO
("the author") and is subject to dual-copyright according to
the terms set in "The OpenNMS Project Contributor Agreement".

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307,
USA.

The author can be contacted at the following email address:

	Rocco RIONERO
	rock (at) rionero.com

(please, specify "rancid-trap-utility" in the subject of your message)

-----------------------------------------------------------------------------
OpenNMS Network Management System is Copyright by The OpenNMS Group, Inc.

RANCID application is Copyright by Terrapin Communications, Inc.
=============================================================================


-----------------------------------------------------------------------------
                 UNSUPPORTED BETA-RELEASE SOFTWARE VERSION
-----------------------------------------------------------------------------


1. INTRODUCTION

rancid (Really Awesome New Cisco confIg Differ) is a tool for monitoring
network devices (i.e. routers, switches, etc.) to track software and
hardware configuration changes and maintain a complete history of them by
the means of a revision's control system (i.e. CVS or Subversion) repository.
It is distributed by Shrubbery Networks, Inc (http://www.shrubbery.net/)

OpenNMS is the full-featured enterprise-grade OpenSource Network Management
System by The OpenNMS Group, Inc. (http://www.opennms.org/).

This small package was developed as part of the OpenNMS/rancid Integration
Project, in order to make rancid able to notify OpenNMS about its activities
on the monitored devices.

By installing this package, rancid's main scripts are "enhanced" with
notification ability and a new script is added to the set of rancid's
binaries. The notification extensions may be enabled/configured by
properly setting a (new) environment variable in the rancid's
configuration file "rancid.conf".

The notifications sent are SNMPv1 "traps" and include:

- device's configuration download success
- temporary device's configuration download failure
- persistent device's configuration download failure
- temporary lock-out of a rancid's group of devices
- prolonged lock-out of a rancid's group of devices
- device added to a group (*)
- device removed from a group (*)
- device's configuration change detected by rancid (*)
- rancid started processing a group (MUTEX group's lockfile acquired)
- rancid finished processing a group (MUTEX group's lockfile released)

(*) contributed by Philippe Guillebert <philippe.guillebert@bull.net>


The patch was developed for rancid version 2.3.2a9. As only the "rancid-run"
and the "control_rancid" scripts are involved (which are device-independent,
did not change in a significant way in the past and are not expected to change
in the near future), the patch should be compatible with most rancid's releases.




2. CONTENTS OF THIS PACKAGE

- README

  The short instruction file you are reading right now.


- rancid.patch

  The "patch" file (in unified-diff format) used to add notification abilities
  to rancid by modifying the original "rancid-run" and "control_rancid"
  scripts. It also includes from scratch the "rancid-trap" script, which is
  the actual trap generator (built as a wrapper for the "snmptrap" utility from
  the net-snmp package)


- RANCID-CUSTOM-MIB.mib

  A standard SNMPv1 MIB file to be loaded in the SNMP server (i.e. OpenNMS)
  in order to properly decode the SNMP traps generated by "rancid-trap"




3. INSTALLATION OVER AN ORIGINAL RANCID'S SETUP (UNPATCHED)

- uncompress/untar the distribution package into a directory of your choice;
  if you are reading this README file you almost shurely already completed
  this step :-) ... I will assume that you untarred the package in the /tmp
  directory of your system;


- the untar process created in /tmp the directory "rancid-trap-X.Y"
  (the trailing string "X.Y" being the version of the package);


- change your current working directory to the place where rancid's scripts
  are located (according to the rancid's installation performed on your
  system); I will assume that you created a "rancid" user having /home/rancid
  as home directory and that the rancid's scripts are located in the directory
  /home/rancid/bin, so you would type at your command prompt:

	cd /home/rancid/bin


- ensure that a decent version of the patch utility is installed on your
  system (any version of GNU-patch should be ok) and type at your command
  prompt:

	patch -Nbp1 -z .original < /tmp/rancid-trap-X.Y/rancid.patch

  (substitute "X.Y" with the correct version of this package)


- verify that the patch was correctly applied by checking the existence of the
  following files:

	control_rancid
	control_rancid.original
	rancid-run
	rancid-run.original
	rancid-trap
	rancid-trap.original

  where the files with the ".original" suffix are the original un-patched
  rancid's scripts saved as backup by the patch utility; note that the first
  time you apply this patch, the file named "rancid-trap.original" will have
  a 0-bytes size as the patch utility did not find any original "rancid-trap"
  file (it is not a standard rancid's script and it was just created from
  scratch) so had nothing to backup; the "control_rancid" and "rancid-run"
  files should be slightly greater in size than the corresponding original
  versions and there should not be any of them ending with the ".rej"
  extension (indicating that nothing was "rejected" by the patch utility);


- give the "rancid-trap" file the same ownership and permissions as the other
  rancid's scripts; assuming that all other rancid's script are owned by user
  "rancid" and group "users", if required, run the following command:

	chown rancid:users rancid-trap

  then type:

	chmod 0755 rancid-trap

  to give the file proper execution permissions; verify that ownership and
  permissions for "rancid-run" and "control_rancid" are set the same or adjust
  properly as described above;


- now you can type at your command prompt:

	./rancid-trap

  and a brief usage screen should appear;


- the "rancid-trap" script is a simple wrapper for "snmptrap", the trap-sender
  utility from the net-snmp package; I assume that "snmptrap" is present on
  your system and that it is found in the shell search path for the user
  running rancid; you can specify a full pathname to the "snmptrap" binary, if
  you need it, by editing the "rancid-trap" script and properly adjusting the
  value of the variable SNMP_TRAP_CMD, i.e.:

	SNMP_TRAP_CMD="/usr/local/net-snmp/snmptrap"




4. INSTALLATION OVER A RANCID'S SETUP ALREADY PATCHED WITH A PREVIOUS VERSION
   OF THE RANCID'S NOTIFICATION SYSTEM

- change your current working directory to the place where rancid's scripts
  are located, i.e.:

	cd /home/rancid/bin


- restore the original rancid's unpatched files with the following commands:

	cp rancid-run.original rancid-run
	cp control_rancid.original control_rancid


- delete the previously saved backups (restored on the step above)

	rm rancid-run.original
	rm control_rancid.original


- delete the previous rancid-trap utility and its (fake) backup copy

	rm rancid-trap
	rm rancid-trap.original


- install the new patch as described in previous SECTION 3.




5. TESTING THE TRAP GENERATIONS

- if you are already using a previous version of the rancid's notification
  system, __FIRST__ UNLOAD the previous "RANCID-CUSTOM-MIB.mib" MIB file;


- load the supplied MIB file "RANCID-CUSTOM-MIB.mib" in your SNMP server or
  network management system (i.e. OpenNMS), and ensure that it is running;


- type the following command on your rancid's host system:

	rancid-trap -c <community> -r <receiver> --failure "Just a Test"

  where <community> is the SNMPv1 community string required by your setup, and
  <receiver> is the hostname or IP address of your SNMP server (i.e. the host
  running OpenNMS)


- verify that a "rancidTrapGenericFailure" is received and that the trap
  content is correctly decoded as a "rancidFailureMessage" string with the
  value "Just a Test"




6. CONFIGURING RANCID FOR SENDING NOTIFICATIONS

- edit the rancid's configuration file "rancid.conf" and add the following lines:

	OPENNMS_NOTIFY_CMD="rancid-trap -c <community> -r <receiver>"
	export OPENNMS_NOTIFY_CMD




7. FINAL TEST

- run rancid as usual, (i.e. by typing "rancid-run <groupname>") and verify that
  at the beginning/ending of group's processing and for each processed device
  within the group a proper trap is generated and received by the SNMP
  server (i.e. OpenNMS)




8. CONCLUSION

Nothing more to say, really. For any information you can contact me at the
above email address.

Have fun, make love, live in peace.



					Rocco "rock" Rionero
					RIONERO ThinkOut Solutions
					OpenNMS/RANCID Project Team


