Difference between revisions of "RANCID RWS"

From OpenNMS
Jump to: navigation, search
(Install and configure RANCID)
(Getting Help)
Line 318: Line 318:
== Getting Help ==
== Getting Help ==
If you continue to have issues, Rocco Rionero wrote a fantastic [http://opennms.svn.sourceforge.net/viewvc/opennms/rancid-api/trunk/src/main/webapp/cgi-bin/README?revision=HEAD README].  Take a look through that for details.  If you still have problems, please try the [[Mailing lists|discussion lists]].
If you continue to have issues, Rocco Rionero wrote a fantastic [http://opennms.git.sourceforge.net/git/gitweb.cgi?p=opennms/rancid-api;a=blob;f=src/README;h=549a558f96eb4fca41d3a5fccb2496172c3484f1;hb=HEAD README].  Take a look through that for details.  If you still have problems, please try the [[Mailing lists|discussion lists]].
== Caution  ==
== Caution  ==

Revision as of 15:27, 13 October 2011

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.


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 rancid.conf:

LIST_OF_GROUPS="Home ProvisionOpenNMSGRoup1 ProvisionOpenNMSGroup2"

Set the OpenNMS notification command in rancid.conf

If your OpenNMS server is at

Add the following to your RANCID_HOME/etc/rancid.conf file to tell RANCID the command to send traps to OpenNMS. For instance, if RANCID_HOME is /opt/rancid:

 OPENNMS_NOTIFY_CMD="/opt/rancid/bin/rancid-trap -r";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/*

Configure httpd.conf

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 mod_setenv's 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 "/var/www/rws-server/html">
    Options Indexes FollowSymLinks
    AllowOverride None
    Order allow,deny
    Allow from all


Configure rancid.rws.rc RWS Configuration File

Finally, configure the rws-server configuration file in /var/www/rws-server/rws-cgi/rancid.rws.rc.

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 /var/www path.
  • 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:

<base-url server_url="http://localhost"/>


<base-url server_url="http://rws.mycompany.org"/>

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 -->
<policy-manage name="example1">
  <package name="example1">
    <filter>IPADDR != ''</filter>
    <include-range begin="" end="" />
  <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"/>
  <mapping sysoid-mask="." type="cisco"/>
  <mapping sysoid-mask="." type="cat5"/>
  <mapping sysoid-mask="." type="extreme"/>
  <mapping sysoid-mask="." type="juniper"/>
  <mapping sysoid-mask="." type="erx"/>
  <mapping sysoid-mask="." type="hp"/>

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 .cloginrc file:

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'

Getting Help

If you continue to have issues, Rocco Rionero wrote a fantastic README. Take a look through that for details. If you still have problems, please try the discussion lists.


Please backup your RANCID configuration. The RWS server will update the .cloginrc file as changes are made inside OpenNMS.