(This file was last updated October 15, 2010 by Pete Siemsen)

This file describes a set of Perl scripts called "SwitchMap" that
generate handy Web pages describing Cisco switches.  The comments at
the top of the file contain more information.

INSTALLING SwitchMap on Microsoft Windows:

See Windows_Installation.pdf for Windows-specific instructions.  Even
if you read that file, you'll probably want to read this file anyway
to learn how SwitchMap works.

INSTALLING SwitchMap on Unix/Linux:

Below, I've tried to guess what will be needed to get the script
working at your site.  It's assumed that you have Perl 5.0.  If there
are problems, please send email to the address given at the bottom of
this file.

1. Get the Perl modules needed by switchmap.  If you are running
   Debian Linux, this should do it:

   (as root)
   apt-get install libnet-snmp-perl
   apt-get install liblog-log4perl-perl
   apt-get install liblog-dispatch-perl
   apt-get install libsnmp-perl

   If you have a non-Debian system, with Perl installed, try the

   (as root)
   perl -MCPAN -e shell
   install Log::Log4perl
   install Module::Build
   install Net::SNMP
   install Log::Dispatch::Screen

2. Unpack the distribution

   The switchmap Perl scripts create web pages, so you'll want to
   install the scripts on a machine that has a web server.  Put the
   distribution file (named something like switchmap-12.0.tar.gz) in
   a directory somewhere on the machine.  If you have permisson, put
   it where your operating system likes to store third-party software.
   On Unix systems, this is /usr/local.  Gunzip/untar it.  You should
   end up with a directory named something like "switchmap-12.0".  It
   should contain the following files:

    CHANGELOG                      Shows history of changes  From Cisco, provides SNMP OIDs          From Cisco, provides SNMP OIDs             From Cisco, provides module data              MIB constants and code to read them                   Constant definitions                EtherChannel class                  CGI script, implements "search"                      Program to get ARP caches from routers           Gets some port data from switches                 Gets MAC addresses, hostnames, switchnames                  ModuleList class                    OuiCodes hash
    OuiCodes.txt                   Organizationally Unique Identifiers table                  General utility functions       Contains the PopulateEtherChannels function               Contains the PopulatePort function                        Port class                  contains the "portically" sorting function
    README                         this file                  Perl script to generate "idlesince" files
    SearchPortlists.html           HTML file that invokes             SNMP communities and code to read them                       Code to produce the statistics page                      Switch class
    SwitchMap.css                  CSS file used by the generated web pages
    switchmap                      Optional Unix startup file for /etc/init.d
    switchmap-daemon               Optional script used by "switchmap"                   Main program                 Include file containing shared functions                    Site-specific constant definitions              Program to generate OuiCodes.txt
    VerifyPortLabels               Check port labels (used only at NCAR)                        Vlan class
    Windows_Installation.pdf       How to install SwitchMap on Windows systems           Writes the csv directory  Writes the gigeportspervlan directory            Writes the modulesbyswitch.html file              Writes files used only at NCAR         Writes the ports directory           Writes the Power-over-Ethenet ports file    Writes the Power-over-Ethenet ports file      Writes the switches directory        Writes the unused directory         Writes the vlans directory
    error-log.shtml                beta code to view nidex.php's error log
    index.php                      beta code to refresh SwitchMap on demand

   These files are described in more detail in the comments at the top
   of the main program file named

3. Set up SNMP in your switches and routers

   Make sure your routers and Catalyst switches are configured to
   speak SNMP.  This command enables SNMP on a Cisco Catalyst switch:

     snmp community read-only public

   You should choose another SNMP community string than "public".  See
   the file for instructions for how to configure
   community strings into the switchmap programs.

4. Define site-specific variables

   Change the definitions in to fit your site.  Comments
   in the file explain this in detail.  This is where you define the
   names of the routers and switches in your network, where the output
   files should get written, etc.

5. Run

   Switchmap needs to map MAC addresses to IP addresses.  If you don't
   use HP OpenView, SwitchMap reads a mapping table from a file named
   MacList.  The MacList file is created and updated by the
   script. reads ARP caches from your routers and updates
   the MacList file.  To tell the names of your routers, set
   the @routers array in the file.  Router ARP cache
   entries time out, so to make MacList as complete as possible, you
   should run often (see below).  If it doesn't work, use
   the "-d" option to turn on debugging messages.

   As of version 12.0, SwitchMap reads ARP caches from switches as
   well as routers, so that it can produce information about routing
   ports as well as switching ports.  You still need to run
   to maintain the MacList file.

6. Run

   This should create a directory named "idlesince" containing a file
   for each of your Cisco switches.  If it doesn't work, use the "-d"
   option to turn on debugging messages.

