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:

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:

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:

• 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.

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:

• Mailman maintains an archive of the rancid lists, which is accessible via the web at rancid-announce and rancid-discuss.

• rancid-discuss-request@shrubbery.net (or rancid-announce-request) whose body reads "help". Instructions will be mailed to you. The web interface has far more utility.

• The list archives are searchable via htdig.

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:

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):

• a10login(1)
• agmrancid(1)
• alogin(1)
• anlogin(1)
• arancid(1)
• avologin(1)
• blogin(1)
• brancid(1)
• brlogin(1)
• cat5rancid(1)
• clogin(1)
• control_rancid(1)
• csblogin(1)
• cssrancid(1)
• dllogin(1)
• elogin(1)
• erancid(1)
• f10rancid(1)
• f5rancid(1)
• flogin(1)
• fnlogin(1)
• fnrancid(1)
• fxlogin(1)
• hlogin(1)
• hrancid(1)
• htlogin(1)
• htrancid(1)
• jerancid(1)
• jlogin(1)
• lg_intro(7)
• mrancid(1)
• mrvlogin(1)
• mtlogin(1)
• mtrancid(1)
• nlogin(1)
• noklogin(1)
• nrancid(1)
• nslogin(1)
• nsrancid(1)
• panlogin(1)
• par(1)
• plogin(1)
• rancid-cvs(1)
• rancid-run(1)
• rancid(1)
• rancid_intro(7)
• rblogin(1)
• rivlogin(1)
• rivrancid(1)
• rrancid(1)
• srancid(1)
• tlogin(1)
• trancid(1)
• ulogin(1)
• wlogin(1)
• xlogin(1)
• xilogin(1)
• xirancid(1)
• xrancid(1)
• zrancid(1)

Libraries (3):

• rancid(3)

File formats (5):

• cloginrc(5)
• lg.conf(5)
• rancid.conf(5)
• router.db(5)
• rancid.types.base(5)
• rancid.types.conf(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

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

<<< Contents