Install Rancid and ViewVC on Centos 7

Share on:

In this post I want to walk though the steps to install Rancid on CentOS 7 minimal. Rancid is a great tool to help monitor a device configuration for any changes. It also keeps track of them by using CVS (Concurrent Version System) for backups, so you can go back and compare versions or revert to a previous configuration. Rancid supports multiple hardware from Cisco, HP, Dell, Juniper and more. This is all open-source so you can create custom scripts or add commands to really make this a personal repository that fits your company.  During this install guide several things are required when we install Rancid, I have tired to make this as simple as possible but its not just a type and watch it install. You have to customize some of the scripts to make Rancid work like it should. Read it though and follow along.

So I'm already assuming that you have CentOS 7 minimal installed, with connection to the internet, and have just the root account with a password. You can pick up the latest CentOS at http://www.centos.org/ Login as the root account and let's update this thing and accept any updates before we do anything else.

1yum update

We now need to install all the prerequisites needed for Rancid and some other tools we'll need for troubleshooting (if needed)

1yum install nano wget ftp telnet mariadb-server mariadb perl tcl expect gcc cvs rcs httpd autoconf php-common php-gd php-pear php-pecl-memcache php-mysql php-xml mod_ssl MySQL-python

Since we installed Apache we will want to change the firewall rules on our system to allow HTTP and (HTTPS if we want it) Allow HTTP:

1firewall-cmd --permanent --zone=public --add-service=http

Allow HTTPS:

1firewall-cmd --permanent --zone=public --add-service=https

Reload the Firewall to save changes

1firewall-cmd --reload

Enable the Apache service to start on bootup and let's start it up for the first time.

1systemctl enable httpd.service systemctl start httpd.service

After you enable Apache you should see a sample webpage from Apache when you browse to your server's IP address with a browser. We now need to add a group for the rancid user.

1groupadd netadm

Next we will create a user called rancid and put this user under the group we just created which is netadm. We will also put in the home directory for this rancid user.

1useradd -g netadm -c "Networking Backups" -d /home/rancid rancid

Let's be a little organized and create a directory to put all of our installation files. Once created let's change directories to that tar folder we just created.

1mkdir /home/rancid/tar

Move to the tar folder

1cd /home/rancid/tar/

We will download the latest version of Rancid which at the time of this writing is 3.1 (3-1-16) UPDATE: Current version is 3.4.1 I updated the download paths below, :)

1wget ftp://ftp.shrubbery.net/pub/rancid/rancid-3.4.1.tar.gz

Extract the tar ball we just downloaded:

1tar -zxvf rancid-3.4.1.tar.gz

Move into the rancid-3.1 folder:

1cd rancid-3.4.1

Run/type in the following followed by enter. This get's Rancid ready for install.

1./configure --prefix=/usr/local/rancid

After all of the output clears run the install.

1make install

Now let's copy and modify some permissions

1cp cloginrc.sample /home/rancid/.cloginrc
2chmod 0640 /home/rancid/.cloginrc
3chown -R rancid:netadm /home/rancid/.cloginrc
4chown -R rancid:netadm /usr/local/rancid/
5chmod 775 /usr/local/rancid/

We have to edit the rancid configuration file and put our devices in groups. Find "list of rancid groups" and uncomment it. Type in the groups you would like, for example (Routers Switches)

1nano /usr/local/rancid/etc/rancid.conf
2...
3# list of rancid groups
4LIST_OF_GROUPS="Routers Switches"
5# more groups...
6#LIST_OF_GROUPS="$LIST_OF_GROUPS noc billybobisp"
7#
8...

Switch to the Rancid user account

1su -rancid

Run the following, this creates a CVS Repository with the groups you just entered in the List of Groups.

 1/usr/local/rancid/bin/rancid-cvs
 2 
 3No conflicts created by this import
 4 
 5cvs checkout: Updating Routers
 6Directory /usr/local/rancid/var/CVS/Routers/configs added to the repository
 7cvs commit: Examining configs
 8cvs add: scheduling file `router.db' for addition
 9cvs add: use 'cvs commit' to add this file permanently
10RCS file: /usr/local/rancid/var/CVS/Routers/router.db,v
11done
12Checking in router.db;
13/usr/local/rancid/var/CVS/Routers/router.db,v  --  router.db
14initial revision: 1.1
15done
16 
17No conflicts created by this import
18 
19cvs checkout: Updating Switches
20Directory /usr/local/rancid/var/CVS/Switches/configs added to the repository
21cvs commit: Examining configs
22cvs add: scheduling file `router.db' for addition
23cvs add: use 'cvs commit' to add this file permanently
24RCS file: /usr/local/rancid/var/CVS/Switches/router.db,v
25done
26Checking in router.db;
27/usr/local/rancid/var/CVS/Switches/router.db,v  --  router.db
28initial revision: 1.1
29done
30[rancid@rancid ~]$

After the command runs logout of Rancid user and go back to root. Move back to TAR folder.

1cd /home/rancid/tar

Next we will want to download ViewVC and as of this writing the latest the version is 1.1.23. (3-1-16) UPDATE: Current Version of ViewVC is 1.1.24, I updated the paths below, :)

1wget http://viewvc.tigris.org/files/documents/3330/49471/viewvc-1.1.24.tar.gz

Extract the tarball

1tar -zxvf viewvc-1.1.24.tar.gz

Move to the ViewVC folder and run the installer, accept the defaults.

1cd viewvc-1.1.24 ./viewvc-install

We now need to modify the ViewVC configuration file, basically telling ViewVC where the CVS repo is.

1nano /usr/local/viewvc-1.1.24/viewvc.conf

Find the following and edit as shown below:

 1...
 2## Example:
 3## cvs_roots = cvsroot: /opt/cvs/repos1,
 4##             anotherroot: /usr/local/cvs/repos2
 5##
 6#cvs_roots = cvs:
 7 
 8## svn_roots: Specifies each of the Subversion roots (repositories) on
 9## your system and assigns names to them. Each root should be given by
10...
11## Example:
12## root_parents = /opt/svn: svn,
13##                /opt/cvs: cvs
14##
15root_parents = /usr/local/rancid/var/CVS : cvs
16 
17## default_root: This is the name of the default root.  Valid names
18...
19## Example:
20## rcs_dir = /usr/bin/
21##
22rcs_dir = /usr/local/bin
23 
24## cvsnt: Location of cvsnt program.  ViewVC can use CVSNT (www.cvsnt.org)
25...
26## use_rcsparse: Use the rcsparse Python module to retrieve CVS
27## repository information instead of invoking rcs utilities [EXPERIMENTAL]
28##
29use_rcsparse = 1
30...

We need to copy some files and change permissions for ViewVC.

