Rancid - The Easy Tutorial

Rancid Tutorial
Last Change : Dec 07 2010 english flag

Tool
Install
Ergonomy
Forum

Details What is Rancid ?
Screenshots
Prerequisites
Tutorial Rancid
Other

⚠️⚠️⚠️
Please check our website about
attractions in Western Switzerland !! (Please use english translation).

⚠️⚠️⚠️
Merci de consulter notre site sur les
activités à faire en Suisse romande !!

The first thing to do is to create a new user called rancid because you should avoid running any applications with the root rights for security reasons.

#adduser rancid --home /home/rancid
This will create the rancid user and at the same time a rancid directory. The rancid user will own this directory.

Compiling the software

Once we've obtained the Rancid software from the shrubbery website, access the directory where it was downloaded and uncompress it.

#tar xvfz rancid-2.3.1.tar.gz
We need to install the tools required to compile and install a software.

#apt-get install build-essential
Now, we can compile and install Rancid. To do so, we need to access the new directory

#cd /home/user/Desktop/rancid-2.3.1
#./configure --prefix=/home/rancid
#checkinstall
This will install Rancid in /home/rancid.
If the checkinstall command is not available on your system or if you want more information about it, read the checkinstall page.

Now, we can start to set the Rancid tool.
We configure the /home/rancid/etc/rancid.conf file to create groups of devices. At least one group needs to be configured.

Adding the line below will create the melting_pot group where all the device configurations will be stored:

LIST_OF_GROUPS="melting_pot"
It can be very helpful to create several groups if you have a lot of devices and want to separate them by let's say geographical location.

LIST_OF_GROUPS="Dallas Boston Washington Other"
The group names must be separated with a space.

We need to configure a file called ".cloginrc" containing the passwords necessary to the access to the network devices. To create this file, we need to rename cloginrc.sample to .cloginrc.

#cp /home/rancid/share/rancid/cloginrc.sample /home/rancid/.cloginrc
Then we edit the new .cloginrc file where one can find syntax examples based on the type of device (Cisco, Juniper, etc ...) and connection (telnet, ssh, ...)
In our example, we will use telnet to access a Cisco switch with 10.156.1.1 as its IP address.
Open /home/rancid/.cloginrc

add password 10.156.1.1 {user_password} {enable_password}
Add a # at the beginning of each line except for the one you would like to use to access your device.
Be VERY careful with the .cloginrc file permissions because the passwords set are not encrypted. So the only way to protect them is to restrict the access rights to the file.
In order to do so, we change the access rights to 600, meaning the owner of the file will have read and write rights and all other players will be denied access to it. Next, the ownership of the /home/rancid directory including its files and directories must be transferred to the rancid user.

#chmod 600 /home/rancid/.cloginrc
#chown -R rancid:rancid /home/rancid

Creating a CVS architecture:
Login as rancid:

#su rancid
rancid@linux#/home/rancid/bin/rancid-cvs
add devices to the groups:
/home/rancid/var/rancid/"group_name"/router.db
The syntaxe is the following:
"ip_address or FQDN":"device_type":"status"

10.156.1.1:cisco:up
10.156.1.28:cisco:up
Check the remote access credentials configured in the /home/rancid/.cloginrc file:

rancid@linux:~/bin$ /home/rancid/bin/clogin 10.156.1.1

10.156.1.1
spawn telnet 10.156.1.1
Trying 10.156.1.1...
Connected to 10.156.1.1.
Escape character is '^]'.

User Access Verification

Password:
Router>enable
Password:
Router#

launch Rancid:

rancid@linux#/home/rancid/bin/rancid-run
You can check the logs in the /home/rancid/var/rancid/logs/ directory

We now just need to install the platform to see the device configurations via a web browser.

CvsWeb

We need to add a line in the /etc/cvsweb.conf file with the root user to create the new Rancid CVS repository. Look for the line beginning with "@CVSrepositories" and add the following bold line:

@CVSrepositories = (
#'local' => ['Local Repository', '/var/lib/cvs'],
'My_Config' => ['My Config', '/home/rancid/var/CVS'],
#'freeebsd' => ['FreeBSD', '/var/ncvs'],
#'openbsd' => ['OpenBSD', '/var/ncvs'],
#'netbsd' => ['NetBSD', '/var/ncvs'],
#'ruby' => ['Ruby', '/var/anoncvs/ruby'],
);
If the directory containing the cvsweb icons and css files is not in /var/www, you have to add a symbolic link :

#ln -s /usr/share/cvsweb /var/www/cvsweb
We can test it using a web browser such as Explorer or Firefox:
http://127.0.0.1/cgi-bin/cvsweb

Optionnaly, you can configure Rancid to send you a mail when a config has been changed after running the rancid-run script.

The first thing to do is to install Postfix with:

#apt-get install postfix
Then you will have to configure Postfix to send mails to your company SMTP gateway. This machine will send mails either outside the company to the internet or inside it to mail servers such as IBM Lotus Notes mail server.
For this, we need to set the Postfix configuration file which is /etc/postfix/main.cf .
Add the following settings:

relayhost = FQDN_or_IP_addresse_of_your_smtp_gateway
For example: relayhost = armageddon.dallas.us.qwertzy.com
Then restart Postfix:

#/etc/init.d/postfix restart
Now we can test if we can send a mail successfully, from the local machine:

#telnet localhost 25
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
220 localhost ESMTP Postfix (Ubuntu)
ehlo mail
250-localhost
250-PIPELINING
250-SIZE 10240000
250-VRFY
250-ETRN
250-STARTTLS
250 8BITMIME
mail from: <test@test.com>
250 Ok
rcpt to: <your_email@yourcompany.com>
250 Ok
data
354 End data with .
Subject: This is a test !
Wake up please!
.
250 Ok: queued as BD8261C01D4
quit
Connection closed by foreign host.
Then you should reveive your email.
If you have a problem check the /var/log/mail.log file. To see the last few lines in real time:

#tail -f /var/log/mail.log
The Rancid tool is set to send mails to two recipients per group

rancid-"group_name"
rancid-admin-"group_name"
The first recipient will receive a report after a configuration change, the second one when there is error messages.
For reminder, the group(s) are configured in the /home/rancid/etc/rancid.conf file. See above for more details.
For example, if you have a group called melting_pot, the mails will be sent to rancid-melting_pot and rancid-admin-melting_pot

The last thing to do is to create aliases for your recipients. Open the /etc/aliases file:

rancid-melting_pot
your_email@yourcompany.com rancid-admin-melting_pot
your_email@yourcompany.com

We used here our example group melting_pot.

Then, to initialize the alias database:

#newaliases

We need to create a cron job to run rancid-run frequently

crontab -e -u rancid

# run ranid-run script every day at 00:30
30 00 * * * /home/rancid/bin/rancid-run
The crontab command will update the /var/spool/cron/crontabs/rancid file.

Located on the debian-administration website, the useful "find" command that can be added to the crontab to remove old logs. The command below will remove standard files modified 30 days ago or more in the /home/rancid/var/logs/ directory :

# removed the old logs the first day of every month at 00:15
15 00 1 * * find /home/rancid/var/logs -type f -mtime +30 -exec rm {} \;
To get further explanations about crontab, have at look a the Wikipedia crontab page.