The pattern-based constraint verifier should run with minimal support;
no database support is needed, nor does the program depend on any
database support, CGI, etc.
On the other hand, the control-flow analyzer has several dependencies.
We've highlighted the dependencies that are specific to the control-flow
- perl (v5.8.0 or greater suggested)
- mysql (v.3.23 or greater suggested)
- perl modules
- 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)
We eventually plan to make our code available to the general public.
Because our tool is in its infancy, and because we want operator
feedback, help, etc. in adding features, fixing bugs, and developing the
tool, we are initially providing download access via a CVS pserver
only. This helps us keep track of the people in the community that are
trying out the tool, and encourages others in the community to contribute.
We are committed to making a tool that is useful to the operator
community, but we can't do this without operator feedback!
emphasize that this tool is alpha, and only the adventurous
should proceed. :)
To download the code, please take the following steps:
- Get access to the CVS pserver. The code is available for
download via a CVS pserver.
You can ask for access via this form.
- Download code via the CVS pserver.
- Type cvs -d :pserver:[username]@nms.lcs.mit.edu:/cvs
Enter your password when asked for it.
- Type cvs -d :pserver:[username]@nms.lcs.mit.edu:/cvs checkout
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.
It should now be possible to run the verifier scripts. If you encounter
problems, please contact us.
- 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.
- 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.
- 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
(If you must change the default database
name, this can be done in ConfigDB.pm.)
- 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
at the shell prompt.
- cat db-schema/config_control_flow.sql | mysql
- cat db-schema/config_if.sql | mysql
- cat db-schema/config_isis.sql | mysql
- Web interface setup (configuration browser only).
flowgraph.cgi is an interface
to the database that shows some (hopefully) interesting things about the
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.
The verifier scripts are located in the perl/src/ directory. The
scripts for each part of the verifier are located in subdirectories.
This section of the manual describes how to run those scripts, and, in
the case of the control-flow analyzer, how to use the Web interface.
The scripts for the constraint verifier are located in the
perl/src/queries/ subdirectory. Running the constraint
verifier involves two steps:
- Parsing Cisco and Juniper configs into an intermediate
This is done with the script gen_intermediate.pl
in the src/config-convert subdirectory. Important options for
- --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)
- 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
will be printed to STDOUT. Otherwise, results printed to .txt files in
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
The scripts for the pattern-based verifier are located in the
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
(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
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.
Coming soon: Instructions for how to write new rules for the
configuration verifier (i.e., writing new perl modules).