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) or Subversion to maintain history of changes.

RANCID does this by the very simple process summarized here:

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-skool 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 Cisco routers, Juniper routers, Catalyst switches, Foundry switches, 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 2.3.6. Read the CHANGES file for differences since the previous version.

Also, there are two alpha images; rancid-2.3.2a3.tar.gz and rancid-wcgallar.tar.gz. The latter is based on the former, but has fixes for use of SSH with HP Provurce switches.

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 supplied expect. See the O/S-specific section.

1. Sample diffs (output)
2. Getting started
   1. FreeBSD
   2. Linux
   3. OS X
3. Getting Help
4. Miscellaneous RANCID stuff
5. O/S-specific information
   1. Linux
   2. Solaris
6. Version-specific information
7. Other monitoring packages

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 it's 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, three very experienced chaps have written articles about installing RANCID on FreeBSD, Linux, and Mac OS X.

Chris Boyd wrote "Getting Rancid on FreeBSD" for Daemon News. Mark Duling wrote for OS X in an "OS X How-To" and Peter Harrison wrote for Linux and Linux Home Networks in "Network Device Backups with RANCID".

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

<<<Contents

Miscellaneous

Presentations about or involving RANCID:

• Our NANOG 29 presentation Tracking Device Changes with RANCID.
• What else can I do with rancid? Excellent question. See Joe Abley and Stephen Stuart's NANOG 26 Tutorial Managing IP Networks with Free Software.

<<<Contents

Getting help

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

We have the standard mailing lists for those interested; rancid-announce@shrubbery.net and rancid-discuss@shrubbery.net. Subscribe by sending an email whose body contains "subscribe rancid-<announce or discuss>" to majordomo@shrubbery.net.

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

• http://www.shrubbery.net/rancid/maillist/
• majordomo
  majordomo maintains an archive of the rancid list, which is accessible via email to majordomo. send an email to majordomo@shrubbery.net whose body reads "help". Instructions will be mailed to you; see the "index" and "get" commands.
• searchable via htdig.

<<< 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 it's mate Tcl 8.3.

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.

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:

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.

<<< Contents

Version-specific information

Patches for 2.2.2:

• Filter forensics.log changes on Cisco's recent IOS releases. [patch1]
• bin/hpfilter.c patch to pacify GCC 3. [patch2]
• Remove special handling of GSR fabric and MBUS module upgrade warnings. [patch3]

<<< Contents

Other monitoring packages

• COSI NMS - http://cosi-nms.sourceforge.net/

<<< Contents