- 1 This is for the those on the bleeding edge
- 2 OpenNMS and RANCID Integration
- 3 What is Rancid
- 4 What is RANCID RWS ?
- 5 Install and configure RANCID
- 6 Set Up the RWS Server
- 7 Set up ViewVC
- 8 Configure OpenNMS to communicate with RWS
- 9 Rancid Provisioning Adapter
- 10 Getting Help
- 11 Caution
This is for the those on the bleeding edge
RANCID RWS integration is in OpenNMS 1.7.1 and higher but is is yet considered as beta software.
OpenNMS and RANCID Integration
OpenNMS and RANCID have been integrated in three ways. The first integration has been made providing a GUI into opennms to access rancid configuration data and downloaded configurations. You are able to see the rancid data within the opennms GUI. When such Rancid Integration Enabled (just modify the right property in opennms.properties) all you have is a couple of new links in the node page and in the "admin node" page. The configurations repository is displayed embedding "viewvc" pages into the opennms GUI.
The second integration is throw what we called the Rancid Provisioning Adapter. The Rancid Provisioning Adapter is able to synchronize the nodes from opennms database to rancid device list. When you make changes to a Requisition Group and require synchronization the Rancid Provisioning Adapter is able to performs the add, delete and update operation over rancid configuration files (ie .cloginrc and router.db).
The above integrations have been made developing the awesome RWS service that is a RESTFUL Interface over Rancid.
The third integration is made by events: Rancid sends mail to group admin and user regarding the status of its downloads and operations failure, now applying a patch we provide to rancid it is possible to send traps from rancid to a management station. These traps can also be send to opennms that is configured to manage them as events.
What is Rancid
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 to 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
As most "good-old-school" unix-based tools, rancid's configuration is performed by editing a set of configuration files on the hosting system; rancid's execution is started from the system's command line or automatically scheduled via the unix cron daemon; the information repositories generated by rancid can be accessed by any CVS or Subversion browsing tool.
What is RANCID RWS ?
In order to perform a consistent integration into a general network management system (NMS), a proper application program interface (API) to rancid's configuration and information repository, was developed. It was designed according to a resource-oriented client-server model following a Representational State Transfer (REST) style of software architecture based on the Hyper Text Transfer Protocol version 1.1, that is -as commonly defined- a resource-oriented RESTful web service API.
Download RANCID RWS
The latest RWS RANCID release is available at the OpenNMS download site. Alternatively, you can build from source by running
mvn package in the source tree checked out from the RANCID API repository by cloning git://opennms.git.sourceforge.net/gitroot/opennms/rancid-api. This will create release and source tarballs in the target/ directory.
Install and configure RANCID
Download RANCID from: http://www.shrubbery.net/rancid
Note that currently RANCID needs a small patch to work with the OpenNMS integration.
It is included in the
contrib/ directory of the RANCID RWS release distribution.
The patch allow rancid to send traps to a management station. If you do not need this feature you can skip installing the patch.
The distributed patch now works for the rancid version 2.3.6 and must be applied before installing Rancid.
Here is another version of the patch for use with RANCID 2.3.4
To install the patch (es. /tmp/rancid.patch) cd to installation directory and run:
patch -Nbp1 -z .original < /tmp/rancid.patch
For more details on patch installation follow Rocco's README
After you have installed the patch you can install rancid.
And you should also configure Rancid.
If you want to user the Rancid Provisioning Adapter add the OpenNMS "Provisiong Group" to Rancid Group
setting the proper value for LIST_OF_GROUPS in
LIST_OF_GROUPS="Home ProvisionOpenNMSGRoup1 ProvisionOpenNMSGroup2"
Set the OpenNMS notification command in rancid.conf
If your OpenNMS server is at 10.11.12.13:
Add the following to your
RANCID_HOME/etc/rancid.conf file to tell RANCID the command to send traps to OpenNMS. For instance, if
OPENNMS_NOTIFY_CMD="/opt/rancid/bin/rancid-trap -r 10.11.12.13";export OPENNMS_NOTIFY_CMD
Set Up the RWS Server
The RWS Server implements a CGI Application as the middleware between OpenNMS and RANCID.
In my setup I implemented RWS as a Virtual Server on Apache. This was implemeted on RedHat 4 Enterprise.
Make the CGI Files Available to the Web Server
First, put the CGI file(s) somewhere your web server can get to them:
cd /var/www mkdir rws-server cp -R /path/to/rws/cgi-bin rws-server/rws-cgi chown rancid:root rws-server chmod -R 755 rws-server mkdir rws-server/html chown rancid:rancid rws-server/*
Then, configure your
httpd.conf so that Apache runs as the RANCID user. This step is necessary because Apache's
mod_suexec "cleans" the environment of scripts that run under it, rendering that strategy incompatible with the use of
SetEnv directive to configure the RWS services.
NameVirtualHost *:80 User rancid Group rancid <VirtualHost *:80> DocumentRoot /var/www/rws-server/html ServerName rws.mycompany.org ErrorLog logs/rws-error_log TransferLog logs/rws-access_log ScriptAlias /rws "/var/www/rws-server/rws-cgi/rws-cgi.tcl" AddHandler cgi-script .tcl SetEnv RWS_LOGFILE /var/log/httpd/rws-cgi.log SetEnv RWS_LOGLEVEL debug <Directory /var/www/rws-server/rws-cgi> AllowOverride None Order allow,deny Allow from all </Directory> <Directory "/var/www/rws-server/html"> Options Indexes FollowSymLinks AllowOverride None Order allow,deny Allow from all </Directory> </VirtualHost>
rancid.rws.rc RWS Configuration File
Finally, configure the rws-server configuration file in
The following are the settings we used in rancid.rws.rc:
set pathRancidHome "/home/rancid" set fileRancidConf "/usr/local/rancid/etc/rancid.conf" set pathBackup "/home/rancid/tmp" set pathTemp "/tmp" set commandCVS "/usr/bin/cvs" set urlViewVC "/viewvc"
Set up ViewVC
- Download latest stable viewVC from the site.
- Install it using the provided install script in your
chown -R rancid:rancid /var/www/viewvc
- Edit the viewvc config file to set the CVSROOT path.
Add it to your Apache configuration by adding this ScriptAlias under the
/rws alias :
ScriptAlias /viewvc "/var/www/viewvc/bin/cgi/viewvc.cgi"
You should be able to browse your CVS at :
Configure OpenNMS to communicate with RWS
Edit opennms.properties and change to following line from:
#opennms.rancidIntegrationEnabled = false
opennms.rancidIntegrationEnabled = true
If you want that only the Rancid Provisiong Adapter will change configuration file of rancid from opennms platform change set the following property:
opennms.rancidIntegrationUseOnlyRancidAdapter = true
We used a virtual host instead of localhost, so we edited rws-configuration.xml and change the following line:
Once these steps are done, the node details page for every node in the OpenNMS web UI will contain a View Node Rancid Inventory Info link in the General box. This link takes you to a page where you can see a summary of the node's device configurations and (if maintained in RANCID) its stored software images. From the configurations summary you can also drill into a page that embeds the ViewVC interface, which lets you browse the historical device configurations for the node.
Note that the success of this integration depends on the OpenNMS node label of a given node being identical (including upper / lower case) to the name by which RANCID knows that device. If these two names are even slightly mismatched, no configurations or software images will be visible from the OpenNMS web UI.
Rancid Provisioning Adapter
The Rancid Provisioning Adapter is now an optional component to install by default opennms installation tool. The design of this adapter is to have a full control over Rancid so that devices into rancid are mostly provided via the Rancid Provisioning Adapter.
To provide a node to Rancid the Adapter must use the "Provisioning Group" Name so a correspondence between rancid Group and provision group must be established.
If you want to provide nodes into a Provision Group "Home" then the corresponding Rancid Group "Home must exists otherwise the adapters fails to synchronize opennms and rancid.
If a node "antonio.opennms.it" is provided to the Provisioning Group "Home" then the device "antonio.opennms.it" will be added to the router.db file of the Rancid Group "Home".
You must provide also the following information to insert the node into rancid using the adapter: the ip address of the node, the username to access the node, the password, the method (Telnet, SSH, RSH) to connect to the device, the enable password, and if it uses an enable password.
Each of the above object must be added to the requisition.
To add the ip address just add an interface.
To add the username add the asset field username to the requisition.
To add the password add the asset field password to the requisition.
To add the method add the asset field connection to the requisition.
To add the enable password add the asset field enable to requisition.
To specify is there exists an enable password set the asset field autoenable to 1.
The above assets field are all required minus autoenable.
Here is a snapshot of the rancid-configuration.xml (the configuration file for rancid provisioning adapter:
<?xml version="1.0"?> <rancid-configuration delay="3600" retries="1"> <!-- Configuration example that uses policy-manage --> <policies> <policy-manage name="example1"> <package name="example1"> <filter>IPADDR != '0.0.0.0'</filter> <include-range begin="18.104.22.168" end="254.254.254.254" /> </package> <schedule name="global" type="weekly"> <time day="sunday" begins="12:30:00" ends="12:45:00"/> <time day="sunday" begins="13:30:00" ends="14:45:00"/> <time day="monday" begins="13:30:00" ends="14:45:00"/> <time day="tuesday" begins="13:00:00" ends="14:45:00"/> </schedule> </policy-manage> </policies> <mapping sysoid-mask=".22.214.171.124.126.96.36.199" type="cisco"/> <mapping sysoid-mask=".188.8.131.52.184.108.40.206" type="cat5"/> <mapping sysoid-mask=".220.127.116.11.4.1.1916.2" type="extreme"/> <mapping sysoid-mask=".18.104.22.168.4.1.2636.1" type="juniper"/> <mapping sysoid-mask=".22.214.171.124.4.1.4874.1" type="erx"/> <mapping sysoid-mask=".126.96.36.199.188.8.131.52.3.7.11" type="hp"/> </rancid-configuration>
The mapping element will map the devices to the proper rancid category using the node sysoid (default device category is cisco).
But what are the policy-manage for?
This is the way in which we try to control rancid. In router.db a router can be in state up or down. Up means download configuration, Down means do not download.
When it is received an event from rancid that a configuration has been successfully downloaded the Rancid Provisioning Adapter will set the status to down.
So in line of principle no other configuration will be downloaded later until a "configChange" event is received from the node. In this case the Rancid Provisioning Adapter will set the node to up in router.db.
To do this is introduced a delay, so that the node is set to up in router.db only after a delay time is passed. The policies enforce this to just doing such operation (setting the node to up) only on the specified timetable.
To avoid a bug you need to set up a minimal
add user cisco.example.com dummy_user add method cisco.example.com telnet add password cisco.example.com password enablepassword
It is possible to reload the rancid-configuration.xml to the adapter just run:
/opt/opennms/bin/send-event.pl uei.opennms.org/internal/reloadDaemonConfig --parm 'daemonName Provisiond.RancidProvisioningAdapter'
Please backup your RANCID configuration. The RWS server will update the .cloginrc file as changes are made inside OpenNMS.