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


This documentation is accurate as of April 6, 2012. These steps have been performed on Ubuntu 10.04.4 Server systems and confirmed to work as described here.


It's generally a good idea to start with a healthy, fully functioning, up-to-date system. This means that some combination of sudo apt-get update, sudo apt-get upgrade, sudo apt-get dist-upgrade, and sudo apt-get autoremove should have been recently run. Please understand what the commands do before blindly running them as any system update has the potential to render a system inoperable.


To install RANCID, simply run:

sudo apt-get install rancid


The installation creates a new user and group named “rancid” with a home directory of /var/lib/rancid. Now, we must create at one least one group in RANCID to logically organize our devices. Groups can be based on any criteria you wish. So if you've got one physical location you could create "router", "firewall", and "switch" groups, or, in larger environments with multiple physical locations, group names such as "Los Angeles", "San Francisco", and "New York" may be a better choice. For this example we'll create groups based on the geographical location of devices. So let's create a group for each of these locations.

Even though it's a blank file, it's good practice to start by making a backup copy of the original rancid.conf file.

sudo cp /etc/rancid/rancid.conf /etc/rancid/rancid.conf.ORIGINAL

Open the file “/etc/rancid/rancid.conf” in your favorite text editor, add a line similar to the following, and save and exit.

LIST_OF_GROUPS="Los_Angeles, San_Francisco, and New_York"

E-Mail Notification

Next, we need to let RANCID know who should receive e-mail notifications for each group of devices. This is done by creating e-mail aliases in your MTA’s configuration files. By default on Ubuntu this is the “/etc/aliases” file.

For each group that you created, we need to add two aliases to the aliases file named “rancid-<groupname>” and “rancid-admin-<groupname>”. Open up the “/etc/aliases” file in a text editor and add lines similar to the following:

rancid-Los_Angeles:               <your_email@address.com>
rancid-admin-Los_Angeles:         <your_email@address.com>
rancid-San_Francisco:             <your_email@address.com>
rancid-admin-San_Francisco:       <your_email@address.com>
rancid-New_York:                  <your_email@address.com>
rancid-admin-New_York:            <your_email@address.com>

After saving your changes and exiting, you’ll need to let your MTA know about the changes. Since Ubuntu use sendmail by default, this can be accomplished by running...

sudo /usr/bin/newaliases

CVS Repository

Your device's configuration files will be stored in a Concurrent Versions System (CVS). This provides a way to track changes over time as well as provides you with a bit of disaster recovery. In order to prepare CVS we must create a folder structure based off of the RANCID groups that we created earlier. This command needs to be run as the "rancid" user that was created when the RANCID software was first installed.

sudo su -c /var/lib/rancid/bin/rancid-cvs -s /bin/bash -l rancid

Assuming that runs without any errors, you should see a number of new directories created under “/var/lib/rancid”, named according to the RANCID groups you defined earlier (e.g. “/var/lib/rancid/Los_Angeles”, “/var/lib/rancid/San_Francisco”, “/var/lib/rancid/New_York”, etc). Inside each will be a file named “router.db”:

[username@hostname ~]$ sudo find /var/lib/rancid -type f -name router.db

hosts File

Before going any further, it's a good idea to ensure that you can ping the devices that you want to download configuration files from by name.

Again, it's a good idea to make a backup copy of the original file that we're about to work on. In this case the /etc/hosts file.

sudo cp /etc/hosts /etc/hosts.ORIGINAL

The original /etc/hosts file should look something like this...       localhost       yourcomputershostname.exampledomain.com        yourcomputershostname

# The following lines are desirable for IPv6 capable hosts
::1     localhost ip6-localhost ip6-loopback
fe00::0 ip6-localnet
ff00::0 ip6-mcastprefix
ff02::1 ip6-allnodes
ff02::2 ip6-allrouters

Now that you've made a backup, edit the /etc/hosts file and just above the commented line so that they're grouped with the other IPv4 information, add something like the following...       router.location1.com          router       firewall.location2.com        firewall       switch.location3.com          switch