1cp /usr/local/viewvc-1.1.24/bin/cgi/*.cgi /var/www/cgi-bin
2chmod +x /var/www/cgi-bin/*.cgi
3chown apache:apache /var/www/cgi-bin/*.cgi

For this example we will use HTTP for ViewVC, although you could use HTTPS just have to modify the Apache (HTTPD file)

1nano /etc/httpd/conf/httpd.conf

I put the following at the bottom of the HTTPD file

 1# Custom Rancid Config
 2<VirtualHost *:80>
 3DocumentRoot /var/www
 4ScriptAlias /cgi-bin/ "/var/www/cgi-bin"
 5ScriptAlias /viewvc /var/www/cgi-bin/viewvc.cgi
 6ScriptAlias /query /var/www/cgi-bin/query.cgi
 7<Directory "/var/www/cgi-bin">
 8AllowOverride None
 9Options None
10Order allow,deny
11Allow from all
12</Directory>
13</VirtualHost>

We are almost done, we now need to turn on Mariadb which ViewVC uses, and start up the secure installation. (Accept all defaults and type in a root password for MariaDB.

1systemctl enable mariadb
2systemctl start mariadb
3sudo mysql_secure_installation

Go back into MariaDB and create a ViewVC user and use the password you just created.

1mysql -u root -p

Enter the following: (Replace YourPassowrdHere with something else, I would put a random password..if it was me)

1CREATE USER 'VIEWVC'@'localhost' IDENTIFIED BY 'YourPasswordHere';
2GRANT ALL PRIVILEGES ON *.* TO 'VIEWVC'@'localhost' WITH GRANT OPTION;
3FLUSH PRIVILEGES;
4quit

Make the ViewVC Database with the username and password you just created. (Accept the defaults)

1/usr/local/viewvc-1.1.24/bin/make-database
2MySQL Hostname (leave blank for default):
3MySQL Port (leave blank for default):
4MySQL User: VIEWVC
5MySQL Password: YourPasswordHere
6ViewVC Database Name [default: ViewVC]:
7 
8Database created successfully.  Don't forget to configure the
9[cvsdb] section of your viewvc.conf file.

Go back to MariaDB (MySQL) with the root password

1mysql -u root -p

Create a Read-Only account for ViewVC on the MySQL database. (Replace YourROPassowrdHere with something else)

1CREATE USER 'VIEWVCRO'@'localhost' IDENTIFIED BY 'YourROPasswordHere';
2GRANT SELECT ON ViewVC.* TO 'VIEWVCRO'@'localhost' WITH GRANT OPTION;
3FLUSH PRIVILEGES;
4quit

We now need to configure the ViewVC configuration file with the user names and passwords to that we created in MySQL.

1nano /usr/local/viewvc-1.1.24/viewvc.conf

Find cvsdb and change it to something like this:

 1##---------------------------------------------------------------------------
 2[cvsdb]
 3 
 4## enabled: Enable database integration feature.
 5##
 6enabled = 1
 7 
 8## host: Database hostname.  Leave unset to use a local Unix socket
 9## connection.
10##
11host = localhost
12 
13## post: Database listening port.
14##
15port = 3306
16 
17## database_name: ViewVC database name.
18##
19database_name = ViewVC
20 
21## user: Username of user with read/write privileges to the database
22## specified by the 'database_name' configuration option.
23##
24user = VIEWVC
25 
26## passwd: Password of user with read/write privileges to the database
27## specified by the 'database_name' configuration option.
28##
29passwd = YourPasswordHere
30 
31## readonly_user: Username of user with read privileges to the database
32## specified by the 'database_name' configuration option.
33##
34readonly_user = VIEWVCRO
35 
36## readonly_passwd: Password of user with read privileges to the database
37## specified by the 'database_name' configuration option.
38##
39readonly_passwd = YourROPasswordHere

Run the following command to build the Database.

1/usr/local/viewvc-1.1.24/bin/cvsdbadmin rebuild /usr/local/rancid/var/CVS/CVSROOT/

Reboot the server once online you should be able view the Repository at http://rancid-server-ip/viewvc Screenshot of ViewVC using Rancid

If you see the groups that we created we looking good so far. To finish this installation off we need to setup Rancid to send emails. Usually you have to add the Rancid to the allowed senders list on your email infrastructure. Rancid uses aliases to send emails we need to edit the aliases file.

1nano /etc/aliases

Depending on your infrastructure you might have different teams of people for different equipment that rancid is monitoring. Or you are running one-man-shop either way you can specify. In this example I'm using only one email address and created a new aliases called Rancid all of this is at the bottom of the aliases file.

1# Custom Rancid Configuration (Put an Email Here)
2rancid:         emailaddress@goeshere.com
3 
4# Custom Rancid Configuration
5rancid-admin-Routers: rancid
6rancid-Routers: rancid
7rancid-admin-Switches: rancid
8rancid-Switches: rancid

Depending on what you created in your List of Groups in the rancid configuration file you might have more or less. (In this example we just created Routers and Switches) We must specify these in the aliases file otherwise Rancid wont send emails for these groups. Once we are done editing you want to let our Rancid box know about the new aliases we just created. Type in the following command to update.

1newaliases

In this example postfix is already installed so we just need to edit the postfix configuration file.

1nano /etc/postfix/main.cf

Find and uncomment "relayhost" and type either the domain name (if you have MX records) the FQDN or IP address of your email system.

1relayhost =  mycompanydomain.com
2relayhost = email.mycompanydomain.com
3#relayhost = [mailserver.isp.tld]
4#relayhost = uucphost
5#relayhost = [an.ip.add.ress]

Start up posfix and enable it on boot

1systemctl start postfix
2systemctl enable postfix

Finished! We have just installed Rancid along with made some helpful tweaks like getting an upfront web page to view the configurations instead of CLI as well as setting up Rancid to email us if anything changes or if there are issues with connecting to any equipment. I'll put the brakes here and in the next post we will go over how to customize rancid to log into devices and grab configurations. I hope this install guide is helpful and let me know if you have any questions. Enjoy New Year! :) If you can't wait for me then you can check Shrubbery at http://www.shrubbery.net/rancid/ Read the README file once you download Rancid. You can also check threads from Rancid Discussions at www.gossamer-threads.com/lists/rancid/


Static Comments:

Brad S -

This was a great how to and saved me a lot of time! Thank you


night-fury -

hey Ryan, thanks for getting back on this. I do have similar logs:

 1[root@host-192-168-10-161 log]# tail -n 9 maillog
 2Jan 22 14:18:54 localhost postfix/postfix-script[1690]: starting the Postfix mail system
 3Jan 22 14:18:54 localhost postfix/master[1716]: daemon started — version 2.10.1, configuration /etc/postfix
 4Jan 23 10:33:17 localhost postfix/postfix-script[1787]: starting the Postfix mail system
 5Jan 23 10:33:17 localhost postfix/master[1811]: daemon started — version 2.10.1, configuration /etc/postfix
 6Jan 23 17:33:17 localhost postfix/pickup[21220]: DEC68243416E: uid=0 from=
 7Jan 23 17:33:17 localhost postfix/cleanup[22244]: DEC68243416E: message-id=20160123120317.DEC68243416E@host-192-168-10-161.localdomain
 8Jan 23 17:33:17 localhost postfix/qmgr[1821]: DEC68243416E: from=root@host-192-168-10-161.localdomain, size=47328, nrcpt=1 (queue active)
 9Jan 23 17:33:18 localhost postfix/smtp[22246]: DEC68243416E: to=my.email@my.domain.com, relay=10.20.30.40[10.20.30.40]:25, delay=0.95, delays=0.06/0.14/0.01/0.74, dsn=2.6.0, status=sent (250 2.6.0 20160123120317.DEC68243416E@host-192-168-10-161.localdomain [InternalId=53596896886795, Hostname=MAIL.SERVER.FQDN] Queued mail for delivery)
10Jan 23 17:33:18 localhost postfix/qmgr[1821]: DEC68243416E: removed

that means my mail server is messing with the emails. any pointer on what is to be changes in mail system? My mail logs, however, do not show anywhere that the mail is being sent to rancid-Switches@rancid.example.com etc. You think its a problem? -thanks night-fury


Ryan -

No Problem :)


erheqrheqhq -

Question, does it work for you without the Expect patch? You have no hangs like mentioned in http://www.shrubbery.net/rancid/EXPECTBUG ?


Ben -

First off thanks so much for the detail you put into these instructions. I am hoping though, you might be able to help with an error I'm getting. I went through your list without incident until the first reboot and attempting to browse to rancid-ip/viewvc which returns a traceback error.

 1Python Traceback
 2
 3Traceback (most recent call last):
 4File "/usr/local/viewvc-1.1.23/lib/viewvc.py", line 4848, in main
 5request.run_viewvc()
 6File "/usr/local/viewvc-1.1.23/lib/viewvc.py", line 402, in run_viewvc
 7self.view_func(self)
 8File "/usr/local/viewvc-1.1.23/lib/viewvc.py", line 2202, in view_roots
 9allroots = list_roots(request)
10File "/usr/local/viewvc-1.1.23/lib/viewvc.py", line 4698, in list_roots
11cfg.utilities, cfg.options.use_rcsparse)
12File "/usr/local/viewvc-1.1.23/lib/vclib/ccvs/init.py", line 56, in CVSRepository
13rootpath = canonicalize_rootpath(rootpath)
14File "/usr/local/viewvc-1.1.23/lib/vclib/ccvs/init.py", line 17, in canonicalize_rootpath
15assert os.path.isabs(rootpath)
16AssertionError

I've tried googling and found only one forum poster with an identical error.. he says that he resolved his by modifying 'rcs_dir = /usr/local/bin' to 'rcs_dir = /usr/bin' Which I did after LS'ing and finding out that /usr/local/bin was empty. However after another reboot the error persists. Any ideas would be awesome.. this is my second attempt at a successful config and I'm getting frustrated. Thanks!


Ben -

Thanks Ryan.. Actually what I wound up doing was deleting the vhd and starting over from scratch with your page. I actually have it all working save one thing.. Rancid actually creating the config files. My boss is pushing DR and I won;t have a whole lot of time left in the near future to work on this so thats why I decided to start all over. But yeah I can run clogin x.x.x.x and end up with a responsive ssh prompt to that switch. But rancid-run generates nothing at all, even an empty log file.


mlf -

It just worked with RHEL 6.5. After many attempts with other guides this one was just amazing. Thanks Ryan.


Adam -

This is my error below.

   1root@hmsgrancid viewvc-1.1.23]# /usr/local/viewvc-1.1.23/bin/cvsdbadmin rebuild /usr/local/rancid/var/CVS/CVSROOT/
   2Using repository root `/usr/local/rancid/var/CVS’
   3Traceback (most recent call last):
   4File “/usr/local/viewvc-1.1.23/bin/cvsdbadmin”, line 175, in
   5db = cvsdb.ConnectDatabase(cfg)
   6File “/usr/local/viewvc-1.1.23/lib/cvsdb.py”, line 904, in ConnectDatabase
   7db.Connect()
   8File “/usr/local/viewvc-1.1.23/lib/cvsdb.py”, line 59, in Connect
   9table_list = self.GetTableList()
  10File “/usr/local/viewvc-1.1.23/lib/cvsdb.py”, line 177, in GetTableList
  11cursor.execute(sql)
  12File “/usr/lib64/python2.7/site-packages/MySQLdb/cursors.py”, line 174, in execute
  13self.errorhandler(self, exc, value)
  14File “/usr/lib64/python2.7/site-packages/MySQLdb/connections.py”, line 36, in defaulterrorhandler
  15raise errorclass, errorvalue
  16_mysql_exceptions.OperationalError: (1046, ‘No database selected’)
  17
  18This is the viewvc.config file
  19
  20##—————————————————————————
  21##
  22
  23Configuration file for ViewVC
  24
  25##
  26
  27Information on ViewVC is located at the following web site:
  28
  29http://viewvc.org/
  30
  31##
  32##—————————————————————————
  33
  34THE FORMAT OF THIS CONFIGURATION FILE
  35
  36##
  37
  38This file is delineated by sections, specified in [brackets]. Within
  39
  40each section, are a number of configuration settings. These settings
  41
  42take the form of: name = value. Values may be continued on the
  43
  44following line by indenting the continued line.
  45
  46##
  47
  48WARNING: Indentation always means continuation. Name=value lines
  49
  50should always start in column zero.
  51
  52##
  53
  54Comments should always start in column zero, and are identified
  55
  56with “#”. By default each of the configuration items is
  57
  58commented out, with the default value of the option shown.
  59
  60You’ll need to remove the ‘#’ that precedes configuration
  61
  62options whose values you wish to modify.
  63
  64##
  65
  66Certain configuration settings may have multiple values. These should
  67
  68be separated by a comma. The settings where this is allowed are noted
  69
  70below. Any other setting that requires special syntax is noted at that
  71
  72setting.
  73
  74##
  75
  76SOME TERMINOLOGY USED HEREIN
  77
  78##
  79
  80“root” – This is a CVS or Subversion repository. For Subversion, the
  81
  82meaning is pretty clear, as the virtual, versioned directory tree
  83
  84stored inside a Subversion repository looks nothing like the actual
  85
  86tree visible with shell utilities that holds the repository. For
  87
  88CVS, this is more confusing, because CVS’s repository layout mimics
  89
  90(actually, defines) the layout of the stuff housed in the repository.
  91
  92But a CVS repository can be identified by the presence of a CVSROOT
  93
  94subdirectory in its root directory.
  95
  96##
  97
  98“module” – A module is a top-level subdirectory of a root, usually
  99
 100associated with the concept of a single “project” among many housed
 101
 102within a single repository.
 103
 104##
 105##
 106
 107BASIC VIEWVC CONFIGURATION HINTS
 108
 109##
 110
 111While ViewVC has quite a few configuration options, you generally
 112
 113only need to change a small subset of them to get your ViewVC
 114
 115installation working properly. Here are some options that we
 116
 117recommend you pay attention to. Of course, don’t try to change the
 118
 119options here — do so in the relevant section of the configuration
 120
 121file below.
 122
 123For correct operation, you will probably need to change the following
 124
 125configuration variables:
 126
 127cvs_roots (for CVS)
 128
 129svn_roots (for Subversion)
 130
 131root_parents (for CVS or Subversion)
 132
 133default_root
 134
 135root_as_url_component
 136
 137rcs_dir
 138
 139mime_types_files
 140
 141the many options in the [utilities] section
 142
 143It is usually desirable to change the following variables:
 144
 145address
 146
 147forbidden
 148
 149To optimize delivery of ViewVC static files:
 150
 151docroot
 152
 153To customize the display of ViewVC for your site:
 154
 155template_dir
 156
 157the [templates] override section
 158
 159##
 160
 161##—————————————————————————
 162[general]
 163
 164cvs_roots: Specifies each of the CVS roots on your system and
 165
 166assigns names to them. Each root should be given by a “name: path”
 167
 168value (where the path is an absolute filesystem path). Multiple roots
 169
 170should be separated by commas and can be placed on separate lines.
 171
 172##
 173
 174Example:
 175
 176cvs_roots = cvsroot: /opt/cvs/repos1,
 177
 178anotherroot: /usr/local/cvs/repos2
 179
 180##
 181#cvs_roots = cvs:
 182
 183svn_roots: Specifies each of the Subversion roots (repositories) on
 184
 185your system and assigns names to them. Each root should be given by
 186
 187a “name: path” value (where the path is an absolute filesystem path).
 188
 189Multiple roots should be separated by commas and can be placed on
 190
 191separate lines.
 192
 193##
 194
 195NOTE: ViewVC offers experimental support for displaying remote
 196
 197Subversion repositories. Simply use the repository’s URL instead
 198
 199of a local filesystem path when defining the root.
 200
 201##
 202
 203Example:
 204
 205svn_roots = svnrepos: /opt/svn/,
 206
 207anotherrepos: /usr/local/svn/repos2
 208
 209##
 210#svn_roots =
 211
 212root_parents: Specifies a list of directories under which any
 213
 214number of repositories may reside. You can specify multiple root
 215
 216parents separated by commas or new lines, each of which is of the
 217
 218form “path: type” (where the type is either “cvs” or “svn”, and
 219
 220the path is an absolute filesystem path).
 221
 222##
 223
 224Rather than force you to add a new entry to ‘cvs_roots’ or
 225
 226‘svn_roots’ each time you create a new repository, ViewVC rewards
 227
 228you for organizing all your repositories under a few parent
 229
 230directories by allowing you to simply tell it about those parent
 231
 232directories. ViewVC will then notice each repository of the
 233
 234specified type in that directory as a root whose name is the
 235
 236subdirectory in which that repository lives.
 237
 238##
 239
 240For example, if you have three Subversion repositories located at
 241
 242/opt/svn/projects, /opt/svn/websites, and /opt/svn/devstuff, you
 243
 244could list them individually in svn_roots like so:
 245
 246##
 247
 248svn_roots = projects: /opt/svn/projects,
 249
 250websites: /opt/svn/websites,
 251
 252devstuff: /opt/svn/devstuff
 253
 254##
 255
 256or you could instead use the root_parents configuration option:
 257
 258##
 259
 260root_parents = /opt/svn: svn
 261
 262##
 263
 264The benefit of this latter approach is that, as you add new
 265
 266repositories to your /opt/svn directory, they automatically become
 267
 268available for display in ViewVC without additional configuration.
 269
 270##
 271
 272WARNING: the root names derived for repositories configured via the
 273
 274root_parents option can, of course, clash with names you have
 275
 276defined in your cvs_roots or svn_roots configuration items. If
 277
 278this occurs, you can either rename the offending repository on
 279
 280disk, or grant new names to the clashing item in cvs_roots or
 281
 282svn_roots. Each parent path is processed sequentially, so the
 283
 284names of repositories under later parent paths may override earlier
 285
 286ones.
 287
 288##
 289
 290Example:
 291
 292root_parents = /opt/svn: svn,
 293
 294/opt/cvs: cvs
 295
 296##
 297#root_parents = /usr/local/rancid/var/CVS : cvs
 298
 299default_root: This is the name of the default root. Valid names
 300
 301include those explicitly listed in the cvs_roots and svn_roots
 302
 303configuration options, as well as those implicitly indicated by
 304
 305virtue of being the basenames of repositories found in the
 306
 307root_parents option locations.
 308
 309##
 310
 311NOTE: This setting is ignored when root_as_url_component is enabled.
 312
 313##
 314
 315Example:
 316
 317default_root = cvsroot
 318
 319##
 320#default_root =
 321
 322mime_types_files: This is a list of pathnames to a set of MIME type
 323
 324mapping files to help ViewVC guess the correct MIME type of a
 325
 326versioned file. The pathnames listed here are specified in order of
 327
 328authoritativeness either as absolute paths or relative to this
 329
 330configuration file.
 331
 332##
 333
 334As a convenience, ViewVC provides a MIME type mapping file
 335
 336(mimetypes.conf) which is, by default, the preferred provider of
 337
 338MIME type mapping answers, but which is also empty. If you find
 339
 340that ViewVC is unable to accurately guess MIME types based on the
 341
 342extensions of some of your versioned files, you can add records of
 343
 344your preferred mappings to the provided mimetypes.conf file (or to
 345
 346your system’s mapping files, if you wish).
 347
 348##
 349
 350You might, for example, wish to have ViewVC also consult the mapping
 351
 352files provided by your operating system and Apache.
 353
 354##
 355
 356Example:
 357
 358mime_types_files = mimetypes.conf,
 359
 360/etc/mime.types,
 361
 362/usr/local/apache2/conf/mime.types
 363
 364##
 365#mime_types_files = mimetypes.conf
 366
 367address: The address of the local repository maintainer. (This
 368
 369option is provided only as a convenience for ViewVC installations
 370
 371which are using the default template set, where the value of this
 372
 373option will be displayed in the footer of every ViewVC page.)
 374
 375##
 376
 377Example:
 378
 379address = admin@server.com
 380
 381##
 382#address =
 383
 384kv_files: Provides a mechanism for custom key/value pairs to be
 385
 386available to templates. These are stored in key/value (KV) files.
 387
 388##
 389
 390The paths of the KV files are listed here, specified either as
 391
 392absolute paths or relative to this configuration file. The files
 393
 394use the same format as this configuration file, containing one or
 395
 396more user-defined sections, and user-defined options in those
 397
 398sections. ViewVC makes these options available to template authors
 399
 400as:
 401
 402##
 403
 404kv.SECTION.OPTION
 405
 406##
 407
 408Note that an option name can be dotted. For example:
 409
 410##
 411
 412[my_images]
 413
 414logos.small = /images/small-logo.png
 415
 416logos.big = /images/big-logo.png
 417
 418##
 419
 420Templates can use these with a directive like: [kv.my_images.logos.small]
 421
 422##
 423
 424Note that section names which are common to multiple KV files will
 425
 426be merged. If two files have a [my_images] section, then the
 427
 428options in those two like-named sections will be merged together.
 429
 430If two files have the same option name in a section, then one will
 431
 432overwrite the other (and which one “wins” is unspecified).
 433
 434##
 435
 436To further categorize the KV files, and how the values are provided to
 437
 438the templates, a KV file name may be annotated with an additional level
 439
 440of dotted naming. For example:
 441
 442##
 443
 444kv_files = [asf]kv/images.conf
 445
 446##
 447
 448Assuming the same section as above, the template would refer to an image
 449
 450using [kv.asf.my_images.logos.small]
 451
 452##
 453
 454Lastly, it is possible to use %lang% in the filenames to specify a
 455
 456substitution of the selected language-tag.
 457
 458##
 459
 460Example:
 461
 462kv_files = kv/file1.conf, kv/file2.conf, [i18n]kv/%lang%_data.conf
 463
 464##
 465#kv_files =
 466
 467This option is a comma-separated list of language-tag values
 468
 469available to ViewVC. The first language-tag listed is the default
 470
 471language, and will be used if an Accept-Language header is not
 472
 473present in the request, or none of the user’s requested languages
 474
 475are available. If there are ties on the selection of a language,
 476
 477then the first to appear in the list is chosen.
 478
 479##
 480
 481Example:
 482
 483languages = en-us, en-gb, de
 484
 485##
 486#languages = en-us
 487
 488##—————————————————————————
 489[utilities]
 490
 491ViewVC uses (sometimes optionally) various third-party programs to do some
 492
 493of the heavy lifting. Generally, it will attempt to execute those utility
 494
 495programs in such a way that if they are found in ViewVC’s executable
 496
 497search path ($PATH, %PATH%, etc.) all is well. But sometimes these tools
 498
 499aren’t installed in the executable search path, so here’s where you can
 500
 501tell ViewVC where to find them.
 502
 503##
 504
 505NOTE: Options with a “_dir” suffix are for configuring the
 506
 507directories in which certain programs live. Note that this might
 508
 509not be the same directory into which the program’s installer dumped
 510
 511the whole program package — we want the deepest directory in which
 512
 513the executable program itself resides (“C:\rcstools\bin\win32”
 514
 515rather than just “C:\rcstools”, for example). The values of options
 516
 517whose names lack the “_dir” suffix should point to the actual
 518
 519program itself (such as “C:\Program Files\cvsnt\cvs.exe”).
 520
 521rcs_dir: Directory in which the RCS utilities are installed, used
 522
 523for viewing CVS repositories.
 524
 525##
 526
 527Example:
 528
 529rcs_dir = /usr/bin/
 530
 531##
 532#rcs_dir = /usr/local/bin
 533
 534cvsnt: Location of cvsnt program. ViewVC can use CVSNT (www.cvsnt.org)
 535
 536instead of the RCS utilities to retrieve information from CVS
 537
 538repositories. To enable use of CVSNT, set the “cvsnt” value to the
 539
 540path of the CVSNT executable. (If CVSNT is on the standard path, you
 541
 542can also set it to the name of the CVSNT executable). By default
 543
 544“cvsnt” is set to “cvs” on Windows and is not set on other platforms.
 545
 546##
 547
 548Examples:
 549
 550cvsnt = K:\Program Files\cvsnt\cvs.exe
 551
 552cvsnt = /usr/bin/cvs
 553
 554cvsnt = cvs
 555
 556##
 557#cvsnt =
 558
 559svn: Location of the Subversion command-line client, used for
 560
 561viewing Subversion repositories.
 562
 563##
 564
 565Example:
 566
 567svn = /usr/bin/svn
 568
 569##
 570#svn =
 571
 572diff: Location of the GNU diff program, used for showing file
 573
 574version differences.
 575
 576##
 577
 578Example:
 579
 580diff = /usr/bin/diff
 581
 582##
 583#diff =
 584
 585cvsgraph: Location of the CvsGraph program, a graphical CVS version
 586
 587graph generator (see options.use_cvsgraph).
 588
 589##
 590
 591Example:
 592
 593cvsgraph = /usr/local/bin/cvsgraph
 594
 595##
 596#cvsgraph =
 597
 598##—————————————————————————
 599[options]
 600
 601root_as_url_component: Interpret the first path component in the URL
 602
 603after the script location as the root to use. This is an
 604
 605alternative to using the “root=” query key. If ViewVC is configured
 606
 607with multiple repositories, this results in more natural looking
 608
 609ViewVC URLs.
 610
 611##
 612
 613NOTE: Enabling this option will break backwards compatibility with
 614
 615any old ViewCVS URL which doesn’t have an explicit “root” parameter.
 616
 617##
 618#root_as_url_component = 1
 619
 620checkout_magic: Use checkout links with magic /checkout/ prefixes so
 621
 622checked out HTML pages can have working links to other repository files
 623
 624##
 625
 626NOTE: This option is DEPRECATED and should not be used in new ViewVC
 627
 628installations. Setting “default_file_view = co” achieves the same effect
 629
 630##
 631#checkout_magic = 0
 632
 633allowed_views: List the ViewVC views which are enabled. Views not
 634
 635in this comma-delited list will not be served (or, will return an
 636
 637error on attempted access).
 638
 639##
 640
 641Valid items for this list include: “annotate”, “co”, “diff”, “markup”,
 642
 643“roots”, “tar”.
 644
 645##
 646
 647———-+———————————————————
 648
 649VIEW | DESCRIPTION
 650
 651———-+———————————————————
 652
 653annotate | The ‘annotate’ view shows the contents of a single
 654
 655| revision of a versioned file in exactly the same way as
 656
 657| the markup view, but with additional line-by-line
 658
 659| change attribution (the revision number, author, etc.
 660
 661| the most recent edit to that line of text as of the
 662
 663| displayed version).
 664
 665———-+———————————————————
 666
 667co | The ‘co’ (aka “checkout” or “download”) view isn’t
 668
 669| really a branded view at all, but allows for direct
 670
 671| downloading of the contents of a single revision of a
 672
 673| versioned file.
 674
 675———-+———————————————————
 676
 677diff | The ‘diff’ view displays line-based differences between
 678
 679| two revisions of a versioned file in a variety of
 680
 681| different user-selectable formats.
 682
 683———-+———————————————————
 684
 685markup | The ‘markup’ view shows the contents of a single
 686
 687| revision of a versioned file, with syntax highlighting
 688
 689| where possible and enabled. It can also optionally
 690
 691| show change log information for that revision of the
 692
 693| file.
 694
 695———-+———————————————————
 696
 697roots | The ‘roots’ view is a simple listing of the various
 698
 699| repositories which ViewVC has been configured to serve
 700
 701| to users.
 702
 703———-+———————————————————
 704
 705tar | The ‘tar’ view isn’t a branded view, but generates
 706
 707| a GNU Tar archive file containing a single versioned
 708
 709| directory and its contents (recursively).
 710
 711———-+———————————————————
 712
 713##
 714#allowed_views = annotate, diff, markup, roots
 715
 716Comma-delimited list of MIME content types (with support for fnmatch-
 717
 718style glob characters) which are considered not-human-readable and for
 719
 720which ViewVC will neither generate links to, nor support the direct
 721
 722display of, non-checkout views which carry the file’s content (the
 723
 724‘markup’, ‘annotate’, ‘diff’, and ‘patch’ views).
 725
 726##
 727
 728NOTE: Handling of this option is given priority over ViewVC’s
 729
 730longstanding support for showing web-friendly file formats — even
 731
 732binary ones such as “image/jpeg” and “image/gif” — in the ‘markup’
 733
 734view. Thus, if you add “image/*” to this list, ‘markup’-view
 735
 736display of JPEG, GIF, and PNG images will be disabled.
 737
 738##
 739
 740Example:
 741
 742binary_mime_types = application/octet-stream, image/*, application/pdf,
 743
 744application/vnd*, application/msword, audio/*
 745
 746#
 747#binary_mime_types =
 748
 749authorizer: The name of the ViewVC authorizer plugin to use when
 750
 751authorizing access to repository contents. This value must be the
 752
 753name of a Python module addressable as vcauth.MODULENAME (most
 754
 755easily accomplished by placing it in ViewVC’s lib/vcauth/ directory)
 756
 757and which implements a ViewVCAuthorizer class (as a subclass of
 758
 759vcauth.GenericViewVCAuthorizer). You can provide custom parameters
 760
 761to the authorizer module by defining configuration sections named
 762
 763authz-MODULENAME and adding the parameter keys and values there.
 764
 765##
 766
 767ViewVC provides the following modules:
 768
 769svnauthz – based on Subversion authz files
 770
 771forbidden – simple path glob matches against top-level root directories
 772
 773forbiddenre – root and path matches against regular expressions
 774
 775##
 776
 777NOTE: Only one authorizer may be in use for a given ViewVC request.
 778
 779It doesn’t matter if you configure the parameters of multiple
 780
 781authorizer plugins — only the authorizer whose name is configured
 782
 783here (or effectively configured here via per-vhost or per-root
 784
 785configuration) will be activated.
 786
 787##
 788#authorizer =
 789
 790hide_cvsroot: Don’t show the CVSROOT directory
 791
 7921 Hide CVSROOT directory
 793
 7940 Show CVSROOT directory
 795
 796##
 797
 798NOTE: Someday this option may be removed in favor of letting
 799
 800individual authorizer plugin hide the CVSROOT.
 801
 802##
 803#hide_cvsroot = 1
 804
 805mangle_email_addresses: Mangle email addresses in marked-up output.
 806
 807There are various levels of mangling available:
 808
 8090 – No mangling; markup un-mangled email addresses as hyperlinks
 810
 8111 – Obfuscation (using entity encoding); no hyperlinking
 812
 8132 – Data-dropping address truncation; no hyperlinking
 814
 815##
 816
 817NOTE: this will not effect the display of versioned file contents, only
 818
 819addresses that appear in version control metadata (e.g. log messages).
 820
 821##
 822#mangle_email_addresses = 0
 823
 824custom_log_formatting: Specifies mappings of regular expressions to
 825
 826substitution format strings used to URL-ize strings found in
 827
 828revision log messages. Multiple mappings (specified as
 829
 830REGEXP:FORMATSTRING) may be defined, separated by commas.
 831
 832##
 833
 834NOTE: Due to a limitation of the configuration format, commas may
 835
 836not be used in the regular expression portion of each mapping.
 837
 838Commas “in the raw” may not be used in the format string portion,
 839
 840either, but you can probably use the URI-encoded form of the comma
 841
 842(“%2C”) instead with no ill side-effects. If you must specify a
 843
 844colon character in either the regular expression or the format
 845
 846string, escape it with a preceding backslash (“:”).
 847
 848##
 849
 850Example:
 851
 852custom_log_formatting =
 853
 854artf[0-9]+ : http://example.com/tracker?id=\0,
 855
 856issue ([0-9]+) : http://example.com/bug?id=\1&opts=full%2csortby=id
 857
 858##
 859#custom_log_formatting =
 860
 861default_file_view: “log”, “co”, or “markup”
 862
 863Controls whether the default view for file URLs is a checkout view or
 864
 865a log view. “log” is the default for backwards compatibility with old
 866
 867ViewCVS URLs, but “co” has the advantage that it allows ViewVC to serve
 868
 869static HTML pages directly from a repository with working links
 870
 871to other repository files
 872
 873##
 874
 875NOTE: Changing this option may break compatibility with existing
 876
 877bookmarked URLs.
 878
 879##
 880
 881ALSO NOTE: If you choose one of the “co” or “markup” views, be sure
 882
 883to enable it (via the allowed_views option)
 884
 885##
 886#default_file_view = log
 887
 888http_expiration_time: Expiration time (in seconds) for cacheable
 889
 890pages served by ViewVC. Note that in most cases, a cache aware
 891
 892client will only revalidate the page after it expires (using the
 893
 894If-Modified-Since and/or If-None-Match headers) and that browsers
 895
 896will also revalidate the page when the reload button is pressed.
 897
 898Set to 0 to disable the transmission of these caching headers.
 899
 900##
 901#http_expiration_time = 600
 902
 903generate_etags: Generate Etag headers for relevant pages to assist
 904
 905in browser caching.
 906
 9071 Generate Etags
 908
 9090 Don’t generate Etags
 910
 911##
 912#generate_etags = 1
 913
 914svn_ignore_mimetype: Don’t consult the svn:mime-type property to
 915
 916determine how to display a file in the markup view. This is
 917
 918especially helpful when versioned images carry the default
 919
 920Subversion-calculated MIME type of “application/octet-stream” (which
 921
 922isn’t recognized as viewable type by browsers).
 923
 924##
 925#svn_ignore_mimetype = 0
 926
 927max_filesize_kbytes: Limit ViewVC’s processing of file contents in
 928
 929“markup” and “annotate” views to only those files which are smaller
 930
 931than this setting, expressed in kilobytes. Set to 0 to disable
 932
 933this safeguard.
 934
 935##
 936
 937NOTE: The “co” and “tar” views are unaffected by this setting.
 938
 939#max_filesize_kbytes = 512
 940
 941svn_config_dir: Path of the Subversion runtime configuration
 942
 943directory ViewVC should consult for various things, including cached
 944
 945remote authentication credentials. If unset, Subversion will use
 946
 947the default location(s) ($HOME/.subversion, etc.)
 948
 949##
 950#svn_config_dir =
 951
 952use_rcsparse: Use the rcsparse Python module to retrieve CVS
 953
 954repository information instead of invoking rcs utilities [EXPERIMENTAL]
 955
 956##
 957#use_rcsparse = 1
 958
 959sort_by: File sort order
 960
 961file Sort by filename
 962
 963rev Sort by revision number
 964
 965date Sort by commit date
 966
 967author Sort by author
 968
 969log Sort by log message
 970
 971##
 972#sort_by = file
 973
 974sort_group_dirs: Group directories when sorting
 975
 9761 Group directories together
 977
 9780 No grouping — sort directories as any other item would be sorted
 979
 980##
 981#sort_group_dirs = 1
 982
 983hide_attic: Hide or show the contents of the Attic subdirectory
 984
 9851 Hide dead files inside Attic subdir
 986
 9870 Show the files which are inside the Attic subdir
 988
 989##
 990#hide_attic = 1
 991
 992hide_errorful_entries: Hide or show errorful directory entries
 993
 994(perhaps due to not being readable, or some other rlog parsing
 995
 996error, etc.)
 997
 9981 Hide errorful entries from the directory display
 999
10000 Show errorful entries (with their errors) in the directory display
1001
1002##
1003#hide_errorful_entries = 0
1004
1005log_sort: Sort order for log messages
1006
1007date Sort revisions by date
1008
1009rev Sort revision by revision number
1010
1011none Use the version control system’s ordering
1012
1013##
1014#log_sort = date
1015
1016diff_format: Default diff format
1017
1018h Human readable
1019
1020u Unified diff
1021
1022c Context diff
1023
1024s Side by side
1025
1026l Long human readable (more context)
1027
1028f Full human readable (entire file)
1029
1030##
1031#diff_format = h
1032
1033hr_breakable: Diff view line breaks
1034
10351 lines break at spaces
1036
10370 no line breaking
1038
1039Or, use a positive integer > 1 to cut lines after that many characters
1040
1041##
1042#hr_breakable = 1
1043
1044hr_funout: Give out function names in human readable diffs.
1045
1046(Only works well for C source files, otherwise diff’s heuristic falls short.)
1047
1048(‘-p’ option to diff)
1049
1050##
1051#hr_funout = 1
1052
1053hr_ignore_white: Ignore whitespace (indendation and stuff) for human
1054
1055readable diffs.
1056
1057(‘-w’ option to diff)
1058
1059##
1060#hr_ignore_white = 0
1061
1062hr_ignore_keyword_subst: Ignore diffs which are caused by keyword
1063
1064substitution (such as “$Id – Stuff”).
1065
1066(‘-kk’ option to rcsdiff)
1067
1068##
1069#hr_ignore_keyword_subst = 1
1070
1071hr_intraline: Enable highlighting of intraline changes in human
1072
1073readable diffs. [Requires Python 2.4]
1074
1075##
1076#hr_intraline = 0
1077
1078allow_compress: Allow compression via gzip of output if the Browser
1079
1080accepts it (HTTP_ACCEPT_ENCODING contains “gzip”).
1081
1082##
1083
1084NOTE: this relies on Python’s gzip module, which has proven to be
1085
1086not-so-performant. Enabling this feature should reduce the overall
1087
1088transfer size of ViewVC’s responses to the client’s request, but
1089
1090will do so with a speed penalty.
1091
1092##
1093#allow_compress = 0
1094
1095template_dir: The directory which contains the EZT templates used by
1096
1097ViewVC to customize the display of the various output views. ViewVC
1098
1099looks in this directory for files with names that match the name of
1100
1101the view (“log”, “directory”, etc.) plus the “.ezt” extension. If
1102
1103specified as a relative path, it is relative to the directory where
1104
1105this config file resides; absolute paths may be used as well. If
1106
1107%lang% occurs in the pathname, then the selected language will be
1108
1109substituted.
1110
1111SEE ALSO: the [templates] configuration section, where you can
1112
1113override templates on a per-view basis.
1114
1115##
1116#template_dir = templates
1117
1118docroot: Web path to a directory that contains ViewVC static files
1119
1120(stylesheets, images, etc.) If set, static files will get
1121
1122downloaded directory from this location. If unset, static files
1123
1124will be served by the ViewVC script (at a likely performance
1125
1126penalty, and from the “docroot” subdirectory of the directory
1127
1128specified by the “template_dir” option).
1129
1130##
1131
1132NOTE: This option is evaluated outside the context of a particular
1133
1134root. Be careful when using per-root configuration to select an
1135
1136alternate template set as the default value for this option will
1137
1138still be based on the global default template set per ‘template_dir’
1139
1140above, not on ‘template_dir’ as overridden for a given root.
1141
1142##
1143#docroot =
1144
1145show_subdir_lastmod: Show last changelog message for CVS subdirectories
1146
1147##
1148
1149NOTE: The current implementation makes many assumptions and may show
1150
1151the incorrect file at some times. The main assumption is that the
1152
1153last modified file has the newest filedate. But some CVS operations
1154
1155touches the file without even when a new version is not checked in,
1156
1157and TAG based browsing essentially puts this out of order, unless
1158
1159the last checkin was on the same tag as you are viewing. Enable
1160
1161this if you like the feature, but don’t rely on correct results.
1162
1163##
1164
1165SECURITY WARNING: Enabling this will currently leak unauthorized
1166
1167path names.
1168
1169##
1170#show_subdir_lastmod = 0
1171
1172show_roots_lastmod: In the root listing view, show the most recent
1173
1174modifications made to the root. (Subversion roots only.)
1175
1176##
1177
1178NOTE: Enabling this feature will significantly reduce the
1179
1180performance of the root listing view.
1181
1182##
1183#show_roots_lastmod = 0
1184
1185show_logs: Show the most recent log entry in directory listings.
1186
1187##
1188#show_logs = 1
1189
1190show_log_in_markup: Show log when viewing file contents.
1191
1192##
1193#show_log_in_markup = 1
1194
1195cross_copies: Cross filesystem copies when traversing Subversion
1196
1197file revision histories.
1198
1199##
1200#cross_copies = 1
1201
1202use_localtime: Display dates as UTC or in local time zone.
1203
1204##
1205#use_localtime = 0
1206
1207iso8601_dates: Display timestamps using a standard ISO-8601 format.
1208
1209##
1210#iso8601_timestamps = 0
1211
1212short_log_len: The length (in characters) to which the most recent
1213
1214log entry should be truncated when shown in the directory view.
1215
1216##
1217#short_log_len = 80
1218
1219enable_syntax_coloration: Should we colorize known file content
1220
1221syntaxes?
1222
1223##
1224
1225NOTE: This feature requires the Pygments Python module
1226
1227(http://pygments.org) and works only when ViewVC can determine the
1228
1229MIME content type of the file whose contents it wishes to colorize.
1230
1231Use the ‘mime_types_files’ configuration option to specify MIME
1232
1233type mapping files useful for making that determination.
1234
1235##
1236#enable_syntax_coloration = 1
1237
1238tabsize: The number of spaces into which horizontal tab characters
1239
1240are converted when viewing file contents. Set to 0 to preserve
1241
1242tab characters.
1243
1244##
1245#tabsize = 8
1246
1247detect_encoding: Should we attempt to detect versioned file
1248
1249character encodings? [Requires ‘chardet’ module, and is currently
1250
1251used only for the ‘markup’ and ‘annotate’ views.]
1252
1253##
1254#detect_encoding = 0
1255
1256use_cvsgraph: Use CvsGraph to offer visual graphs of CVS revision history.
1257
1258##
1259#use_cvsgraph = 0
1260
1261cvsgraph_conf: Location of the customized cvsgraph configuration file.
1262
1263May be specified as an absolute path or as a path relative to this
1264
1265configuration file.
1266
1267##
1268#cvsgraph_conf = cvsgraph.conf
1269
1270use_re_search: Enable regular expression search of files in a directory.
1271
1272##
1273
1274WARNING: Enabling this option can consume HUGE amounts of server
1275
1276time. A “checkout” must be performed on each file in a directory,
1277
1278and the result needs to be searched for a match against the regular
1279
1280expression.
1281
1282##
1283
1284SECURITY WARNING: Since a user can enter the regular expression, it
1285
1286is possible for them to enter an expression with many alternatives
1287
1288and a lot of backtracking. Executing that search over thousands of
1289
1290lines over dozens of files can easily tie up a server for a long
1291
1292period of time. This option should only be used on sites with
1293
1294trusted users. It is highly inadvisable to use this on a public site.
1295
1296##
1297#use_re_search = 0
1298
1299dir_pagesize: Maximum number of directory entries on a given page.
1300
1301This allows ViewVC to present discrete pages to the users instead of
1302
1303the entire directory. Set to 0 to disable pagination.
1304
1305##
1306#dir_pagesize = 0
1307
1308log_pagesize: Maximum number of revision log entries on a given page.
1309
1310This allows ViewVC to present discrete pages to the users instead of
1311
1312the entire revision log. Set to 0 to disable pagination.
1313
1314##
1315#log_pagesize = 0
1316
1317log_pagesextra: Maximum number of extra pages (based on
1318
1319log_pagesize) of revision log data to fetch and present to the user
1320
1321as additional options for display. Revision log information
1322
1323“beyond” this window is still accessible, but must be navigated to
1324
1325in multiple steps.
1326
1327##
1328
1329Example:
1330
1331log_pagesize = 100
1332
1333log_pagesextra = 3
1334
1335##
1336
1337For a versioned file with 1000 revisions, the above settings would
1338
1339present to the user the first 100 of those 1000 revisions, with
1340
1341links to three additional pages (the 200-299th revisions, 300-399th
1342
1343revisions, and 400-499th revisions) plus a link to the 500th
1344
1345revision. Following these links slides the display “window”,
1346
1347showing the requested set of revisions plus links to three
1348
1349additional pages beyond those, and so on.
1350
1351##
1352#log_pagesextra = 3
1353
1354limit_changes: Maximum number of changed paths shown per commit in
1355
1356the Subversion revision view and in query results. This is not a
1357
1358hard limit (the UI provides options to show all changed paths), but
1359
1360it prevents ViewVC from generating enormous and hard to read pages
1361
1362by default when they happen to contain import or merge commits
1363
1364affecting hundreds or thousands of files. Set to 0 to disable the
1365
1366limit.
1367
1368##
1369#limit_changes = 100
1370
1371##—————————————————————————
1372[templates]
1373
1374You can override the templates used by various ViewVC views in this
1375
1376section. By default, ViewVC will look for templates in the
1377
1378directory specified by the “template_dir” configuration option (see
1379
1380the documentation for that option for details). But if you want to
1381
1382use a different template for a particular view, simply uncomment the
1383
1384appropriate option below and specify the currect location of the EZT
1385
1386template file you wish to use for that view.
1387
1388Templates are specified relative to the configured template
1389
1390directory (see the “template_dir” option), but absolute paths may
1391
1392also be used as well.
1393
1394##
1395
1396If %lang% occurs in the pathname, then the selected language will be
1397
1398substituted.
1399
1400##
1401
1402NOTE: the selected language is defined by the “languages” item in the
1403
1404[general] section, and based on the request’s Accept-Language
1405
1406header.
1407
1408##
1409
1410diff: Template used for the file differences view.
1411
1412##
1413#diff =
1414
1415directory: Template used for the directory listing view.
1416
1417##
1418#directory =
1419
1420error: Template used for the ViewVC error display view.
1421
1422##
1423#error =
1424
1425file: Template used for the file contents/annotation view.
1426
1427##
1428#file =
1429
1430graph: Template used for the revision graph view.
1431
1432##
1433#graph =
1434
1435log: Template used for the revision log view.
1436
1437##
1438#log =
1439
1440query: Template used for the non-integrated query interface.
1441
1442##
1443#query =
1444
1445query_form: Template used for the query form view.
1446
1447##
1448#query_form =
1449
1450query_results: Template used for the query results view.
1451
1452##
1453#query_results =
1454
1455revision: Template used for the revision/changeset view.
1456
1457##
1458#revision =
1459
1460roots: Template used for the root listing view.
1461
1462##
1463#roots =
1464
1465##—————————————————————————
1466[cvsdb]
1467
1468enabled: Enable database integration feature.
1469
1470##
1471#enabled = 1
1472
1473host: Database hostname. Leave unset to use a local Unix socket
1474
1475connection.
1476
1477##
1478#host = localhost
1479
1480post: Database listening port.
1481
1482##
1483#port = 3306
1484
1485database_name: ViewVC database name.
1486
1487##
1488#database_name = ViewVC
1489
1490user: Username of user with read/write privileges to the database
1491
1492specified by the ‘database_name’ configuration option.
1493
1494##
1495#user = VIEWVC
1496
1497passwd: Password of user with read/write privileges to the database
1498
1499specified by the ‘database_name’ configuration option.
1500
1501##
1502#passwd = gr33nback
1503
1504readonly_user: Username of user with read privileges to the database
1505
1506specified by the ‘database_name’ configuration option.
1507
1508##
1509#readonly_user = VIEWVCRO
1510
1511readonly_passwd: Password of user with read privileges to the database
1512
1513specified by the ‘database_name’ configuration option.
1514
1515##
1516#readonly_passwd = gr33nback
1517
1518row_limit: Maximum number of rows returned by a given normal query
1519
1520to the database.
1521
1522##
1523
1524NOTE: This limits the amount of data provided to ViewVC by the
1525
1526database. It is from this already-reduced data set that ViewVC
1527
1528builds the query response it presents to the user, which may or may
1529
1530not include still more limiting via the query form’s ‘limit’
1531
1532parameter. In other words, there is no value which the user can use
1533
1534in the query form’s ‘limit’ parameter which will cause more data to
1535
1536be returned by the database for ViewVC to process.
1537
1538##
1539#row_limit = 1000
1540
1541rss_row_limit: Maximum number of rows returned by a given query to
1542
1543the database made as part of an RSS feed request. (Keeping in mind
1544
1545that RSS readers tend to poll regularly for new data, you might want
1546
1547to keep this set to a conservative number.)
1548
1549##
1550
1551See also the `NOTE for the row_limit option, which applies here
1552
1553as well.
1554
1555##
1556#rss_row_limit = 100
1557
1558check_database_for_root: Check if the repository is found in the
1559
1560database before showing the query link and RSS feeds.
1561
1562WARNING: Enabling this check adds the cost of a database connection
1563
1564and query to most ViewVC requests. If all your roots are represented
1565
1566in the commits database, or if you dont care about the creation of
1567
1568RSS and query links that might lead ultimately to error pages for
1569
1570certain of your roots, or if you simply dont want to add this extra
1571
1572cost to your ViewVC requests, leave this disabled.
1573
1574##
1575#check_database_for_root = 0
1576
1577##—————————————————————————
1578[vhosts]
1579
1580Virtual hosts are individual logical servers accessible via
1581
1582different hostnames, but which are all really the same physical
1583
1584computer. For example, you might have your web server configured to
1585
1586accept incoming traffic for both http://www.yourdomain.com/ and
1587
1588http://viewvc.yourdomain.com/. Users pointing their web browsers at
1589
1590each of those two URLs might see entirely different content via one
1591
1592URL versus the other, but all that content actually lives on the
1593
1594same computer, is served up via the same web server, and so
1595
1596on. It just looks like its coming from multiple servers.
1597
1598##
1599
1600ViewVC allows you to customize its configuration options for
1601
1602individual virtual hosts. You might, for example, wish to expose
1603
1604all of your Subversion repositories at http://svn.yourdomain.com/viewvc/
1605
1606and all your CVS ones at http://cvs.yourdomain.com/viewvc/, with no
1607
1608cross-exposure. Using ViewVCs virtual host (vhost) configuration
1609
1610support, you can do this. Simply create two vhost configurations
1611
1612(one for each of your hostnames), then configure the cvs_roots
1613
1614option only for the vhost associated with cvs.yourdomain.com, and
1615
1616configure the svn_roots option only for the vhost associated with
1617
1618svn.yourdomain.com.
1619
1620##
1621
1622This section is a freeform configuration section, where you create
1623
1624both the option names and their values. The names of the options
1625
1626are then treated as canonical names of virtual hosts, and their
1627
1628values are defined to be comma-delimited lists of hostname globs
1629
1630against which incoming ViewVC requests will be matched to figure out
1631
1632which vhost they apply to.
1633
1634##
1635
1636After youve named and defined your vhosts, you may then create new
1637
1638configuration sections whose names are of the form
1639
1640vhost-VHOSTNAME/CONFIGSECTION. VHOSTNAME here is the canonical name
1641
1642of one of the virtual hosts you defined under the [vhosts] section.
1643
1644Inside those configuration sections, you override the standard
1645
1646ViewVC options typically found in the base configuration section
1647
1648named CONFIGSECTION (general, option, etc.)
1649
1650##
1651
1652NOTE: Per-vhost overrides may only be applied to the following
1653
1654sections:
1655
1656##
1657
1658general
1659
1660options
1661
1662utilities
1663
1664templates
1665
1666cvsdb
1667
1668authz-*
1669
1670##
1671
1672Here is an example:
1673
1674##
1675
1676[vhosts]
1677
1678libs = libs.yourdomain.*, .yourlibs.
1679
1680gui = guiproject.yourdomain.*
1681
1682##
1683
1684[vhost-libs/general]
1685
1686cvs_roots =
1687
1688svn_roots = svnroot: /var/svn/libs-repos
1689
1690default_root = svnroot
1691
1692##
1693
1694[vhost-libs/options]
1695
1696show_logs = 1
1697
1698##
1699
1700[vhost-gui/general]
1701
1702cvs_roots = cvsroot: /var/cvs/guiproject
1703
1704svn_roots =
1705
1706default_root = cvsroot
1707
1708##
1709
1710##—————————————————————————
1711
1712ViewVC recognizes per-root configuration overrides, too. To
1713
1714override the value of a configuration parameter only for a single
1715
1716root, create a configuration section whose names is of the form
1717
1718root-ROOTNAME/CONFIGSECTION. ROOTNAME here is the name of the root
1719
1720as defined explicitly in cvs_roots or svn_roots or implicitly as the
1721
1722basename of a root path in root_parents. Options found in this new
1723
1724configuration section override for this one root the corresponding
1725
1726options found in the base configuration section CONFIGSECTION
1727
1728(options, authz-*, etc.) as interpreted after per-vhost
1729
1730overrides (if any) have been applied.
1731
1732##
1733
1734NOTE: Per-root overrides may only be applied to the following
1735
1736sections:
1737
1738##
1739
1740options
1741
1742utilities
1743
1744authz-*
1745
1746##
1747
1748WARNING: Do not use per-root overrides if your ViewVC instance is
1749
1750served via the standalone.py server option! Doing so could cause
1751
1752ViewVC to be unable to function properly (or at all).
1753
1754##
1755
1756Here is an example showing how to enable Subversion authz-based
1757
1758authorization for only the single root named svnroot:
1759
1760[root-svnroot/options]
1761
1762authorizer = svnauthz
1763
1764##
1765
1766[root-svnroot/authz-svnauthz]
1767
1768authzfile = /path/to/authzfile
1769
1770##
1771
1772##—————————————————————————
1773[authz-forbidden]
1774
1775The forbidden authorizer forbids access to repository modules,
1776
1777defined to be top-level subdirectories in a repository.
1778
1779##
1780
1781NOTE: The options in this section apply only when the authorizer
1782
1783option (in the [options] section) is set to forbidden.
1784
1785forbidden: A comma-delimited list of patterns which match modules
1786
1787that ViewVC should hide from users.
1788
1789##
1790
1791You can use a simple list of modules, or something more complex:
1792
1793##
1794
1795*) The ! can be used before a module to explicitly state that it
1796
1797is NOT forbidden. Whenever this form is seen, then all modules will
1798
1799be forbidden unless one of the ! modules match.
1800
1801##
1802
1803) Shell-style glob expressions may be used. “” will match any
1804
1805sequence of zero or more characters, “?” will match any single
1806
1807character, [seq] will match any character in seq, and [!seq]
1808
1809will match any character not in seq.
1810
1811##
1812
1813*) Tests are performed in sequence. The first match will terminate the
1814
1815testing. This allows for more complex allow/deny patterns.
1816
1817##
1818
1819Tests are case-sensitive.
1820
1821##
1822
1823NOTE: Again, this is for the hiding of modules within repositories, not
1824
1825for the hiding of repositories (roots) themselves.
1826
1827##
1828
1829Some examples:
1830
1831##
1832
1833Disallow example but allow all others:
1834
1835forbidden = example
1836
1837##
1838
1839Disallow example1 and example2 but allow all others:
1840
1841forbidden = example1, example2
1842
1843##
1844
1845Allow only example1 and example2:
1846
1847forbidden = !example1, !example2
1848
1849##
1850
1851Forbid modules starting with x:
1852
1853forbidden = x*
1854
1855##
1856
1857Allow modules starting with x but no others:
1858
1859forbidden = !x*
1860
1861##
1862
1863Allow xml, forbid other modules starting with x, and allow the rest:
1864
1865forbidden = !xml, x*, !*
1866
1867##
1868#forbidden =
1869
1870##—————————————————————————
1871[authz-forbiddenre]
1872
1873The forbiddenre authorizer forbids access to repositories and
1874
1875repository paths by comparing a list of regular expressions
1876
1877(separated by commas) against paths consisting of the repository (or
1878
1879root) name plus the path of the versioned file or directory to be
1880
1881tested. For example, to see if the user is authorized to see the
1882
1883path /trunk/www/index.html in the repository whose root name is
1884
1885svnrepos, this authorizer will check the path
1886
1887svnrepos/trunk/www/index.html against the list of forbidden
1888
1889regular expressions. Directory paths will be terminated by a forward
1890
1891slash.
1892
1893##
1894
1895NOTE: The options in this section apply only when the authorizer
1896
1897option (in the [options] section) is set to forbiddenre.
1898
1899forbiddenre: A comma-delimited list of regular expressions which
1900
1901match paths that ViewVC should hide from users.
1902
1903##
1904
1905Like the forbidden authorizer
1906
1907##
1908
1909*) The ! can be used before a module to explicitly state that it
1910
1911is NOT forbidden. Whenever this form is seen, then all modules will
1912
1913be forbidden unless one of the ! modules match.
1914
1915##
1916
1917*) Tests are performed in sequence. The first match will terminate the
1918
1919testing. This allows for more complex allow/deny patterns.
1920
1921##
1922
1923Unlike the forbidden authorizer, you can can use this to hide roots, too.
1924
1925##
1926
1927Some examples:
1928
1929##
1930
1931Disallow files named PRIVATE, but allow all others:
1932
1933forbiddenre = /PRIVATE$
1934
1935##
1936
1937Disallow the hidden repository, allowing all others:
1938
1939forbiddenre = ^hidden(/|$)
1940
1941##
1942
1943Allow only the example1 and example2 roots and the paths inside them,
1944
1945disallowing all others (which can be done in multiple ways):
1946
1947forbiddenre = !^example1(/|$), !^example2(/|$)/
1948
1949forbiddenre = !^example12
1950
1951##
1952
1953Only allow visibility of HTML files and the directories that hold them:
1954
1955forbiddenre = !^([^/]+|.*(/|.html))$
1956
1957##
1958#forbiddenre =
1959
1960##—————————————————————————
1961[authz-svnauthz]
1962
1963The svnauthz authorizer uses a Subversion authz configuration file
1964
1965to determine access to repository paths.
1966
1967##
1968
1969NOTE: The options in this section apply only when the authorizer
1970
1971option (in the [options] section) is set to svnauthz.
1972
1973authzfile: Specifies the location of the authorization rules file
1974
1975(using an absolute path).
1976
1977##
1978#authzfile =
1979
1980root_relative_authzfile: Specifies the location of the
1981
1982authorization rules file using an path relative to the repository.
1983
1984##
1985
1986Example:
1987
1988root_relative_authzfile = conf/access
1989
1990##
1991#root_relative_authzfile =
1992
1993force_username_case: Like the AuthzForceUsernameCase httpd.conf
1994
1995directive, set this to upper or lower to force the normalization
1996
1997to upper- or lower-case, respectively, of incoming usernames prior
1998
1999to comparison against the authorization rules files. Leave the
2000
2001option unset to preserve the username case.
2002
2003##
2004#force_username_case =
2005
2006##—————————————————————————
2007[query]
2008
2009The configuration items in this section are used exclusively by the
2010
2011query script, a separate script from ViewVC itself that ships
2012
2013with ViewVC and allows for queries into the ViewVC commits
2014
2015database. If you arent using this separate script (which was made
2016
2017largely irrelevant by the introduction of an integrated query
2018
2019view in ViewVC itself, or arent using the ViewVC commits database
2020
2021functionality at all, you can ignore these configurations items
2022
2023altogether.
2024
2025viewvc_base_url: Base URL at which ViewVC may be accessed on this
2026
2027server. The default value for this option is determined at
2028
2029run-time by the various front-ends to the query script.
2030
2031##
2032
2033Examples:
2034
2035viewvc_base_url = /viewvc.py
2036
2037viewvc_base_url = /viewvc.wsgi
2038
2039viewvc_base_url = /cgi-bin/viewvc
2040
2041viewvc_base_url = viewvc
2042
2043##
2044
2045To disable cross-linking between the query script and ViewVC,
2046
2047uncomment this option and leave its value empty.
2048
2049##
2050#viewvc_base_url =
2051
2052##—————————————————————————

Dan -

This is a fantastic guide. One of the best I have read in a long time. Thank you.


night-fury -

Okay, will check what can be done at the exchange end. Thank you for all your help :)


Iqbal -

Hi Ryan :) Hope you are doing well. After running the last command I get the following error. Could you please help me ?

1root@rancid-test:~# /usr/local/viewvc-1.1.24/bin/cvsdbadmin rebuild /usr/local/rancid/var/CVS/CVSROOT/
2Traceback (most recent call last):
3File “/usr/local/viewvc-1.1.24/bin/cvsdbadmin”, line 44, in
4import cvsdb
5File “/usr/local/viewvc-1.1.24/lib/cvsdb.py”, line 21, in
6import dbi
7File “/usr/local/viewvc-1.1.24/lib/dbi.py”, line 18, in
8import MySQLdb
9ImportError: No module named MySQLdb

Iqbal -

Hi Ryan, thanks for the reply. I don't know what the reason is, but I was able to do it when I tried to do it again from the beginning :) It looks like this now : https://onedrive.live.com/redir?resid=1BBA8AF56E1CCA90!4580&authkey=!AN-zNMBZRJY-d9I&v=3&ithint=photo%2cPNG What I want now is to change the ViewVC logo to be replaced by my company logo. I know I have to change the html page corresponding to it. But I don't find that html page. Do you have any idea? Thanks a lot in advance :)


Ryan -

Glad it worked out!


bobby -

What are you using Maria-db for?


Kenan Gülle (@KenanGulle) -

[rancid@raancid root]$ bin/clogin 192.168.1.1 bash: bin/clogin: Permission denied view error help me :(


Ben -

I figured it out Ryan. The router.db files formatting needs semi colons instead of colons.


sunny -

Hi, Fantastic guide to install rancid and view VC. I am fairly new to linux and was able to set this up readin this guide. Well. now ihave certain devices belonging to cisco-sb type and trying to set that up i had to play a lot with the software and configs. I was able to set it up finally. Now i have quite a few revisions in ViewVC. Is there a way to clear all the revisions so that when i run 'rancid-run' next, the first revision i.e. 1.1 should have all devices config in it. I guess creating a new database should do it but want to get expert opinion. Please let me know. Any help would be much appreciated.


Ryan -

Hey Ben, Usually this is some type of permission issue with either apache or the rancid user. You may want to also post your problem at http://www.gossamer-threads.com/lists/rancid/ might get someone better than me :) Check the areas where you had to modify permissions like the cgi-bin folder (Apache should be the owner here)

1[root@rancid ~]# ls -l /var/www/cgi-bin/
2total 8
3-rwxr-xr-x. 1 apache apache 1782 Jan 1 05:55 query.cgi
4-rwxr-xr-x. 1 apache apache 1781 Jan 1 05:55 viewvc.cgi

Also what Python version are you running? In this example it was:

1[root@rancid ~]# python -V
2Python 2.7.5

Check to make sure you have RCS installed:

1[root@rancid ~]# yum install rcs
2Loaded plugins: fastestmirror
3Loading mirror speeds from cached hostfile
4* base: mirror.raystedman.net
5* extras: mirror.netdepot.com
6* updates: mirrors.kernel.org
7Package rcs-5.9.0-5.el7.x86_64 already installed and latest version
8Nothing to do

I would also try to run rancid manually and have it connect to a device to see if you can get diffs just in CLI. That would help because then its likely something wrong with just Apache/ViewVC. What I'll do is do a fresh install of Rancid on Centos 7 and see if I run into this problem, but I won't be able to really look at until next week sometime.

Good Luck and don't get too frustrated ;) Ryan


Ryan -

In this version I'm using Rancid 3.1 with Expect version 5.45. I have not experienced any of the hangs like mentioned above. The TCL version I'm using is 8.5.13. Maybe its fixed? Just in case if anyone wants to check: To check the Expect version run: expect -v To check TCL version go type tclsh followed by typing info patchlevel Thanks for bringing it up :)


Configuring Rancid « Cisco Skills -

[…] my last post I talked about installing Rancid on Centos 7 so be sure to check that out. In this post we now want to actually use Rancid so I’ll walk through […]


Ryan -

Hey Adam, I would check your viewvc.conf file and make sure you put the database you are connecting into the view.conf file in my example my database is ViewVC. The error message basically says there is no database selected when you run the rebuild script. Configure the ViewVC configuration file nano /usr/local/viewvc-1.1.23/viewvc.conf Look for database_name = Type in your database to connect ViewVC. Hope that Helps, Ryan


Wayne -

A nice guide for me but when i access to "Query on /configs" website and click "search", an error appears,can you help me solve?

 1An Exception Has Occurred
 2
 3Python Traceback
 4
 5Traceback (most recent call last):
 6File “/usr/local/viewvc-1.1.24/lib/viewvc.py”, line 4855, in main
 7request.run_viewvc()
 8File “/usr/local/viewvc-1.1.24/lib/viewvc.py”, line 408, in run_viewvc
 9self.view_func(self)
10File “/usr/local/viewvc-1.1.24/lib/viewvc.py”, line 4484, in view_query
11db = cvsdb.ConnectDatabaseReadOnly(cfg)
12File “/usr/local/viewvc-1.1.24/lib/cvsdb.py”, line 908, in ConnectDatabaseReadOnly
13return ConnectDatabase(cfg, 1)
14File “/usr/local/viewvc-1.1.24/lib/cvsdb.py”, line 904, in ConnectDatabase
15db.Connect()
16File “/usr/local/viewvc-1.1.24/lib/cvsdb.py”, line 56, in Connect
17self._host, self._port, self._user, self._passwd, self._database)
18File “/usr/local/viewvc-1.1.24/lib/dbi.py”, line 63, in connect
19return MySQLdb.connect(host=host, port=port, user=user, passwd=passwd, db=db)
20File “/usr/lib64/python2.7/site-packages/MySQLdb/init.py”, line 81, in Connect
21return Connection(*args, **kwargs)
22File “/usr/lib64/python2.7/site-packages/MySQLdb/connections.py”, line 187, in __init__
23super(Connection, self).__init__(*args, **kwargs2)
24TypeError: connect() argument 3 must be string, not int

Ryan -

No problem, glad you where able to get it working :)


Adam -

Hi Ryan, I checked everything in all the config files. In the end I deleted the VM are started again from scratch, sadly i got the end with the same error. Fancy building me a quick one and exporting it ti ovf/ova?


Abhinav Bahri -

Hi I am getting this error "OSError: [Errno 13] Permission denied: '/usr/local/rancid/var/CVS'" while running viewvc on browser.. directory permissions are, drwxrwxr-x. 4 rancid netadm 4096 Nov 6 09:02 CVS Any help will be appreciated. Thanks Abhinav


Ryan -

Hey Alex, Does your error match what I had above? Ryan


christopherbnash -

No the rebuild didn't work still the same error.


Ryan -

Hey Adam, Could you post your viewvc.conf file? Ryan


Ryan -

Hey Alex, Glad you got it working and thanks for posting back your solution.


Alex -

Hi Ryan, Thank you for your answer. The thing is that my CVS folder is already in 775 mode, that's why I don't understand this error. Do you have any idea ? Cheers, Alex


Ryan -

Hey Alex, What is your permissions on that directory "/usr/local/rancid/var/CVS"? This is likely the issue, I can reproduce the issue if "Others/All Users" don't have permission to read and or execute the CVS folder. Here is the error I get if CVS is not readable to All users does that match what you have?

 1An Exception Has Occurred
 2Python Traceback
 3
 4Traceback (most recent call last):
 5File "/usr/local/viewvc-1.1.23/lib/viewvc.py", line 4848, in main
 6request.run_viewvc()
 7File "/usr/local/viewvc-1.1.23/lib/viewvc.py", line 402, in run_viewvc
 8self.view_func(self)
 9File "/usr/local/viewvc-1.1.23/lib/viewvc.py", line 2201, in view_roots
10expand_root_parents(request.cfg)
11File "/usr/local/viewvc-1.1.23/lib/viewvc.py", line 4720, in expand_root_parents
12roots = vclib.ccvs.expand_root_parent(pp)
13File "/usr/local/viewvc-1.1.23/lib/vclib/ccvs/init.py", line 32, in expand_root_parent
14subpaths = os.listdir(parent_path)
15OSError: [Errno 13] Permission denied: '/usr/local/rancid/var/CVS'

Here is the output of my machine, notice the CVS folder permissions? I don't have read and execute permission to all users.

1[root@rancid ~]# ls -l /usr/local/rancid/var/
2total 12
3drwxrwx---. 5 rancid netadm 67 Sep 23 18:36 CVS
4drwxr-x---. 2 rancid netadm 4096 Sep 23 19:00 logs
5drwxr-x---. 4 rancid netadm 4096 Sep 23 19:00 Routers
6drwxr-x---. 4 rancid netadm 4096 Sep 23 19:00 Switches

Change it by running this command. chmod 775 /usr/local/rancid/var/CVS/ Verify:

1ls -l /usr/local/rancid/var/
2total 12
3drwxrwxr-x. 5 rancid netadm 67 Sep 23 18:36 CVS
4drwxr-x---. 2 rancid netadm 4096 Sep 23 19:00 logs
5drwxr-x---. 4 rancid netadm 4096 Sep 23 19:00 Routers
6drwxr-x---. 4 rancid netadm 4096 Sep 23 19:00 Switches

Hope that Helps. Ryan


Ryan -

Hey Night-Fury, That actually looks right to me, rancid modifies the TO field in the email header but if you look in the log file located at /var/log/maillog you'll see that the message does get forwarded. In this example (real-email@example.com) is the email address I typed in the aliases file to send the email messages to. You may have to change a setting in your email system to allow this message to send.

 1[root@rancid log]# tail -n 9 maillog
 2Jan 22 19:03:07 rancid postfix/pickup[5922]: 0C8708026C6B: uid=1000 from=
 3Jan 22 19:03:07 rancid postfix/cleanup[6647]: 0C8708026C6B: message-id=20160123020307.0C8708026C6B@rancid.example.com
 4Jan 22 19:03:07 rancid postfix/qmgr[1723]: 0C8708026C6B: from=rancid@rancid.example.com, size=1483, nrcpt=1 (queue active)
 5Jan 22 19:03:07 rancid postfix/cleanup[6647]: 1DFC780BE715: message-id=20160123020307.0C8708026C6B@rancid.example.com
 6Jan 22 19:03:07 rancid postfix/qmgr[1723]: 1DFC780BE715: from=rancid@rancid.example.com, size=1665, nrcpt=1 (queue active)
 7Jan 22 19:03:07 rancid postfix/local[6655]: 0C8708026C6B: to=rancid-Switches@rancid.example.com, orig_to=, relay=local, delay=0.11, delays=0.06/0.04/0/0.02, dsn=2.0.0, status=sent (forwarded as 1DFC780BE715)
 8Jan 22 19:03:07 rancid postfix/qmgr[1723]: 0C8708026C6B: removed
 9Jan 22 19:03:07 rancid postfix/smtp[6658]: 1DFC780BE715: to=real-email@example.com, orig_to=, relay=email.example.com[192.168.2.25]:25, delay=0.74, delays=0.01/0.02/0/0.71, dsn=2.6.0, status=sent (250 2.6.0 20160123020307.0C8708026C6B@rancid.example.com [InternalId=322292] Queued mail for delivery)
10Jan 22 19:03:07 rancid postfix/qmgr[1723]: 1DFC780BE715: removed
11[root@rancid log]#

Hope that Helps, Ryan


Ryan -

Hey Night-Fury, Each mail system varies sometimes there are called trusted hosts or relays. The mail system has to trust rancid in sending emails. In your log it says queued mail for delivery so the message was sent. It is likely something on your email system. Good Luck. Ryan


Alex -

Ryan, I solved my problem (finally !!). I have SELinux enable on my server, I had to change the security context of my folder (using the command chcon). Cheers, Alex


Alex -

Hi, I have the same problem as Abhinav. I've edited the viewvc.conf file as shown in the guide. I've also tried to use cvs_root and default_root instead of root_parents and it didn't work either. What else can be the problem ? Cheers, Alex


Adam -

Hi I ran the last cmd and this is the out put. Can you help

 1[root@rancid ~]# /usr/local/viewvc-1.1.23/bin/cvsdbadmin rebuild /usr/local/rancid/var/CVS/CVSROOT/
 2Using repository root `/usr/local/rancid/var/CVS’
 3Traceback (most recent call last):
 4File “/usr/local/viewvc-1.1.23/bin/cvsdbadmin”, line 175, in
 5db = cvsdb.ConnectDatabase(cfg)
 6File “/usr/local/viewvc-1.1.23/lib/cvsdb.py”, line 904, in ConnectDatabase
 7db.Connect()
 8File “/usr/local/viewvc-1.1.23/lib/cvsdb.py”, line 59, in Connect
 9table_list = self.GetTableList()
10File “/usr/local/viewvc-1.1.23/lib/cvsdb.py”, line 177, in GetTableList
11cursor.execute(sql)
12File “/usr/lib64/python2.7/site-packages/MySQLdb/cursors.py”, line 174, in execute
13self.errorhandler(self, exc, value)
14File “/usr/lib64/python2.7/site-packages/MySQLdb/connections.py”, line 36, in defaulterrorhandler
15raise errorclass, errorvalue
16_mysql_exceptions.OperationalError: (1046, ‘No database selected’)

night-fury -

Hi, thank you for the precise details you have listed !! its hard work. i have set it up on centos 7 and works well. pulled the devices, i can see the configs in viewvc. but the mail it sends, it sends to:

rancid-switches@host-192-168-10-161.localdomain & rancid-rtr-fw@host-192-168-10-161.localdomain

rather than sending it to he email ID which was defined in /etc/aliases. any idea why ?

my files have configuration as below:

/etc/aliases

Custom Rancid Configuration (Put an Email Here)

rancid: <i.have.my.emailaddress.here>@domain.com

Custom Rancid Configuration

rancid-admin-rtr-fw: rancid rancid-rtr-fw: rancid rancid-admin-switches: rancid rancid-switches: rancid

My /etc/postfix/main.cf is:

#relayhost = $mydomain #relayhost = [gateway.my.domain] #relayhost = [mailserver.isp.tld] #relayhost = uucphost relayhost = 10.20.30.40

where can i check mail logs etc to know where the problem is? please help.


Alex -

Hi Ryan, Sorry for the late answer. The error I get is the following:

 1An Exception Has Occurred
 2
 3Python Traceback
 4
 5Traceback (most recent call last):
 6File “/usr/lib/python2.7/site-packages/viewvc/lib/viewvc.py”, line 4855, in main
 7request.run_viewvc()
 8File “/usr/lib/python2.7/site-packages/viewvc/lib/viewvc.py”, line 408, in run_viewvc
 9self.view_func(self)
10File “/usr/lib/python2.7/site-packages/viewvc/lib/viewvc.py”, line 2207, in view_roots
11expand_root_parents(request.cfg)
12File “/usr/lib/python2.7/site-packages/viewvc/lib/viewvc.py”, line 4727, in expand_root_parents
13roots = vclib.ccvs.expand_root_parent(pp)
14File “/usr/lib/python2.7/site-packages/viewvc/lib/vclib/ccvs/init.py”, line 32, in expand_root_parent
15subpaths = os.listdir(parent_path)
16OSError: [Errno 13] Permission denied: ‘/var/rancid/CVS’

Cheers, Alex


Ryan -

Hey Alex, No problem hope your holiday was good ;) So I noticed that you might have installed ViewVC a different way then I did in the above post, not sure if that has anything to do with or not but it might. Your ViewVC is located under /usr/lib/python2.7/site-packages/ where in this post ViewVC is installed under usr/local/. Can you run a sanity check on ViewVC? (This runs a small web server on the system) /usr/local/viewvc-1.1.23/bin/standalone.py -r /usr/local/rancid/CVS On your system it might be: /usr/lib/python2.7/site-packages/viewvc/bin/ standalone.py -r /usr/local/rancid/CVS Does that say any errors? Should report back as saying: server ready at http://localhost:49152/viewvc I would just do a curl to see the HTML document curl http://localhost:49152/viewvc The output should display HTML code if it is working. Hope that Helps, Ryan


Ryan -

Hey Abhinav, Permissions look right as I just checked on my sample box but it just sounds like some type of permission issue It might be something with the viewvc.conf file. Can you verify that you made the correct changes as what I have outlined below. Try that. Ryan Find the following and edit as shown below:

 1 2## Example:
 3## cvs_roots = cvsroot: /opt/cvs/repos1,
 4## anotherroot: /usr/local/cvs/repos2
 5##
 6#cvs_roots = cvs:
 7
 8## svn_roots: Specifies each of the Subversion roots (repositories) on
 9## your system and assigns names to them. Each root should be given by
1011## Example:
12## root_parents = /opt/svn: svn,
13## /opt/cvs: cvs
14##
15root_parents = /usr/local/rancid/var/CVS : cvs
16
17## default_root: This is the name of the default root. Valid names
1819## Example:
20## rcs_dir = /usr/bin/
21##
22rcs_dir = /usr/local/bin
23
24## cvsnt: Location of cvsnt program. ViewVC can use CVSNT (www.cvsnt.org)
2526## use_rcsparse: Use the rcsparse Python module to retrieve CVS
27## repository information instead of invoking rcs utilities [EXPERIMENTAL]
28##
29use_rcsparse = 1
30

Ryan -

Hey Adam, You have to un-commented these out by removing the "#" symbols. Follow the example above when you edit the viewvc.conf file. Hope that Helps. Ryan


Adam -

Bingo! Thanks a lot Ryan!


Jimmy.Li -

Very helpful .I try to deploy Rancid in Centos 7 for a few weeks ,but cant solve problem caused by dependent packages ,I follow the instruction write by a few years ago ,some packages seems EOL, like mod_python and phpmhash .etc when i seems get into trouble , I find this awesome guidle .thank again ,especially you provide a link to discussions of the BBS .I look forward to your next article about Rancie


Ryan -

You are welcome :)


Ryan -

Hey Iqbal, I have not played around the templates folder in ViewVC. All the HTML information is stored. usr/local/viewvc-1.1.24/templates/include Good Luck ;) Ryan


Ryan -

Hey Rohit, Everything looks good but on your router.db are you using semi-colon? (;) instead of a colon (:)? If you are using newer versions of rancid this needs to be a semi-colon in the router.db. It's awesome that you are using a custom script to support other network devices however I'm have not used Cisco SB switches so the only thing I would look at is the cloginrc file. The missing close-brace error is usually means there is a brace "{" that is open still in your cloginrc file. Good Luck Ryan


Rohit -

Great guide ! amazingly detailed ! thanks for the same.

I have setup rancid, followed all the steps. Here’s a problem that I am facing.

After defining hosts, devices in router.db and passwords/parameters in .cloginrc. I have also configured this to backup config of my cisco sb series switches (did the changes in rancid-fe and have rights permissions set for csblogin and csbrancid files). Finally i executed the /usr/local/rancid/bin/rancid-run command. This brought up all the devices UP in the repositories I created in CVS. all good.

But the configuration is not being pulled by rancid. I checked logs and found the messages as below. Any help would be much appreciated.

switch1 csblogin error: Error: missing close-brace switch1: missed cmd(s): show version,show system,show startup-config switch1: End of run not found

Here are the settings that I did in the required files

host file 192.168.0.242 switch1

router.db switch1:cisco-sb:up

cloginrc add method switch1 ssh add user switch1 {admin} add password switch1 {passw0rd12$} add autoenable switch1 1 add userprompt switch1 {“user name:”}

-best Rohit


Rohit -

hey thanks Ryan. I am using colon coz its old version of rancid since in the new i can not update vendor table. however what you said is correct, i found the missing close brace. I looked for it before posting here but i guess I missed it and thought it could be due to some other reason. but thanks for getting back. again a great guide. it helped a lot !!!


Ryan -

Neel, You might want to check your httpd.conf file (Line 368) there is something that is causing this error to come up, maybe a mistype? Jun 08 04:27:54 Test httpd[2662]: httpd: Syntax error on line 368 of /etc/httpd/conf/httpd.conf Hope that Helps, Ryan


Neel -

Hello.. Am very new to linux and am trying your installation guide above. After completing the installation, i have no access to http://rancid-ip/viewvc. When trying to restart httpd service. The following error is obtained.

 1Job for httpd.service failed because the control process exited with error code. See “systemctl status httpd.service” and “journalctl -xe” for details.
 2
 3systemctl status httpd.service
 4
 5● httpd.service – The Apache HTTP Server
 6Loaded: loaded (/usr/lib/systemd/system/httpd.service; enabled; vendor preset: disabled)
 7Active: failed (Result: exit-code) since Wed 2016-06-08 04:27:54 EDT; 1min 7s ago
 8Docs: man:httpd(8)
 9man:apachectl(8)
10Process: 2664 ExecStop=/bin/kill -WINCH ${MAINPID} (code=exited, status=1/FAILURE)
11Process: 2662 ExecStart=/usr/sbin/httpd $OPTIONS -DFOREGROUND (code=exited, status=1/FAILURE)
12Main PID: 2662 (code=exited, status=1/FAILURE)
13
14Jun 08 04:27:54 Test systemd[1]: Starting The Apache HTTP Server…
15Jun 08 04:27:54 Test httpd[2662]: httpd: Syntax error on line 368 of /etc/httpd/conf/httpd.conf: Expected but saw
16Jun 08 04:27:54 Test systemd[1]: httpd.service: main process exited, code=exited, status=1/FAILURE
17Jun 08 04:27:54 Test kill[2664]: kill: cannot find process “”
18Jun 08 04:27:54 Test systemd[1]: httpd.service: control process exited, code=exited status=1
19Jun 08 04:27:54 Test systemd[1]: Failed to start The Apache HTTP Server.
20Jun 08 04:27:54 Test systemd[1]: Unit httpd.service entered failed state.
21Jun 08 04:27:54 Test systemd[1]: httpd.service failed.
22
23#journalctl -xe
24Jun 08 04:06:02 Test kill[2626]: kill: cannot find process “”
25Jun 08 04:06:02 Test systemd[1]: httpd.service: control process exited, code=exited status=1
26Jun 08 04:06:02 Test systemd[1]: Failed to start The Apache HTTP Server.
27— Subject: Unit httpd.service has failed
28— Defined-By: systemd
29
30— Support: http://lists.freedesktop.org/mailman/listinfo/systemd-devel
31
32— Unit httpd.service has failed.
33
34— The result is failed.
35Jun 08 04:06:02 Test systemd[1]: Unit httpd.service entered failed state.
36Jun 08 04:06:02 Test systemd[1]: httpd.service failed.
37Jun 08 04:06:02 Test polkitd[934]: Unregistered Authentication Agent for unix-process:2609:303230 (system bus name :1.15, object path /org/freedesktop
38Jun 08 04:27:54 Test polkitd[934]: Registered Authentication Agent for unix-process:2647:434481 (system bus name :1.16 [/usr/bin/pkttyagent –notify-f
39Jun 08 04:27:54 Test systemd[1]: Starting The Apache HTTP Server…
40— Subject: Unit httpd.service has begun start-up
41— Defined-By: systemd
42
43— Support: http://lists.freedesktop.org/mailman/listinfo/systemd-devel
44
45— Unit httpd.service has begun starting up.
46Jun 08 04:27:54 Test httpd[2662]: httpd: Syntax error on line 368 of /etc/httpd/conf/httpd.conf: Expected but saw
47Jun 08 04:27:54 Test systemd[1]: httpd.service: main process exited, code=exited, status=1/FAILURE
48Jun 08 04:27:54 Test kill[2664]: kill: cannot find process “”
49Jun 08 04:27:54 Test systemd[1]: httpd.service: control process exited, code=exited status=1
50Jun 08 04:27:54 Test systemd[1]: Failed to start The Apache HTTP Server.
51— Subject: Unit httpd.service has failed
52— Defined-By: systemd
53
54— Support: http://lists.freedesktop.org/mailman/listinfo/systemd-devel
55
56— Unit httpd.service has failed.
57
58— The result is failed.
59Jun 08 04:27:54 Test systemd[1]: Unit httpd.service entered failed state.
60Jun 08 04:27:54 Test systemd[1]: httpd.service failed.
61Jun 08 04:27:54 Test polkitd[934]: Unregistered Authentication Agent for unix-process:2647:434481 (system bus name :1.16, object path /org/freedesktop
62lines 2349-2383/238

Can you kindly help.


Ryan -

Chris did that rebuild work? Ryan


christopherbnash -

[root@icewarp /]# /usr/local/viewvc-1.2-dev/bin/cvsdbadmin rebuild /usr/local/rancid/var/CVS/CVSROOT/


Neel -

Hello Ryan, Yea, thanks for he prompt reply. Indeed its a silly mistyping error. Its working great. Thanks. :)


christopherbnash -

Yes fixed it. Problem was my config. The user ViewVC wasn't cap and I need to install mysql-python and that fixed my issue.


christopherbnash -

1[root@icewarp /]# /usr/local/viewvc-1.2-dev/bin/cvsdbadmin rebuild /usr/local/rancid/
2Traceback (most recent call last):
3File “/usr/local/viewvc-1.2-dev/bin/cvsdbadmin”, line 43, in
4import cvsdb
5File “/usr/local/viewvc-1.2-dev/lib/cvsdb.py”, line 20, in
6import dbi
7File “/usr/local/viewvc-1.2-dev/lib/dbi.py”, line 18, in
8import MySQLdb
9ImportError: No module named MySQLdb

Having a problem. I checked my mariadb service and it's working.


Ryan -

Hey Iqbal, It looks like ViewVC can't find the the MySQLdb module. Is MySQL (Mariadb) installed? I would think it is since you had to create users before running this command. What happens when you run this command? systemctl status mariadb Ryan


Ryan -

Your Welcome :)


amolaknet -

Hi Ryan, I am getting below error.

 1[root@localhost viewvc-1.1.24]# /usr/local/viewvc-1.1.24/bin/make-database
 2MySQL Hostname (leave blank for default):
 3MySQL Port (leave blank for default):
 4MySQL User: VIEWVC
 5MySQL Password: *******
 6ViewVC Database Name [default: ViewVC]:
 7ERROR 1045 (28000): Access denied for user ‘VIEWVC’@’localhost’ (using password: YES)
 8
 9[ERROR] The database did not create sucessfully.
10
11MariaDB [(none)]> SHOW GRANTS FOR ‘VIEWVC’@’localhost’\G
12*************************** 1. row ***************************
13Grants for VIEWVC@localhost: GRANT ALL PRIVILEGES ON . TO ‘VIEWVC’@’localhost’ IDENTIFIED BY PASSWORD ‘*6025816A8686624E0CC3FA5F99FB8043E68252B7’ WITH GRANT OPTION
141 row in set (0.00 sec)

I have tried to grant privileges again and flush privileges but no luck. Could you please help. Thanks, Amolak


Ryan -

Your welcome, FYI here is the other post I did about Rancid just in case you need it as a reference. https://ciscoskills.net/2015/02/27/configuring-rancid/ Ryan


ginesgb -

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


Ryan -

Hey Wayne, So to be honest I never really tried that query function. So I would not know where to start unfortunately. I did a test on my box and I get a different error then yours :( To what it looks like you might have typed something wrong in the search bar, maybe? I would just search for everything "Since the beginning of time" and see if you get anything comes up Ryan


amolaknet -

nm...I have reinstalled mariadb-server & mariadb. It fixed the issue. Thanks for this great article.