rcc Manual

Requirements

On the other hand, the control-flow analyzer has several dependencies. We've highlighted the dependencies that are specific to the control-flow analyzer below.

• perl (v5.8.0 or greater suggested)
• mysql (v.3.23 or greater suggested)
• perl modules
  • Getopt::Long
  • NetAddr::IP
  • DBI
  • Heap::Fibonacci
  • Digest::SHA1 (used to store and compare hashes rather than plaintext of auth keys)
  • CGI::Pretty (optional; for configuration browser only)
  • Algorithm::Diff (optional; for configuration browser only)
• Graphviz dot

Download

We are committed to making a tool that is useful to the operator community, but we can't do this without operator feedback!
We also emphasize that this tool is alpha, and only the adventurous should proceed. :)

To download the code, please take the following steps:

1. Get access to the CVS pserver. The code is available for download via a CVS pserver.
   You can ask for access via this form.

2. Download code via the CVS pserver.
   • Type cvs -d :pserver:[username]@nms.lcs.mit.edu:/cvs login.
     Enter your password when asked for it.
   • Type cvs -d :pserver:[username]@nms.lcs.mit.edu:/cvs checkout rolex.
     You should now have all of the code, DB schemas, documentation in a directory under rolex

Important Note: To make this process a little more painless, these steps can now be executed using the menu.pl script in perl/src/utils/. Running this script and selecting from the appropriate menu options can prevent you from having to run most of the steps below from the command line.

Setup

1. Configuration File Setup. The verifier is currently configured to read AS-wide configuration files from a single directory. The following two steps are necessary for the verifier to work.
   
   • Place the configuration files in a single directory, and name the files according to the following format:
     • [router-name]-confg for Cisco IOS files.
     • [router-name]-jconfg for Juniper files.

   • If you don't use peer-groups, you can probably skip this step for now. Change directories into perl/src/utils and run ./riftrans_all.pl [config-dir], where config-dir is the directory where you have placed the files. This script simply does some preprocessing of the configs; for example, it expands things like the peer-group macro, etc.

   Note: The tool currently has modules for Cisco and Juniper configuration parsing. The Cisco module works fairly well for Zebra, Avici, and (with minor modifications) Procket.

2. Default Settings. Most of the default settings are specified in ConfigCommon.pm. In particular, you will want to set the variables that determine the host, port, user, and password information for accessing the database.

   ConfigCommon.pm also contains important variable settings, such as the location of the binaries such as dot, etc., which will be necessary if you decide to use any of these binaries or want to change the location of the temporary directory.

   Some of the tests for the configuration verifier require knowledge of which ASes are peers. If you care about running those tests, you should create a file in the perl/conf/ directory called peers.txt. The file should include a comma-separated list of peers. The distribution includes an example.

3. Database Setup. You will need to create a database. The default database names that ConfigDB.pm looks for areconfig_if (for the BGP constraint verifier), config_isis (for the IS-IS constraint verifier) and config_control_flow (for the configuration browser). The easiest way to do this is to fire up mysql (or equivalent) and type create database config_if (or or config_control_flow).

   (If you must change the default database name, this can be done in ConfigDB.pm.)

4. Database Schema Setup. Now it's time to set up the database tables. The distribution includes the database schema in the db-schema/ subdirectory. The easiest way to do this is to type the following:
   • cat db-schema/config_control_flow.sql | mysql config_control_flow
   • cat db-schema/config_if.sql | mysql config_if
   • cat db-schema/config_isis.sql | mysql config_isis
   at the shell prompt.

5. Web interface setup (configuration browser only). flowgraph.cgi is an interface to the database that shows some (hopefully) interesting things about the control graph. flowgraph.cgi is a CGI script. Therefore, it must be placed at some location on the Web server where executing CGI scripts is allowed. You must also indicate the location where the verifier libs are located. (i.e., modify the push(@INC, "/home/feamster/bgp/src/rolex/perl/lib"); line to point to the appropriate place, and make sure that the libs are world-readable.)

   If you had to move flowgraph.cgi to a cgi-bin directory, you should also make sure that you either (1) moved ConfigWeb.pm to the same directory or (2) added a push(@INC, dir) statement to the code to point to the directory where ConfigWeb.pm is located.

Usage

Constraint Verifier

1. Parsing Cisco and Juniper configs into an intermediate format.

   This is done with the script gen_intermediate.pl in the src/config-convert subdirectory. Important options for this script:

   • --configdir=[dir] (mandatory) specifies the directory where the script should look for configs (note, this should be the location of the translated configs from the setup above).
   • --db -- inserts the intermediate format to the database created in the setup. You'll almost always want this option. If you don't specify this, the intermediate format will be output to stdout.
   • --junos -- specify that the script should look for (and parse JunOS configs)

2. Running the constraint checks.

   This is done by executing a perl script, such as the example we have included in src/queries/scripts/test_all.pl (you should run this script from the scripts directory).

   • --files=[dir] -- if this option is not used, results from the tests will be printed to STDOUT. Otherwise, results printed to .txt files in dir.

   More info:Each test is a class method; constraints are grouped by classes, so it's easy to write a script that runs any subset of tests in test_all.pl.

Configuration Browser

The control flow analyzer consists of:

• CFlow. A analysis script, cflow.pl, which parses the configuration files and generates a high-level control flow analysis, in the form of a text-based or graphical flow graph. Typically, this analysis will be inserted into the database that you created in the setup phase.

  (If you opted to skip setting up the database, it's possible to run the script in "basic mode", or "graph mode", described below, but it's much less useful.)

  The script has several options:

  • Basic mode, with no options. This mode will simply print out a text representation of the high-level BGP configuration (i.e., what routers are connected to what, etc.). It does not require a DB backend.
  • Graph mode, with the --graph option. ./cflow.pl --graph=dot will produce a dot representation of the network, which can be graphed directly with the dot program. ./cflow.pl --graph=eps will run dot automatically and produce a .eps file.
  • DB mode, with the --db option. ./cflow.pl --db will populate the database that can be used with the --> CFWeb interface. This requires that the DB was set up properly, according to the setup instructions above.

• CFWeb. A web interface that queries the database backend, flowgraph.cgi. Using this interface is fairly straightforward. Just make sure you've set things up correctly in the setup phase, place flowgraph.cgi somewhere in your web server's document tree where you can execute CGI scripts, and point the browser at that location.

Development