Config Review Tool

Version 1.0.0
20 Aug 2010

Contents

• Introduction
• Operation
• Installation
• License
• History
• Attachments -- download tool from here

Introduction

The Netomata Config Review Tool is a web CGI script for reviewing NCG-generated config files and approving them for installation on devices.

For each device, the tool keeps track of 3 config files (if they exist):

• Original: the config that the device was originally running (which was presumably created by hand)
• Generated: the most recent config generated by NCG
• Approved: the most recent generated config that has been "approved" via this process

For each device, this tool lets you:

• View the Original, Generated, and (if it exists) Approved config
• See diffs between pairs of configs:
  • Original => Generated
  • Generated => Approved
  • Original => Approved
• Approve a Generated config (i.e., make it the Approved config for the device)
• Unapprove a currently approved config (i.e., delete the Approved config for the device)

The tool does not (yet) install approved configs on devices; the assumption is that you will use a tool such as RANCID to do that, from the files in the "approved" directory.

Operation

When you first access the tool via the web, you will see a list of devices, with various links and action buttons for each device, like this:

The "Device" column lists the device configs that the tool sees in the "generated" directory.

The "Configs" columns are links that allow you to view/download the original, generated, or approved config for a particular device (if it has one).

The "Diffs" buttons let you compare the different versions of the config for a particular device.

The "Actions" buttons let you approve or unapprove the generated config for a particular device. The "approve" button simply copies the generated config into the "approved" directory, while the "unapprove" button simply deletes the config from the "approved" directory (the "unapprove" button will only appear if the device has an approved config).

"Generated is newer" warnings

If the "generated" file is newer than the "approved" file for a particular device (which would happen, for instance, if a new config file has been generated since the last time the config was "approved"), then the tool will put a warning in the "Configs/Approved" column, like this:

To clear this warning, you can review the differences between the generated and approved versions of the file (using the appropriate "Diffs" button), and then approve the newly-generated version of the file.

Diffs

Clicking one of the "Diffs" buttons will generate a page that highlights (in yellow) the differences between the two versions of the config, like this:

At both the top and bottom of the "diffs" page, there are three buttons: "approve" and "unapprove" take that action on the generated config (the same as the "approve" and "unapprove" buttons on the main page), while "return" simply returns you to the main page without taking any action.

Messages and Errors

When you successfully "approve" or "unapprove" a file, a message confirming that will appear in a green box at the top of the main page, like this:

The message is also shown in the browser window title.

If an error occurrs, the error message will be shown in the same place, though the box will be red rather than green.

Installation

Download

The home page for this tool is:

http://www.netomata.com/wiki/config_review_tool

The current version of the tool can be downloaded from the "Attachments" links at the bottom of this page.

Assumptions

The tool assumes:

• There are 3 directories in its current working directory (typically the same directory that the review_configs.cgi program is installed in):

  • original
  • generated
  • approved

  Each of these may be a symlink to a directory elsewhere. The tool needs read permission on the "original" and "generated" directories and the files they contain, and both read & write permission on the "approved" directory.

• Each subdirectory, in turn, contains the actual original/generated/approved config files for the various devices; so, for example, for device "anak", the tool would manipulate the files:

  • original/anak
  • generated/anak
  • approved/anak

• The tool requires the GNU diff program to determine the differences between versions of a config. It assumes that this program is installed as /usr/bin/diff ; you'll need to edit the source code of the tool to change the path, if it is installed somewhere else on your system.

• The tool was developed under Ruby 1.8.7; however, it is a fairly simple program which makes use of the Ruby "CGI" library, so it should probably work just fine under earlier or later versions of Ruby.

Installing as CGI

In general, you should simply need to:

1. Unpack the .tar archive into the directory where you want the CGI to be installed. The main review_configs.cgi script expects to find several other files (i.e., this README, the Netomata logo, etc.) in the same directory as it runs in.

2. Create directories (or symlinks to directories) for the original, generated, and approved files. The tool needs read permission on the "original" and "generated" directories and the files they contain, and both read & write permission on the "approved" directory.

   WARNING: make sure you read the Security section, below, and take appropriate steps to protect your configs.

The method for setting up a CGI program varies from web server to web server, and is beyond the scope of this document. Here are some general tips (with a bias towards Apache 2.x):

• The directory that you install the tool in needs to be one in which CGI programs are recognized and executed. Under Apache, that means that the directory needs to be covered by an "ExecCGI" option in the Apache config.

• If you use symlinks in your setup (for instance, if the orig, generated, or approved directories are actually symlinks to directories somewhere else), then the directory needs to be covered by a "FollowSymlinks" option in the Apache config.

• If your directory is covered by an appropriate "AllowOverride" directive in your Apache config, then you could use a local .htaccess file in the directory to make the necessary config changes, rather than modifying the main Apache config.

• You need to know what user/group the tool is going to run as, so that you can set up appropriate permissions on the original, generated, and approved directories and the files therein. If you aren't sure, edit the review_configs.cgi file to change the following line (in the "Main Code" section, near the end of the program):

  $debug = false

  to

  $debug = true

  This will cause a bunch of debugging info to be printed at the bottom of every page that the program generates. Near the bottom of the debugging info, it tells you the UID/EUID and GID/EGID that the program is running as. The directories and files need to be accessible to the EUID and/or EGID (effective UID/GID).

Security

This tool, and the directories and files that it accesses, should be protected via standard HTTP access control mechanisms, such as an appropriate .htaccess file. Otherwise, anyone who can access the web server will be able to view your device config files, which may contain sensitive information such as clear-text or weakly-encrypted passwords.

The tool needs read permission on the "original" and "generated" directories and the files they contain, and both read & write permission on the "approved" directory.

License

Copyright (C) 2010 Netomata, Inc. All Rights Reserved. Please review the accompanying "LICENSE" file for important notices, disclaimers, and license terms.

This tool is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License, version 3, as published by the Free Software Foundation. A copy of the GNU General Public License, version 3, is included with the Netomata Config Review Tool, in the file named "COPYING".

History

This tool was originally developed in August 2010 by Brent Chapman <brent@netomata.com> of Netomata, Inc.