This is VERY important so take the time to ensure that not only can you ping the device by its IP address, you can also ping it by either it's Fully Qualified Domain Name (FQDN) or simply by its hostname.

router.db Files

Inside each of these “router.db” files is where we let RANCID know what devices exist in each location. A single line in each file is used to identify a single device. The format of the definitions is of the format “hostname:type:status”, where “hostname” is the fully-qualified domain name or IP address, “type” defines the type of device (e.g. “cisco”, “hp”, “foundry”, etc.) and “status” is either “up” or “down”. If “status” is set to “down”, RANCID will simply ignore the device.

Sample entries might look like this:



Once you have successfully added your devices to the appropriate “router.db” files, we need to let RANCID know how to access the devices (telnet, SSH, etc.) and what credentials to use to login. This is done via the “.cloginrc” file that exists in the rancid user’s home directory (“/var/lib/rancid/.cloginrc”, by default).

It is a good security practice to never connect to devices via telnet, so this guide will only cover the SSH method of connecting to a device. Other connection methods are also supported. The way the .cloginrc file is configured also depends on how the end device is configured to authenticate users. Users can be configured locally or a device can authenticate users agains an enterprise system such as LDAP or Active Directory. It gets complicated quickly so make sure that you take your time and read the documentation all the way through.

man cloginrc to see the details of all the available options and keywords available for use.

This guide will assume the simplest setup in which local usernames and passwords are defined on the end devices themselves.

Here's some example information my a .cloginrc file...

add method firewall.location2.com {ssh}
add cyphertype firewall.location2.com {des}
add user firewall.location2.com {rancid}
add password firewall.location2.com {<user_password>} {<enable_password}



The basic of tests utilizes the clogin application.

/usr/lib/rancid/bin/clogin -f /var/lib/rancid/.cloginrc firewall.location2.com

The clogin application will use the .clogin configuration file specified by the -f variable and will automatically login to the device named firewall.location2.com When it's all said and done you should end up in enable mode on the firewall device. If there are problems, clogin does an excellent job of providing pointed advice on what is wrong.


With RANCID now configured, it’s time to test it out! Let’s manually invoke “rancid-run” (as the “rancid” user) to see if it all blows up!

[username@hostname ~]$ sudo su -c /var/lib/rancid/bin/rancid-run -s /bin/bash -l rancid

This command may take a while to run, depending on how many devices you have configured. Be patient and, when it finishes, review the logfiles created in “/var/log/rancid”.

Assuming all goes well, you should receive e-mails from RANCID sent to the addresses that you defined in earlier in “/etc/aliases”.


Once everything is working, it’s time to automate the collection and archiving. The easiest way to do this is to simply create a cronjob under the rancid user that calls “rancid-run” for us on a periodic basis. We have RANCID run weekly, every Wednesday at 11:59AM

[username@hostname ~]$ sudo su -c "/usr/bin/crontab -e -u rancid"

Modify the contents of the file so that you end up with something like this.

# m h  dom mon dow   command
59 11 * * Wed /usr/bin/rancid-run

Extra Packages

When you install rancid, extra packages are installed which includes

  • cvs - Concurrent Versions System is a version control system, which allows you to keep old versions of files (usually source code), keep a log of who, when, and why changes occurred, etc., like RCS or SCCS.

  • expect - Expect is a tool for automating interactive applications according to a script.

  • tcl8.5 - Tcl is a powerful, easy to use, embeddable, cross-platform interpreted scripting language.

See Also

A see also section can be used to point users towards other trusted Ubuntu resources. For example, if a page exists in the official documentation on http://help.ubuntu.com, you can link to such a page. This section is optional.

  • <Link> - Explanation of link.

  • <Link> - Explanation of link.

  • <Link> - Explanation of link.

External Links

There are numerous web resources that I utilized in getting my own RANCID server up and running. Without them, none of what you have just read would have been possible.

RANCID (last edited 2017-12-06 16:05:28 by davidc3)