This document is copyright:
    2006 The University of Wisconsin Board of Regents

  We wish to thank Cisco Systems, Inc for the donation of
the original source code upon which this program is based.

  CatOS, IOS and Catalyst are trademarks of Cisco Systems, Inc.
No usage of those terms in this document is intended to
dilute their rights.

  This program is being released as a kindness to others who
may find it useful.  It is not to be considered complete or
functional for any purpose.  It is not to be expected that
it works for any purpose you may have in mind for it.  The
user bears sole responsability for any use this code is
put to.   If you rely on it "bad things" (tm) may happen.

.--------------------------------------.
|              catcfg_xlat.pl          |
`--------------------------------------'

  catcfg_xlat.pl is a perl program to convert the router and
switch configs of Catalyst 6500 running in hybrid mode to
a config suitable for a Catalyst with a Sup720 running in
native IOS mode.  It consists of the following programs:

  catcfg_xlat.pl - the program which performs the actual translation.
  catcfg.pm - a PERL module which contains subroutines to perform
              the heavy lifting of the translation process
  parse_lib.pm - a PERL module which can parse CatOS configurations.
  httpd-paths.pm - a simple stub to replace the missing original
    that aided catcfg_xlat.pl when called as a CGI script to find
    the path on a chrooted web server.  This could have been 
    safely gutted, but I left it in, in case someone decided to
    return this program to being a web app.
  conf_template.txt - the template used to normalize the configs.
    Invariant config sections had their parse subroutines 
    commented out, and this config file was prepended to the
    modified IOS config before printing.  When I GPL'd the code
    I gutted anything I did not feel like normalizing or explaining.
    Hopefully no-one will be deluded enough to confuse a sample
    config template with a best practice.

.--------------------------------------.
|               License                |
`--------------------------------------'

  Copyright (C) 2006 The University of Wisconsin Board of Regents
  Licensed and distributed under the GNU Public License
    http://www.gnu.org/copyleft/gpl.html
 
  We wish to thank Cisco Systems, Inc for the donation of
  the original source upon which this is based.

  Originally developed as a web application and modified
  by the University of Madison to run as a standalone application.

  This was intended for one time use, and is being released to 
  allow others to use the code if it makes their transition from
  CatOS (TM) to IOS (TM) easier.   Knuth once said to beware
  of an application that was proven to be correct, but not
  tested.  This is neither.

  We specifically assert that this code is not warranted to be of use
  to any entity for any purpose.  You are however free to use it
  for any purpose you want consistent with the GNU GPL.


