The grammar understood by the parser looks something like this:

/* here is a comment */
/* here is 
   a multiline
   comment */
map $MAPNAME {
    image $IMAGE_PATHNAME;
    node $NODENAME {
	map $NESTED_MAP_NAME {
	    ...
	};

	x $X_COORD;
	y $Y_COORD;
	hide;
	terminal;
    };

    link $LINKNAME {
	between $NODE1 $NODE2 ... $NODEx;
	thickness $THICKNESS;
	shaded;
	bandwidth $BW;
	ping $IP from $EPNAME;
	url $URL;
	endpoint $EPNAME {
	    location $NODENAME;
	    host $HOSTNAME;
	    interface $INTERFACE_NAME;
	    snmp community $COMMUNITY;
	};
    };
};

Blocks have names. All the names exist in the same namespace (so you can't call a link, map or endpoint sfo_sprint if you've already created a node called sfo_sprint). Names can contain any alphanumeric character and most punctuation symbols (so bdr1.NewYork:Gig0/3 is an appropriate name for a link). Names can't contain semicolon, space or comment characters.

Each map should have an image keyword (followed by the pathname to the base image which the map will be drawn on - Must be a GIF file. No quotation marks), zero or more nodes, and zero or more links.

If the hide attribute is applied to a node, the node won't appear on the map but can still be used as a "waypoint" for a multinode link. This can be used to cause multiple links between the same pair of nodes to follow different paths so they don't get drawn on top of each other. You can also put "hidden" nodes on street corners and road crossings on maps if you want to draw fibre paths along the line of their physical installation, rather than "as the crow flies" between their source and destination nodes.

If the terminal attribute is applied to a node, the node is drawn as a small dot. This is usually used to indicate that the presence of the node on the map isn't supposed to be indicative of its geographical location. E.g., peering links radiating out from a POP will be 25 - 50 pixels away from the POP, but that doesn't mean they're physically located on adjoining road intersections, buildings, etc. Making the dots smaller provides a visual cue to the fact that the nodes are only being drawn so that their links can be shown on the map, not to indicate their locations.

Nodes which are terminal and hidden aren't shown at all.

A node can have zero or more maps nested within.

Each link has a between keyword which describes the nodes which the link should pass through from start to finish. At least two nodes must be specified.

A link can have a thickness keyword, followed by a number or the keywords thin, medium, thick or obese. If you've provided a number then nodemap will use it to define the pixel-width of the brush used to draw the link. thin to obese mean 1 to 4 pixels respectively.

A link can also be shaded. That causes nodemap to draw it with a dashed line (perhaps to indicate a backup link? nodemap doesn't care, it's up to you). thickness and shaded can be used together.

update_stats will run snmp_show_int against router $HOST to obtain link utilization, description, and state information. The output is similar to the IOS exec "show interface" command, with the values obtained via SNMP.

update_pktloss will run "ping" commands (via rsh or ssh) on the specified host with the source interface set to whatever is defined in the endpoint.

Each endpoint has a location. The location must be one of the nodes listed in the enclosing link's between statement.

An endpoint can optionally have an snmp_community and/or an snmp_version. If you don't specify an snmp_community nodemap will use public as its default community. If you don't specify an snmp_version nodemap will use 2c as its default SNMP version. The syntax for SNMP version numbers is any value which is acceptable to Perl's Net::SNMP module.

Example of a link through three nodes with two endpoints:

    link syd_stm1_to_adl {
	ping pos4-1.adelaide.isp.com from sydney:POS4/0;

	between syd
		adl_syd_corner
		adl;

	endpoint sydney:POS4/0 {
	    location syd;
	    host router.sydney.isp.com;
	    interface POS4/0;
	};

	endpoint adelaide:POS4/1 {
	    location adl;
	    host router.adelaide.isp.com;
	    interface POS4/1;
	    snmp_community private;
	    snmp_version 1;
	};
    };

Link states, their corresponding colors, and the conditions which cause them to occur are listed below:

There is a priority order associated with some of these: "indeterminate" is overridden by "lossy". "loaded", "busy" and "lossy" are overridden by "down".

Color is also used on nodes as well as links. Nodes are normally blue, but if they contain nested maps they will be colored according to the links contained within, according to the same priority order described above. So a node will be green, unless there is at least one yellow, red, bright red, magenta or grey link inside one its nested maps (or inside one of their nested maps, etc), in which case the color of the node will reflect the color of the offending link(s).

The user interface takes a bit of getting used to. Each HTML page generated by nodemap consists of a title, an image, an image map and a set of "DIV" blocks with their visibility attribute set to hidden. The image is generated by drawing nodes and links on top of the GIF file described in the image keyword in the map definition.

As you move the mouse over the image, pop-up boxes will appear to describe the various elements that you "hover" over.

