Shrubbery Networks Shrubbery Networks
About Shrubbery Networks
Services We Offer
Tools
Products
Customer Login
Tools
RANCID - Really Awesome New Cisco confIg Differ

RANCID monitors a router's (or more generally a device's) configuration, including software and hardware (cards, serial numbers, etc) and uses CVS (Concurrent Version System), Subversion or Git to maintain history of changes.

RANCID does this by the very simple process summarized as:

  • login to each device in the router table (router.db),
  • run various commands to get the information that will be saved,
  • cook the output; re-format, remove oscillating or incrementing data,
  • email any differences (sample) from the previous collection to a mail list,
  • and finally commit those changes to the revision control system

RANCID also includes looking glass software. It is based on Ed Kern's looking glass which was once used for http://nitrous.digex.net/, for the old-school folks who remember it. Our version has added functions, supports cisco, juniper, and foundry and uses the login scripts that come with rancid; so it can use telnet or ssh to connect to your devices(s).

Rancid currently supports Allied Telesis switches running AW+, Cisco routers, Juniper routers, Catalyst switches, Foundry switches (now Brocade), Redback NASs, ADC EZT3 muxes, MRTd (and thus likely IRRd), Alteon switches, and HP Procurve switches and a host of others.

Rancid is known to be used at: AOL, Global Crossing, MFN, NTT America, Certainty Solutions Inc.

The current version is 3.13, available from ftp or https. Read the CHANGES file for differences since the previous version.

NOTE: For rancid >= 2.3, you must use expect >= 5.40. Versions prior to this appear to have a regex handling bug that affects the ability of clogin to parse CLI prompts.

NOTE: The expect source available in the rancid ftp area has been patched for a bug that affects Linux and Solaris. The Tcl source is the mate to the supplied version of expect. See the O/S-specific section.

  1. Sample diffs (output)
  2. Getting started
    1. FreeBSD
    2. Linux
    3. OS X
    4. Solaris
  3. Getting Help
  4. Modules for other devices
  5. Web interfaces
  6. Miscellaneous RANCID information
  7. O/S-specific information
    1. FreeBSD
    2. Linux
    3. Solaris
  8. Man pages on-line
  9. Version-specific information
  10. Source repository
  11. Other monitoring packages

Some folks seem to like "testimonials", so here's my favorite one:

...I have noticed a behaviour change since implementing RANCID. The entire NOC team gets an email when a config change is made. The result is everyone is cautious about making changes on the fly, and any changes that are made are quickly explained by the changer. Before, changes would be made and if it broke something.....silence. So, at the very least we have fewer **problems** that magically appear.
-- Jason Lewis

Samples

Below are a few sample diffs (or "output") to give you an idea of the sort of things that RANCID can catch. The output is abridged, it can be quite volumous:

In this example, a Gigabit Ethernet card was removed from the router.

From: rancid <rancid@example.com>
To: rancid-example@example.com
Subject: example router config diffs
Precedence: bulk
  
Index: configs/dfw.example.com
===================================================================
retrieving revision 1.144
diff -u -4 -r1.144 dfw.example.com
@@ -57,14 +57,8 @@
  !Slot 2/MBUS: hvers 1.1
  !Slot 2/MBUS: software 01.36 (RAM) (ROM version is 01.33)
  !Slot 2/MBUS: 128 Mbytes DRAM, 16384 Kbytes SDRAM
  !
- !Slot 6: 1 Port Gigabit Ethernet
- !Slot 6/PCA: part 73-3302-03 rev C0 ver 3, serial CAB031216OL
- !Slot 6/PCA: hvers 1.1
- !Slot 6/MBUS: part 73-2146-07 rev B0 dev 0, serial CAB031112SB
- !Slot 6/MBUS: hvers 1.2
- !Slot 6/MBUS: software 01.36 (RAM) (ROM version is 01.33)
  !Slot 7: Route Processor
  !Slot 7/PCA: part 73-2170-03 rev B0 ver 3, serial CAB024901SI
  !Slot 7/PCA: hvers 1.4
  !Slot 7/MBUS: part 73-2146-06 rev A0 dev 0, serial CAB02060044
