I’m going to implement RANCID on a FreeBSD box at work to track changes to my Cisco network devices.  I’ve tested these directions on FreeBSD 6.3 and 7.2 and they should work on FreeBSD in general.

Oh, and credit where credit is due, I used Joe-Ma’s directions extensively as I learned about RANCID.

.

1.    First, let’s create a user for RANCID.  I’ll call the user… I dunno… RANCID.

# adduser

I added the RANCID user to the wheel group, so I can easily su to root later when I’m logged in as RANCID.

.

2.    Now let’s make sure we have the latest version of RANCID to install:

# portsnap fetch update

I like portsnap, other people user other methods.  To each his own.

.

3.    Install RANCID next:

# cd /usr/ports/net-mgmt/rancid/ && make install clean

I accepted all the defaults during the install.

.

4.    Now copy /usr/local/etc/rancid/rancid.conf.sample to /usr/local/etc/rancid/rancid.conf.

# cp /usr/local/etc/rancid/rancid.conf.sample /usr/local/etc/rancid/rancid.conf

.

5.    Edit rancid.conf.  I changed and uncommented the following line:

LIST_OF_GROUPS=”CiscoDevices”

(this is where you list one or more groups that your network devices will fall under.  I’m only using one group for all of them.)

.

6.    None of my Cisco devices are in DNS, so I’m going to just add some names to my /etc/hosts file:

192.168.1.5.1     Switch1
192.168.2.10.1    Switch2
192.168.2.15.1    Router1
256.43.26.35      Firewall1

Etc.

.

7.    We’ve been working as root, but now you’ll want to login as your RANCID user and create a .cloginrc file in the home directory:

$ touch /home/RANCID/.cloginrc

.

8.    The .cloginrc file contains usernames, passwords, and methods of logging into your network equipment.  You’ll need to edit the file to include this information. Here are some eamples from mine:

add password switch* {password} {enapassword}

(In this case, any device defined in my hosts file that starts with “switch” will use the first password to login to the device, and the second as the enable password.)

add method switch* telnet

(Any device that starts with “switch” will be logged into through telnet.)

add user firewall* admin

(Any device that starts with “firewall” will be logged into using “admin” as the username.)

add method firewall* ssh

(Any device that starts with “firewall” will be logged into through ssh.)

Note: I’ve found that when clogin uses the .cloginrc file to identify devices, it changes the name given to lowercase.  Therefore, all your device names in the .cloginrc file must be in lowercase.  For instance, in my hosts file I list Switch1 and Switch2, but when referring to them in .cloginrc I use switch* – WITHOUT a capital “s”.  Otherwise it won’t work.  I don’t know if there is a setting to change this, but in my case the easiest thing to do is just avoid capital letters in device names in .cloginrc.

.

9.    Keep in mind that the .cloginrc file has clear-text passwords in it, so it needs to be locked down.  In fact, the program won’t use it if it’s writeable by anybody other than the RANCID user.  So let’s set the permissions on it:

$ chmod 600 /home/RANCID/.cloginrc

The installation might have created a /usr/local/var/rancid directory.  But we don’t want it, we’re going to create it again ourselves.  So, if it exists, su to root and get rid of it.

$ su
Password:
# rm –r /usr/local/var/rancid

.

10.    We need to recreate the /rancid directory as the RANCID user, but I didn’t have permission to do so.  But remember, we made RANCID a member of the wheel group.  So, still as root, let’s modify the directory permissions:

# chmod 775 /usr/local/var

.

11.    Now we’ll exit back to our RANCID user shell and recreate that folder:

# exit
$ mkdir /usr/local/var/rancid

.

12.    Next we’ll create our initial directory structure with this command:

$ /usr/local/bin/rancid-run

.

13.    And now our data directories with this command:

$ /usr/local/bin/rancid-cvs

.

14.    Now the full structure should be in place in the /usr/local/var/rancid directory.  You should be able to cd to a directory named after the group (or groups) you named in Step 5.

$ cd /usr/local/var/rancid/CiscoDevices

.

15.    In here there’s a file called router.db that we need to edit.  This is where we’ll add the list of devices that we want RANCID to look at.  Based on earlier examples, here’s mine:

Switch1:cisco:up
Switch2:cisco:up
Router1:cisco:up
Firewall1:cisco:up

The first section refers to the device based on the names I put in my /etc/hosts file.  The second section specifies the type of device – in my case, they are all Cisco.  The third section simply says the device is up and should be scanned.  Any device I add here I want to be scanned, so they will all say “up”.

.

16.    Before we run anything at this point, you’ll probably want the emails generated to actually go somewhere.  Let’s su back to root and add some aliases.  This all depends on your mail setup, but in my case I want the emails from RANCID to go to an external email address.  So I added the following lines to /etc/aliases:

rancid-CiscoDevices: bruco@myemail.com
rancid-admin-CiscoDevices: bruco@myemail.com

Replace “CiscoDevices” in both those lines with whatever group name you defined in Step 5.  If you did multiple groups, you’ll need two lines for each group.

.

17.    This step depends on what mail server you are running.  By default FreeBSD runs sendmail.  I haven’t changed that, so I run sendmail, and now I need to regenerate my aliases for it.  Still as root:

# newaliases

.

18.    Now let’s exit back to our RANCID shell and run it again.  Don’t run it as root!  It might cause permission issues and will just be a headache.  Only run it as the RANCID user you created.

# exit
$ /usr/local/bin/rancid-run

If everything works, you should receive emails detailing the devices you’ve specified in router.db.

.

19.    Lastly, we probably want to run this automatically every so often.  So let’s schedule it with cron.  Once again, we’ll do it as the RANCID user, not root!

$ crontab -e
 45    17    *    *    *    /usr/local/bin/rancid-run

I’m running the job at 5:45 each day, because I have a fairly controlled environment (I’m the only person making changes to the Cisco devices).  However, it could be run more frequently if necessary.  Many people probably run it hourly.

.

Now we’re done!  At whatever interval we’ve set, RANCID will log into all the devices you’ve defined and check for differences since the last check.  If it finds them, it will email you the differences.

Here’s an example of an email from RANCID:

.

Index: configs/switch1
===================================================================
retrieving revision 1.3
diff -u -4 -r1.3 switch1
@@ -135,9 +135,8 @@
!
interface FastEthernet0/17
!
interface FastEthernet0/18
-  power inline never
spanning-tree portfast trunk
!
interface FastEthernet0/19
!

.

In this case I changed port 0/18 to allow Power over Ethernet on it.  See the – character next to “power inline never”?  That means that that particular line was removed from the configuration since the last time it was checked.  If I had added a line it would appear with a + character next to it.

.

Things to keep in mind:

Make sure all the device names in .cloginrc are in lowercase.

Don’t run /usr/local/bin/rancid-run as root – only run it as the RANCID user.

I ran into one issue where RANCID was hanging on one device – a router, specifically.  It turns out the router security was set up incorrectly and didn’t require an ena password.  RANCID didn’t know what to do, so it just hung on that device.  I changed the router configuration (since I do want an ena password to be required!) and now RANCID can login and pull the configuration properly.