.--------------------------------------.
|         Theory of Operation          |
`--------------------------------------'

    This code is intended to take the seperate configs of a
  Catalyst 6500 in Hybrid mode, and a template with some
  standard config elements, and merge them into a single configuration
  file suitable to be checked for errors by hand and then applied
  with config term or config net.

    You can place the code in any directory you choose, along with
  the associated perl modules.  You should either run the command
  from the directory you keep the configs in, or remove the code
  that parses the config file names since the program parses the
  filename to determine the $hostname variable which replaces some
  sections of the template.    Although our naming convention is
  internally consistent, it is highly unlikely these same rules
  will work for other users of this software.

    It will also be necessary to edit the code to remove or
  modify any rules related to treating a -1-core device differently
  from a -2-core device.

    I really should have replaced certain kludges in the 
  software.  The use of commented out print statements for
  debugging should be replaced with a dprint subroutine that
  keys on -d, and the use of statements to manually place skipped
  commands into an array ($SKIPPED_COMMANDS->[$i] eq "skipped")
  should be replaced with an addSkippedCommand subroutine.
  In many places we want to ignore certain commands,  and 
  I handled it in some cases by commenting out the parser's
  name in the %PARSERS_SET hash in catcfg.pm, in some cases
  by commented out the addGlobalConfig call in catcfg_xlat.pl
  and in others by modifying the parsing.  In general I had
  reasons for doing so, sometimes it had to do with whether I
  wanted a command to be silently ignored instead of added to
  the $SKIPPED_COMMANDS array, in other times I probably just
  was being lazy.  This should be normalized.

    Please bear in mind, this software was written to run once, 
  to manage a migration from Hybrid CatOS/IOS to native IOS when
  we upgraded from Supervisor 2 cards to Supervisor 720 cards.

    It would be naive in the extreme to expect this code to 
  function for whatever use you had in mind for it.  It would
  be even more naive to expect it work after you modify it
  without testing.

    The user of this code is solely responsible for anything
  they do with it.

    The code is relatively straightfoward.  Usage can be expected
  to happen as follows:

 - install the files into some useful path, probably
   ~user/sup720/

 - check the files into RCS/CVS or whatever you use to
   maintain your source code repository before you begin
   editing them.  This is not required, but certainly is
   a sane thing to do.

 - edit httpd-paths.pm
   Since this was originally a web application, it needed to
   know the false root of the web server.  I was never given
   a httpd-paths.pm.  I created a stub that returned what the
   program since it was relatively easy, and I thought someone
   might want to make it a web app again. 
   
   You'll need to edit the paths for $ChrootRoot to be the
   actual directory you stored it in.

 - edit catcfg_xlat.pl to reflect your needs.
   At a minimum you'll edit the "use lib" line.

   You should probably change the code to parse the file name
   and determine what role the device serves based on filename.

   There are lots of pieces of code to normalize the config
   template.  For example this piece of code replaces the
   $hostname in the template with the contents of the variable
   $hostname in the code itself (gleaned from the config file name).

    } elsif ($_ =~ /You are connected to the \$hostname Router./) {
      s/\$hostname/$hostname/;
      print "$_\n";

   You probably want to edit it.
   
 - Edit the parsers in parse_lib.pm   A parser takes a config
   line from the CatOS config and places it into a datastructure,
   usually the global config.  Many of them have lines commented
   out, because we wanted to ignore those config bits from the
   CatOS config and replace them with bits from the template.
   You may choose to make a different decision.   Remember that
   the last config but applies is the one that takes affect.
   Putting something in the template, which is prepended to the
   config, and then having a parser write something different,
   means you lose the config bits from the template.


.--------------------------------------.
|          Running the Program         |
`--------------------------------------'

 - change into the direction where you config files are stored:
   cd /full/path/to/stored/configs

 - run catcfg_xlat.pl

     The program spits out a config on standard output, and the
   errors it found, including config lines it was unable to
   parse, on standard error.

   You can run it as follows:
     /full/path/to/catcfg_xlat.pl -r router-config.conf -s switch-config.conf

   But I generally recommend the following:

   /path/to/catcfg_xlat.pl -r rh-site1-101-1-node.conf -s sh-site1-101-1-node.conf > r-site1-101-1-node.conf 2>r-site1-101-1-node.err

    This sends the config to r-site1-101-1-node.conf and the errors
  to r-site1-101-1-node.err for bash users.

    Note:    It expects the router config text file to actually have
           meaning, since we use the following convention.

      For a 6500 in hybrid mode:
        role is either rh (a router) or sh (a switch)
        location is the bulding short-name.
        room_num is the room number.
        position is either 1, a primary, or 2 the backup.
        use is whether the device is core, node or access.
        For most customers, this code can be completely removed.
 
      rh-cssc-b280c-1-core.conf means:
      rh = router config of a 6500 in hybrid mode.  
      cssc = computer science and statistics building
      b280c is the rooom number.
      1 is the primary 6500
      core is because it's a core device.
      .conf is the extension we use for our config files.
 
    This code only matters because we added rules to configure
  the primary and secondary boxes differently, and we wanted
  to normalize the configs while we were converting.  As I
  mentioned, most people will simply remove this code and use
  whatever file names for your configs you choose to.

.--------------------------------------.
|           Getting Help               |
`--------------------------------------'

  A number of excellent PERL programmers and network engineers
are available for hire as consultants.  You can also hire someone
through contracting houses and consulting firms.  I do not with to
be one of those people.  If you wish, you can email me, plato at a machine
named wisc.edu.  I cannot promise any help, or even a reply, but I
would enjoy the email, and perhaps I could offer moral support.

I hope this program saves you some time.

Janet Plato, Sr Network Engineer, UW Madison