@@ -136,11 +130,8 @@
  boot system flash slot0:
  logging buffered 32768 debugging
  no logging console
  enable secret 5 $1$73Y1$grXuRjuZxfSiLYv1sBRUz0

In this one a router, pao.example.com, was added to the router table (router.db), followed by its config.

From: rancid 
To: rancid-example@example.com
Subject: example router config diffs
Precedence: bulk

Index: router.db  
===================================================================
retrieving revision 1.19  
diff -u -4 -r1.19 router.db
@@ -28,9 +28,9 @@
  nyc.example.com:cisco:up
  ord.example.com:cisco:up
+ pao.example.com:juniper:up 
Index: configs/pao.example.com
===================================================================
retrieving revision 1.1
diff -u -4 -r1.1 pao.example.com
@@ -0,0 +1,1391 @@
+ # pao.example.com> show chassis clocks
+ # Reference clock status:
+ #   Current source:           Primary
+ #   Primary source:           Internal
+ #   Secondary source:         Internal
+ #   Tertiary source:          Internal
+ #   Rollover algorithm:       Holdover
+ #   PLL mode:                 Free-running
+ #   PLL errors:               0
+ #   Sync message current:     0x00
+ #   Sync message normal:      0x00
+ #   Sync message override:    0x00
+ #   Reference clock ppm:      5
+ #
+ # pao.example.com> show chassis environment
+ #
	[ .... ]
# pao.example.com> show chassis firmware
# Part                     Type       Version
# System control board     ROM        Juniper ROM Monitor Version 3.0b1
#                          O/S        Version 3.2I1 by root on 1999-06-07 08:27
# FPC 1                    ROM        Juniper ROM Monitor Version 3.0b1
#                          O/S        Version 3.2I1 by root on 1999-06-07 08:32
# FPC 5                    ROM        Juniper ROM Monitor Version 3.0b1
#                          O/S        Version 3.2I1 by root on 1999-06-07 08:32
#
	[ .... ]
