Bob Drank the Water

July 9, 2009


Filed under: nerd — bruco @ 2:39 pm

RANCID is an application that allows you to track changes to network devices using a CVS tree.  It will email you any changes made at scheduled intervals.  You can read more about it here.

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:


(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:     Switch1    Switch2    Router1      Firewall1



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


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:


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.



  1. Hmm, in step 9, you probably didn’t really mean to say:

    rm –r /usr/local/var

    but maybe:

    rm –r /usr/local/var/rancid

    Comment by JRB — July 16, 2009 @ 4:30 am

    • Ah, you are right. Good eye. I’ve edited that step.

      On my system the /usr/local/var directory was only created when I installed RANCID – so removing the entire thing wouldn’t break anything. But who knows what other ports might use that directory structure?

      Comment by bruco — July 16, 2009 @ 9:26 am

  2. […] put together a useful tutorial for setting up RANCID on […]

    Pingback by RANCID on FreeBSD (howto) | FreeBSD - the unknown Giant — July 23, 2009 @ 1:51 am

  3. […] RANCID diegimas (tinklo įrenginių keitimosi stebėjimas) […]

    Pingback by Nuorodos į naujus straipsnius | — July 23, 2009 @ 2:48 pm

  4. Up and running in < 30 minutes. Thanks!

    Comment by fatboy — February 18, 2010 @ 3:30 pm

  5. Great tutorial thanks!

    Comment by Tim — March 9, 2010 @ 1:39 pm

  6. cannot works..

    how to edit /etc/hosts ?
    I received “WARNING: local host name (XXXX) is not qualified;” when type “newaliases”.

    Comment by ivan — November 9, 2010 @ 10:53 pm

    • I just edited /etc/hosts file, no wrror msg occur when type in newaliases command.

      My problem now is how to get the rancid send a mail to my maill address? Need some configuration or just type “/usr/local/rancid/bin/rancid-run”?


      Comment by ivan — November 9, 2010 @ 11:12 pm

      • Are you running sendmail? You’ll need to add lines to /etc/aliases like I did in the instructions, then run the newaliases command.

        Then, as the RANCID user, run /usr/local/rancid/bin/rancid-run and you should get some email.

        Comment by bruco — November 9, 2010 @ 11:30 pm

  7. Hi Bruco

    I’m new to linux, so I’m not sure whether I have configured it correctly.

    At first I’m running sendmail, but after few tries, I have follow other guide which is need to installed postfix. Now the server will running sendmail or postfix to send an email?

    I follow the steps below:
    i. Add lines below to /etc/aliases:
    rancid-admin-CiscoDevices: rancid-CiscoDevices

    ii. Type newaliases and comes with detail below: “/etc/aliases: 78 aliases, longest 22 bytes, 850 bytes total”.

    iii. As rancid user, type “/usr/local/rancid/bin/rancid-run”

    * After step iii, there is nth come out both server and my mail account.
    * Sometimes I ran “rancid-run” command, it will show me there are an email sent to “/var/spool/mail/rancid”.

    Anything I miss out?


    Comment by ivan — November 10, 2010 @ 1:52 am

  8. Add in a question:
    Do I need to configure sendmail, SNMP or mail server those thing to make the mail function works?


    Comment by ivan — November 10, 2010 @ 5:51 am

  9. some1 teach me how to configure sendmail on my new server to work with RANCID..

    Given 2 weeks but now already end of 3 weeks.. breached company SLA T.T

    Comment by ivan — November 12, 2010 @ 5:43 am

    • Configuring sendmail is a bit beyond the scope of this article. I can tell you that on a fresh FreeBSD build with networking set up and DNS servers defined, these instructions worked in my environment. Yours might differ, depending on how your FreeBSD box is built, whether SMTP traffic is allowed out, etc.

      This is probably the best place to start for sendmail:

      Comment by bruco — November 27, 2010 @ 1:15 pm

    • Configuring sendmail is a bit beyond the scope of this article. I can tell you that on a fresh FreeBSD build with networking set up and DNS servers defined, these instructions worked in my environment. Yours might differ, depending on how your FreeBSD box is built, whether SMTP traffic is allowed out, etc.

      This is probably the best place to start for sendmail:

      Comment by bruco — November 27, 2010 @ 1:15 pm

  10. How do we change the setup/configuration so that we get the email notifications about the changes made on the device. We also want numbers in terms of Total devices, no of devices which failed for backup and no. of devices for which backup happened successfully.

    We receive email notification stating that the back up is done. We managed to show the list of devices for which back up failed, but we dont get the pure numbers for which backup had failed of the total devices.

    Comment by Jigar Balani — November 19, 2010 @ 5:05 am

    • I don’t know that the functionality exists to give a count of devices, as opposed to just listing devices that were unreachable. Obviously there is one line per device in the email describing unreachable devices, maybe some kind of script could do a count on that? Not sure.

      I don’t really consider RANCID a backup solution for my Cisco configs, more of a change log. I suppose it might be possible to explore the CVS tree and pull the configuration of a device, but I’ve just scripted backups of a “show run” output and a tftp backup for my devices. Easy to reference, easy to restore.

      Comment by bruco — November 27, 2010 @ 1:21 pm

  11. Hi , it was looking like rancid change settings to make a single shipment notification email every 24 hours. I use RANCID for all my network device config backups. For non critical networks, or execs that wanted to know what was going on it the network .
    Greetings and thank you

    Comment by ggb — June 24, 2016 @ 5:57 am

RSS feed for comments on this post. TrackBack URI

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

Create a free website or blog at