• NAME
• SYNOPSIS
• DESCRIPTION
• EXAMPLES
• NOTES
• BUGS
• AUTHOR
• SEE ALSO

NAME

stpgraph - a grapher for ethernetworks utilizing the spanning tree protocol

SYNOPSIS

   stpgraph [ -hvV ] [-c string] [ <-s filename> [-b filename] [-p n|-P] | <-r> ] [-g type [-W width] [-H height] [<-u|U> [-O] [-X regexp]] args [...]

DESCRIPTION

stpgraph is a tool used to discover and graph ethernet spanning-tree topologies.

Usually this is a two-step process:

1. )
   
Discover the spanning-tree information for your switches, and store the information to files using the -s option.
2. )
   
Graph the information as a directed graph using the -g option.

The resulting graphs have these characteristics (parenthesized terms are graph-theory/graphviz terminology):

The bridges (nodes) are grouped (clustered) in boxes labeled by building name, room number, and topological role.
The root bridge (node) is shown as a rectangle (box).
Other bridges (nodes) are shown as an ellipse.
Bridges (nodes) named (labeled) ``unknown'' are bridges that were not polled directly but, instead, were discovered based on the STP info from an adjacent bridge.
Lines (edges) are directed toward the root bridge. The end of the line marked with a diamond is that toward the root.
Solid lines (edges) are links that are in forwarding state.
Dashed lines (edges) are links that are in blocking state.
Dotted lines (edges) are links that are in other states (rare).

stpgraph has the following options:

-h

shows usage information

mnemonic: 'h'elp

-v

show status/warning messages including SNMP_util warnings

mnemonic: 'v'erbose

-V

show status/warning messages including SNMP_util and SNMP_Session warnings

mnemonic: 'V'ery verbose

-c string

use the specified value as the SNMP read community string

mnemonic: 'c'ommunity

-g type

generate 'g'raph of specified output type: ps, png, fig

mnemonic: 'g'raph type

-W width

mnemonic: 'W'idth

when generating a graph, use the specified value as the graph width, in pages

-H height

when generating a graph, use the specified value as the graph height, in pages

mnemonic: 'H'eight

-u

when generating a graph, graph unknown nodes nodes connected to ports that have dot1dStpPort info

mnemonic: 'u'nknown

-U

when generating a graph, graph all unknown nodes

mnemonic: all 'U'nknown

-O

when generating a graph, graph unknown nodes even if the known port to which they are connected had an ifOperStatus that indicated that the port was not up

mnemonic: if'O'perStatus

-X regexp

when generating a graph with unknown nodes, exclude unknown nodes connected to nodes with names matching this perl regexp

mnemonic: e'X'clude

-s filename

store stp info as a Storable object in filename (%s in filename will be replaced by bridge arg)

With this option, args should be the bridge names or IP addresses.

mnemonic: 's'tore

-p n

when discovering and storing, parallelize the polling and storage by forking multiple processes, limited to n concurrent processes, to speed up collection phase

mnemonic: 'p'arallelize

-P

Like ``-p'', but do not restrict the number of concurrent processes

mnemonic: 'P'arallelize

-r

retrieve spanning-tree info from arguments, which should be the names of files created previously using using -s (store).

mnemonic: 'r'etrieve

-b filename

preload bridge (MAC) addresses from the specified file

This option is especially useful when some of the nodes are Cisco Catalyst 4000 series switches running IOS, which has a bug which causes them to report an incorrect dot1dBaseBridgeAddress when queried via SNMP.

Instead, you can use the ``show spanning-tree [vlan n]'' command to determine the correct bridge address.

mnemonic: 'b'ridge addresses

EXAMPLES

Discover the spanning-tree information for vlan 1 (using Cisco's vlan-based community string indexing with per-VLAN spanning tree), and store the information as Storable objects in files with names with the suffix ``_stp1.obj'' corresponding to each host:

   $ stpgraph -c public@1 -s %s_stp1.obj host1 host2 host3

Graph the spanning-tree for vlan 1, based on the information discovered and stored previously, to a PostScript output file:

   $ stpgraph -g ps -r host[123]_stp1.obj > stp1.ps

Graph the spanning-tree for vlan 1, based on the information discovered and stored previously, to an xfig output file:

   $ stpgraph -g fig -r host[123]_stp1.obj > stp1.fig

Graph the spanning-tree for vlan 1 showing unknown nodes, unless they would be linked to a node with a name ending in ``-access'':

   $ stpgraph -g ps -u -X access -r host[123]_stp1.obj > stp1.ps

NOTES

This Cisco Catalyst 4000 series switches running IOS (as of 12.1(20)EW1) have a bug which causes them to report an incorrect bridge address when queried via SNMP.

Instead, you can use the ``show spanning-tree [vlan n]'' command to determine the correct bridge address and use the -b option to cause the correct bridge addresses to be preloaded, rather than discovered via SNMP.

The SNMP MIB object definitions used by stpgraph can be found in these files:

    ftp://ftp.cisco.com/pub/mibs/v1/BRIDGE-MIB.my
    ftp://ftp.cisco.com/pub/mibs/oid/BRIDGE-MIB.oid

    ftp://ftp.cisco.com/pub/mibs/v2/IF-MIB.my
    ftp://ftp.cisco.com/pub/mibs/oid/IF-MIB.oid

stpgraph uses only the IEEE 802.1d spanning-tree information and should not require a modern implementation such as as 802.1w (Rapid Reconfiguration). However, stpgraph has been demonstrated to work using dot1q vlans on Cisco gear running Cisco's PVST+ or PVRST+ (Per-Vlan [Rapid] Spanning Tree) because Cisco uses a clever tecnique of using the SNMP community string as an index (by appending an ``@n'' suffix, where `n' is the desired dot1q vlan number) enabling the user to select which vlan's bridge objects will be accessed. Community Strings Indexing is supported on a number of Cisco products including the Catalyst 3550, 5000, and 6000 as documented here:

   ftp://ftp.cisco.com/pub/mibs/supportlists/wsc5000/wsc5000-communityIndexing.html
   ftp://ftp.cisco.com/pub/mibs/supportlists/wsc6000/wsc6000-communityIndexing.html

BUGS

To be determined...

AUTHOR

Dave Plonka <plonka@doit.wisc.edu>

Copyright (C) 2004, 2005 Dave Plonka. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

SEE ALSO

perl(1), SNMP_Session, SNMP_util, GraphViz, Storable, Data::Dumper.