#
system {
    host-name pao;
    domain-name example.com;
    default-address-selection;
    dump-on-panic;
    dump-device /dev/wd2s1b;
	[ .... ]

<<< Contents


Getting started

The distribution includes a traditional README file with quick-start instructions, an UPGRADING file to help folks upgrage from a pre-2.3 version, and a copy of the FAQ. These generally require or assume some basic Unix and tool knowledge.

Lucky for those not yet possessing that knowledge, a few experienced folks have written articles about installing RANCID on FreeBSD, Linux, and Mac OS X or added packaging for RANCiD for various O/Ses.

NSRC has a workshop that includes instruction for RANCiD installation on Linux. Chris Boyd wrote "Getting Rancid on FreeBSD" (formerly http://ezine.daemonnews.org/200302/rancid.html) for Daemon News and Lyndon Labuschagne has written a how-to for FreeBSD 6.1 and another by Bruco Hitchcock.

There is packagng for OS X via Homebrew and Peter Harrison wrote for Linux and Linux Home Networks in "Network Device Backups with RANCID". Rhys Evans has written a Linux install and operation overview and it may be useful for Unix in general. And, Steve Smith has updated it for Fedora 15.

Anand Deveriya's Cisco Press publication Network Administrators Survival Guide includes some RANCID information. Sadly, this book is foolishly very Linux centric.

Rick Porter created a Solaris package and instructions for creating a Solaris package.

<<<Contents


Modules for other devices

There is a burgeoning collection of RANCID modules for unsupported devices located in the contrib FTP directory at ftp://ftp.shrubbery.net/pub/rancid/contrib/.

These are not supported nor do we maintain them ourselves because we do not have the devices to do the testing ourselves. If we receive enough positive feedback about a given module, we will consider importing into the distribution.

<<<Contents


Web Interfaces

There are no GUIs or web interfaces for configuring RANCiD, but there a few approaches to viewing diffs and the RCS repository. If you are using CVS, viewvc and cvsweb are the most common. If you are using SVN, viewvc works, and Scotty Hinote describes some other SVN tools nicely in the list-mail http://www.shrubbery.net/pipermail/rancid-discuss/2013-March/006752.html.

<<<Contents


Miscellaneous

Presentations about or involving RANCID:

Click for a copy of the RANCID license.

<<<Contents


Getting help

Please send problems/contributions/suggestions to rancid@shrubbery.net.

We have the standard mailing lists for those interested; rancid-announce and rancid-discuss. Subscribe by sending an email to rancid-<announce or discuss>-subscribe@shrubbery.net or by visiting the mailman page for each, at rancid-announce or rancid-discuss.

Archives exist for these lists post 20010722. They are available via:

Also look at the rancid FAQ.

<<< Contents


O/S-specific information

Expect has a problem on Solaris and Linux which causes hangs. The problem first appeared or was first reported under Linux with expect 5.40 (maybe anything after 5.25) and its mate Tcl 8.3.

The problem is best explained in this e-mail. To correct this, we worked out the following patches, which amount to making the socket (or file descriptor) non-blocking. OK, these are not so much patches, as they are hacks. The real problem is likely within Tcl, but I do not have the time to invest in tracking it down. The patches do fix the problem. [ Thanks to Dorian Kim and Mike Hyde for use of their Linux boxes. ]

These patches are NOT necessary for any of the BSDs.

The bug has been reported to the expect folks, but I've not seen any reply or progress on it. Just use the hacks, err patches.

For linux, use expect-hack1, which makes the file descriptors non-blocking. This is the original patch and as expect versions advance, this may apply with some fuzz.

For Solaris, expect-hack2, which uses poll(2) to test the file descriptors for waiting data. Making the file descriptors non-blocking caused streams problems for us under Solaris 2.9. This patch ought to work just fine for Linux as well.

For FreeBSD, it seems that this problem, or similar, may have recently appeared with the expect-devel port (5.44.x). What we've seen is that it does not hang but otherwise resembles this same bug. The non-devel expect port is still 5.43.x; using it seems to fix the problem.

One more bit on Solaris. If you have experienced rancid (or more precisely, telnet) hanging on a solaris 2.6 box; check to be sure you have the following two patches installed (see showrev -p). There may be more recent versions of these patches and they are likely included with 2.7 and 2.8:

Patch-ID# 105529-08
Keywords: security tcp rlogin TCP ACK FIN packet listen
Synopsis: SunOS 5.6: /kernel/drv/tcp patch

Patch-ID# 105786-11
Keywords: security ip tcp_priv_stream routing ip_enable_group_ifs ndd
Synopsis: SunOS 5.6: /kernel/drv/ip patch

NOTE: The version of Expect on the FTP site has been patched for this problem. The version of Tcl that is there is the mate to this Expect. They are there merely for convenience, since we get some folks not familiar with C or patching.

Some folks have tried to argue with me about these patches. The fact is that I just don't care to argue about it. You can use the patches or not, but do not ask for help and refuse to use them.

Some combination of FreeBSD and Expect have a problem. A few have reported their successful combinations, one of those was http://www.shrubbery.net/pipermail/rancid-discuss/2009-December/004458.html.

<<< Contents


Man pages on-line

User commands (1):

Libraries (3):

File formats (5):

<<< Contents


Version-specific information

none.

<<< Contents


Source respository

We have migrated to git from svn. We are also experimenting with pushing to github.com, now that github has relaxed the license. It is NOT the canonical source, may be slightly behind the canonical, and we make no guarantee that this will continue.

  • dev head: https://github.com/haussli/rancid
  • release tags: https://github.com/haussli/rancid/releases

<<< Contents


Other monitoring packages

<<< Contents

     Copyright© 1996-2016 Shrubbery Networks, All rights reserved. | Contact | Home