7. Run

   This should produce HTML files in subdirectories of the
   $DestinationDirectory that you configured in your file.
   The subdirectories are named "ports", "vlans" and "switches".  If
   it doesn't work, try using the "-d" option to turn on debugging

8. Look at the resulting files

    Point your Web browser at the $DestinationdDirectory.  There
    should be an index.html file.  Hope it looks ok!

9. Once the above is working, you'll want to set up some mechanism to
   run the programs on a regular schedule to keep the web pages
   up-to-date.  Mechanisms to do this depend on your operating system.
   Some approaches for Unix-based systems are described here.  Windows
   users should look in the Windows_Installation.pdf file in the
   SwitchMap distribution.

    A. cron jobs

       Option 1:

    Set up one cron job to run, which will run all
    three SwitchMap programs.  This option is simpler than Option 2,
    but offers less flexibility - you'll tend to run a
    little more often than you probably need, and you may run less often.  If you use this option, you'll have to
    edit to install some paths and such.

       Option 2:

    Set up 3 separate cron jobs to run the 3 programs regularly.  This
    is what I do at my site.  Set up one job to run
    every hour and one to run every day.  If you don't
    have HP OpenView, set up a third cron job to run every 3
    hours.  Of course, you may want to change these frequencies - some
    sites run SwitchMap every hour.  My crontab entries look like

# These entries run Pete Siemsen's switchmap scripts to gather
# information about Ethernet switch ports.  The result is web pages
# created every day that show what machines are connected to the
# switch ports.
# At 44 minutes after every hour, scan the switches for port
# statuses and update the .idlesince files, then at 49 minutes
# after every hour, get ARP information from the routers and
# update the MacList file.
44 * * * * /usr/web/nets/internal/portlists/
49 * * * * /usr/web/nets/internal/portlists/
# At 2:05pm every day, during the middle of the day when the
# most ports are likely to be active, read the .idlesince files
# and create the web pages.  It's best to run this when there's
# a lot of network traffic, so you're most likely to find MAC
# address information in the switch CAM tables.
05 14 * * * /usr/web/nets/internal/portlists/

   B. startup daemon

   This is an alternative to cron jobs.  It uses the standard Unix
   mechanism to start a daemon when the system boots.  The daemon runs
   the SwitchMap programs.  This requires a little more knowledge of
   Unix than the cron mechanisms.  Copy the file named "switchmap" to
   /etc/init.d and edit it to set the paths.  If you have "chkconfig",
   run it to set up the proper links to the "switchmap" file.

10. If you have HP NNM and you've set up SNMP community strings
    correctly, the SwitchMap programs will automatically adjust as you
    add or remove switches from your network.  If you don't have NNM,
    you'll have to manually keep the "LocalSwitches" and "routers"
    arrays up-to-date in your file.

11. The HTML files produced by includes a "search the
    port lists web pages" feature.  This allows users to, for example,
    find a port by the IP address it serves.  To make the search
    functionality work, you have to set up the following things:

    1. Edit  In the "use lib" line, change the path to
       the directory that contains

    2. Copy to a directory known to your web server.
       The directory must be one that the web server allows CGI files
       to be run from.  The easiest thing to do is to leave in the directory that you configured as the
       $DestinationDirectory in your file.  Then configure
       your web server to add that directory to the list of
       directories that can contain CGI files.  If you don't run the
       web server yourself, ask the person who does.  They may require
       that you put somewhere else.

    3. Edit SearchPortLists.html to fix paths.  Near the top, you'll
       find 7 references to the directory where the SwitchMap files
       reside (at my site the references are
       "/nets/internal/portlists").  Change them to the directory
       where SwitchMap resides on your system (it'll be the same place
       as the $DestinationDirectory in your, but relative
       to the root of the web server).

       A little further down, find the "form" tag, and set the value
       of it's action attribute to the path to  At my
       site it's "/nets/cgi/internal/".  You'll need to
       replace the "nets/cgi/internal" with the appropriate path to
       the place you copied to in step #2.

    4. Copy SearchPortLists.html to the directory that you defined as
       the $DestinationDirectory in  While you're at it,
       edit the blurb at the bottom, after the <hr>, to make it
       reflect your site, not mine :-)

    FindOffice allows an optional "fmt=csv" argument to the search
    query.  If it's present, will return CSV lines
    instead of an HTML page.  This can be used to search the SwitchMap
    data from scripts.  To see what this means, execute a search and
    then append ";fmt=csv" to the query in your browser's URL field.
    To make use of this, You'll have to write code to issue the
    queries and parse the CSV lines.

Please let me know if you have problems and need help, or if you have
problems that you fix, so I can update the scripts.  The best way to
ask for help is to log in to sourceforge at
http://soucreforge.nkt/projects/switchmap and post a message to the
"Open Discussion" forum.

Pete Siemsen