Hovering over a link will open a popup containing the link name, its status ("ok", "loaded", "busy", "indeterminate", "down", "lossy"), its bandwidth (in Mbps), the percentage of load which was on the link when update_stats last sampled it, the RTT of packets over the link (if the link definition includes a ping keyword), the percentage of packet loss (if the link definition includes a ping keyword and the packet loss is greater than 0%), and the line protocol state of each endpoint ("up", "down" or empty for indeterminate endpoints).

Hovering over a node will open a popup containing the node name. If the node has any nested maps, there wil be hyperlinks to those maps in the popup box. To click the links, leave the mouse stationary until the outline of the popup box turns into a dotted line (to indicate that it won't disappear when you move the mouse off its node) then click the link. If you want to dismiss the popup without clicking a link, just click anywhere else in the popup.

The popups will be transparent if your browser's DOM has alpha channel support, enabling you to see items which would otherwise be obscured behind them.

Note that popups will only "pin" themselves to the map after about 0.75 seconds of hovering, so random mouse movements won't cause them to lock themselves onto the screen.

    nodemap [ -o output-directory ] [ -c mapfile ] [ map ... ]

output-directory specifies where the HTML and GIF files generated by nodemap should be placed. It'll ordinarily be in a webroot somewhere. This directory should be populated with the stylesheets and JavaScript code from the nodemap distribution, otherwise the user interface will fail to work correctly. The output-directory defaults to the current directory.

mapfile is the pathname to the configuration file. If this argument isn't provided, it'll default to etc/nodemap.cf relative to the current directory.

map is the name of the map within the configuration file which you want nodemap to render. If not supplied, this argument will default to main. Multiple maps can be specified, they'll be plotted in sequence.

The scheduler command line looks like this:

    scheduler [-d] [-p] [-c config-file] [-o output-directory] [mapname]

Ordinarily scheduler will disassociate itself from its controlling terminal, turn itself into a daemon, and record its PID in /var/run/nodemap.pid when it is invoked. The -d flag makes it run in the foreground instead with copious debugging output sent to stderr.

The -p flag can be used to turn off scheduler's efforts to contact routers to run packet loss/latency "ping" tests. Use this flag to make it ignore ping tests in etc/nodemap.cf if you haven't enabled rsh/ssh access to your routers.

The -c flag points scheduler at a nodemap.cf file. The default is etc/nodemap.cf relative to the "current" directory.

The -o flag is passed on to nodemap subprocesses by the scheduler, providing a way to specify the location of the output directory for GIF and HTML files generated by nodemap. This directory should be somewhere in your web server's document root heirarchy.

If mapname is specified, all of scheduler's actions will be restricted to things whic affect the named map and any nested maps needed to evaluate the named map.

At runtime, scheduler reads the nodemap config file to obtain lists of links which require ping tests, lists of routers which need their interfaces interrogated for usage stats, and lists of maps which need to be redrawn. It then arranges for each item in those lists to be processed asynchronously by subprocesses randomly distributed over a 5-minute scanning interval.

As scheduler determines that each subprocess is falling due, it determines whether adequate resources are available to reasonably execute the process without bogging-down the system. scheduler currently limits itself to having ten (10) processes executing simultaneously at any given point in time. If a new process is due for execution but starting it would mean more than ten processes would be running, scheduler will delay the new process for a random number of seconds between 0 and 30 to give it another try when the system is less loaded. scheduler records its activity and current number of free process slots in its process name as reported by ps:

    bsdunix# ps ax | grep nodemap
     2651  ??  Ss     0:37.75 nodemap sleeping for 1 seconds with 4 slots (perl)
    91950  p3  S+     0:00.00 grep nodemap
    bsdunix#

Using this strategy, large networks can be polled for statistical data even if the nodemap monitoring station is very busy.

As each process completes, scheduler reschedules it so that it'll be executed up to five minutes later.

There are currently three types of events which scheduler tries to manage:

Event type	Action
update_stats	Each router mentioned as an endpoint in nodemap's config file causes an update_stats event to be inserted into scheduler's event queue. As each of these events falls due, snmp_show_int is used to poll all of the interfaces on that router which nodemap cares about.
update_pktloss	Each link with a ping directive in nodemap's config file causes an update_pktloss event to be inserted into scheduler's event queue. As each of these events falls due, scheduler will fork a subprocess to issue rsh/ssh commands to the "source" router to make it ping the destination.
update_nodemap	Every 120 seconds the scheduler will invoke the nodemap program to redraw your maps.

scheduler is normally started at boot-time by the supplied etc/rc.d/nodemap.sh script (which takes "start", "stop" and "restart" arguments like usual rc.d scripts should).

Command line:

    snmp_show_int -h hostname [-n] [-l] [-v snmp-version] [-c community] [interface-list]

If -l is specified, snmp_show_int will SNMP-query the ifTable on the named host to obtain a list of available interfaces, and dump them to stdout.

If -l is not specified but a list of interfaces is, then each interface is queried and simulated "show interface" output is written into the stats directory in a file called hostname:interface-name, with any "/" charaters in the interface name replaced with "=" signs. Note that the ifTable is only queried once per command-line invocation regardless of how many interfaces are queried, so for efficiency reasons it's better to query multiple interfaces on the same router by running snmp_show_int once with all the interfaces on the same command line than it is to execute snmp_show_int separately for each interface one-at-a-time.

If -n is specified, the output will be sent to stdout instead of the file in the stats/ directory.

snmp-version is the version of the SNMP protocol which should be used to make queries. Any version string supported by the perl Net::SNMP module is supported. Version 2c is the default if this option is unspecified. Note that version 1 will suffer from fairly abysmal performance when querying routers with large numbers of interfaces due to deficiencies in SNMP v1's bulk-transfer queries. Try to use version 2c if you can.

The nodemap config file doesn't provide a way to set the SNMP version used on an endpoint-by-endpoint basis, but such a feature can be trivially added if it's ever required. Cisco devices generally support version 2c anyway.

Errors cause snmp_show_int to silently skip the interface which caused the error and move on to the next interface in the list without updating the stats file. nodemap will eventually determine that the old, unupdated stats file is "stale" and stop using it.

snmp_show_int prefers to query the OLD-CISCO-INTERFACE-MIB, which contains most of the values returned in the output of the "show interface" command in the Cisco IOS EXEC. In particular, the MIB includes locIfInBitsSec and locIfOutBitsSec containing input and output bitrates.

Some interface types don't support the OLD-CISCO-INTERFACE-MIB. When snmp_show_int attempts to query those interfaces, it'll automatically fall-back to the RFC-1213 interfaces MIB. This MIB doesn't have OIDs containing bits/sec and packets/sec rates, so they must be calculated by comparing ifInOctets and ifInUcastPkts (and corresponding output OIDs) with the previous value in the stats/ directory and calculating the rate of change. To assist this calculation, simulated "show interface" output in the stats/ directory contains a "Timestamp:" value which isn't normally present in Cisco output, which snmp_show_int can use to work out the elapsed time between samples when calculating its averages.

ATM interfaces on routers cannot be queried with snmp_show_int, although their PVC subinterfaces can (i.e., you can query ATM2/0.100, but you can't query ATM2/0). In practice this is not expected to present any serious operational issues. If you really need to know the utilization on an ATM bearer circuit, probe the interface on the ATM switch instead of on the router.

Installation

Preparation

freebsd# cd /usr/ports/net/p5-SNMP && make install
freebsd# cd /usr/ports/graphics/p5-GD && make install
freebsd# cd /usr/ports/graphics/p5-GD-TextUtil && make install
freebsd# cd /usr/ports/lang/p5-Expect && make install

There are some issues with GIF support in various versions of GD. If that's a problem, change the $gd->gif() calls to $gd->png() or $gd->jpg(), and the newFromGif() call to something else. I expect that this will be a lot more configurable in future, sorry if it's hacky right now (and anyone who wants to make it configurable is welcome to contribute patches :-)

Once the prerequisites are installed, nodemap can be extracted into its runtime directory. The .tar.gz distribution file contains two subdirectories: webroot and nodemap. Put the nodemap directory wherever your local policy dictates third-party software should go (e.g., /usr/local, /opt, etc -- the location isn't critical. We've assumed it'll end up in /usr/local/nodemap, but you can put it whereever you want).

The webroot directory should be located somewhere in your web server's public webroot. We don't care which web server you use, so this directory will vary from installation to installation. The webroot directory contains the documentation and the runtime CSS and JavaScript needed for the nodemap user-interface. After execution it'll also contain the .gif and .html files which nodemap generates.

Once you've chosen your directories, edit etc/rc.d/nodemap.sh to tell it where the bits will be going. $SOFTWARE and $OUTPUT should reference your installation directory and HTML output directory respectively. Once you've made that change, you can copy etc/rc.d/nodemap.sh to your system's startup directory.

Finally, if you're intending to gather packet loss and latency statistics, you'll need to work out whether you're using ssh or rsh to gather them.

As distributed, nodemap uses ssh, but rsh is probably in wider production throughout the world (most Cisco IOS revisions don't support ssh).

If you're using rsh, you'll need to make a one-line change to update_pktloss.pm -- There are two lines which say:

# uncomment the one you want, comment-out the other one
my $rcmd = "/usr/bin/ssh";    # secure(ish) (default)
#my $rcmd = "/usr/bin/rsh";   # less-secure, but more likely to be enabled

Simply comment-out the first line and uncomment the second line.

Execution