STOP PRESS

The patch on this page will not currently apply to the Netdisco upstream source, for two reasons:

1. The Netdisco development team are close to releasing version 1.0 and there are so many changes occurring that it's very difficult to keep this patch up to date.
2. However... I'm working on a complete replacement for this patch, which will be a standalone CPAN module. There are many benefits to this, not least that the module can be upgraded independently of Netdisco, but also that other projects can hopefully make use of the same image generation system. To be informed when I release the new module (and I'm about half done so far), please subscribe to the Netdisco users mailing list.
   

---

Installation

This guide hopefully covers everything. Note that if you run a split frontend/backend, this is all frontend work, on your web server. Please email me if you find any gotchas!

Perl Library Requirements

Please install the following Perl libraries on your web server:

• Imager
• XML::LibXML
• XML::LibXSLT

Imager is a replacement for GD in Peter's original patch. I found it to be much better for manipulating images, as things rapidly get complicated once you have chassis and line cards, and rotation and transparency to deal with. The XML libraries are good, solid Perl interfaces to the well-known GNOME C libraries. The XML modules have their own dependencies (other Perl and C libraries), but I expect you can find them in your operating system. Let me know if you have trouble.

Patch Netdisco Source

My patch works against the latest Netdisco code which lives in the project's CVS repository. At the bottom of this guide I'll talk about my own Debian packages, but otherwise for now we'll assume you are working from CVS source. Begin by downloading Netdisco:

cvs -d:pserver:anonymous@netdisco.cvs.sourceforge.net:/cvsroot/netdisco login
# press return when you are asked for a password
cvs -z3 -d:pserver:anonymous@netdisco.cvs.sourceforge.net:/cvsroot/netdisco co -P netdisco


Now you can install this copy of Netdisco just as you would have done before, without the patch. It'll run in exactly the same way, until we switch on the Frontpanel II bells and whistles.

BUG: The patch does fully apply, but with some hunk offsets. That's because we maintain lots of local patches to Netdisco. If this causes you trouble, please let me know and I'll make a clean patch.

Add the XML Resources

The patch to source isn't quite all you'll need to download. There's a bunch of XML files which tell Netdisco what your devices look like. These are maintained separately to the patch, so that you can edit the files more easily and add descriptions of new hardware.

Later on we're going to configure Netdisco to look for these XML files, so let's begin by downloading them to a location which is readable by both the netdisco user and your web server. On my system, I've used the directory below, but you can of course change it to anything else:

mkdir -p /usr/share/netdisco/frontpanel/xml
cd /usr/share/netdisco/frontpanel/xml
while read URL; do wget $URL; done
https://svn.oucs.ox.ac.uk/people/oliver/pub/entity-mib/trunk/chassis.xml
https://svn.oucs.ox.ac.uk/people/oliver/pub/entity-mib/trunk/module.xml
https://svn.oucs.ox.ac.uk/people/oliver/pub/entity-mib/trunk/port.xml
https://svn.oucs.ox.ac.uk/people/oliver/pub/entity-mib/trunk/entity.xsl
https://svn.oucs.ox.ac.uk/people/oliver/pub/entity-mib/trunk/macro.xsl
https://svn.oucs.ox.ac.uk/people/oliver/pub/entity-mib/trunk/device-spec2perl.xsl
https://svn.oucs.ox.ac.uk/people/oliver/pub/entity-mib/trunk/port-image2perl.xsl

# press control+d on your keyboard

Add the Device Image Files

The frontpanel system uses a number of image files to build up a full frontpanel picture. These images are supplied by the hardware manufacturer (e.g. Cisco) to licensed customers, so neither the Netdisco team nor I can provide you with them.

Having said that, so long as you can get a software image file for your device, you're probably okay. Most images ship with a web device manager which is bundled into the software image, and this will include the files you need. The situation is slightly different for chassis-based devices, but even then there is usually management software to download which includes the images (e.g. CiscoView from Cisco). Usually you'll want to select something mentioning a web device manager, and then untar that file to extract the images contained within.

Because of this, we're not able to go through a detailed example here, but there is one essential step you need to take. The images need to be in a directory which is readable by your web server, and adjacent to the XML file location from the previous step:

mkdir /usr/share/netdisco/frontpanel/images

(Optional) Download Javascript Libraries

Peter's original frontpanel patch had some really cool tooltip-style popups for each port on the device, and this feature has not gone away. You'll need to download Erik Bosrup's overLIB Javascript library and install the mini version of it in a suitable location on your web server. Your server will be asked for files with no leading path part, like so:

<script type="text/javascript" src="overlib_mini.js"><!-- overLIB (c) Erik Bosrup --></script>

(Optional) Download Additional Stylesheets

Later on we're going to look at how to debug Frontpanel II when it isn't drawing your devices properly. To do that, there is a debug web page, and it's really much more usable if you throw a couple of additional stylesheets onto your web server. These are the mktree stylesheets (and Javascript) from Matt Kruse. Like the Javascript libraries these need to be placed somewhere on your web server, although the requested files this time have a /netdisco at the beginning:

<LINK REL="stylesheet" HREF="/netdisco/mktree.css"TYPE="text/css" MEDIA="screen">
<SCRIPT TYPE="text/javascript" SRC="/netdisco/mktree.js"><!-- mktree by Matt Kruse --></SCRIPT>

Er, at some point I might patch netdisco to make these paths configurable. For now, you need to edit the Netdisco autohandler file on your web server to change them.

Configure Netdisco for Frontpanel II

Okay, finally you can add some configuration to Netdisco. Note that if you run a split frontend/backend, this is all frontend work, on your web server. There are three configuration settings for netdisco.conf:

fp_enabled = true
fp_dir     = /usr/share/netdisco/frontpanel
fp_overlib = true

The first and last of these merely enable the Frontpanel II feature, and the tooltip feature, resepectively. The second setting is the location of your XML and image files, which you set earlier. As you can see it's the parent directory of both the XML and image directories.

Prime the Device Spec Cache

One feature of Frontpanel II is that it caches specifications of your device configuration so that the image rendering is a bit quicker and simpler. For example, if you have SFP slots (slots for interchangeable port modules), you might change them from LC fibre to RJ45 copper SFP modules from one day to the next. The cache is populated after Netdisco polls your devices for their configuration, which usually happens overnight. The web frontend of Frontpanel II reads the cache and creates an image.

First you need to create a directory for the cache, which should be writeable by the netdisco user, and readable by your web server:

mkdir /usr/share/netdisco/frontpanel/data

As you can see, this follows our predictable directory naming scheme, and has the same prefix as the fp_dir configuration setting. The next step is to run Netdisco at the command line to populate the cache. Run this as the netdisco user:

netdisco -f

I recommend adding this command as a cron job on your web server, scheduled shortly after Netdisco itself updates; that way all the images will be up to date with your device hardware configurations.

BUG: You might spot that the help text for netdisco mentions that this -f flag takes a device name as an argument. It doesn't, sorry.

Check Device Frontpanels

Now everything should be ready for you to go and look at Netdisco to enjoy beautiful frontpanel images. Your network ops team will love you!

If it hasn't quite worked out, and the frontpanels are missing or wrong, then read on.

---

Configuration and Maintenance

The current distribution of Frontpanel II knows about a few Cisco switches of varying types. If you have the images in place on your web server, there's a good chance you'll get some kind of frontpanel display straight away. However as device software gets updated, and new devices are installed, Frontpanel II will need to know about them. This section explains how this is all done.

Updating XML Resources

The first thing to do is to make sure you have the most up to date device specs. This is simply done by downloading three files, as you did during the installation:

cd /usr/share/netdisco/frontpanel/xml
while read URL; do wget $URL; done
https://svn.oucs.ox.ac.uk/people/oliver/pub/entity-mib/trunk/chassis.xml
https://svn.oucs.ox.ac.uk/people/oliver/pub/entity-mib/trunk/module.xml
https://svn.oucs.ox.ac.uk/people/oliver/pub/entity-mib/trunk/port.xml

# press control+d on your keyboard

Understanding Device XML Specifications

A little bit of background and history is required, here. Netdisco, during its overnight updating process, gathers information via SNMP from the device. One area of information recovered is the ENTITY-MIB, which is described in RFC 2737, and is a logical description of the physical set-up of your device. The description has some standardized names for components:

• Stack
• Chassis
• Container
• Module
• Port
  

All devices can be described using a tree of these components, and that's what's stored in the Netdisco database. The components have code names; for example a 100Mbit fibre port and a Gigabit copper port will have different code names, but are both ports. All this allows us to start with generic descriptions of the component parts of a device, and then when we look in Netdisco's database, all the pieces can be put together to build a frontpanel image with the right combination of ports, containers, and so on.

The three XML files contain generic descriptions of each component which we know about. The 100Mbit fibre port will have an entry in the port.xml file, typically mentioning just the image file used to represent it on a frontpanel. When this port is mentioned in Netdsco's database, Frontpanel II will know which image to use to represent the port. Other parts are more complex; for instance the the chassis represents a particular model of device, and tells Frontpanel II where the other components such as ports and containers (e.g. SFP slots) are placed. The chassis.xml and module.xml files describe x and y co-ordinates, rotation, and other aspects of these components.

At this point let's take a look at the component tree for one of your own devices. Visit your Netdisco site, and select a device from your inventory (try not to pick one that is too large). When you are looking at the page for that device, the URL will contain device.html. Click on your browser location bar and change this to be device_module.html, and reload. The page you see might have a tree of components displayed, or you might need to click on the Expand All link to show the tree.

The first word of each line in the tree is the component type, and the value in round brackets (e.g. cevPortNIC100) is the code name for that particular component. As you can see, everything has a different code name, and we need to make sure the XML files know about (pretty much) each one of them. If Frontpanel II cannot find the component in its XML database, it can't draw an image for it! Let's look at each component type in turn, and see how we represent them in the XML files.

Stack

The stack component (e.g. cevStackCat37xx) doesn't need an entry in the XML database, as it's a logical component which Frontpanel II just uses to let it know there are multiple devices to be drawn.

Chassis

The chassis component (e.g. cevChassisCat375024) does need to appear in the XML database, as it tells Frontpanel II which image forms the main background for the device. An entry must go into the chassis.xml file, and here is one example:

<!-- a Cisco 3750 with 24 10/100 ports and two SFP slots -->
<chassis type="cevChassisCat375024" image="c375024_2.gif">
    <portGroup type="cevPortNIC100"
    x="110" y="25"
    xStep="20" yStep="16"
    width="6" height="2"
    countDirection="down"/>

    <portGroup type="cevPortNIC100"
    x="259" y="25"
    xStep="20" yStep="16"
    width="6" height="2"
    countDirection="down"/>

    <container type="cevContainerSFP" x="469" y="39"/>
    <container type="cevContainerSFP" x="533" y="39"/>
</chassis>

The chassis description starts with a type, which matches the code name you saw in the tree on the web page. Next is an attribute that says which image file to use for the component. If you find a device is not being drawn at all on screen, but the descriptions are all present in the XML files, then you might be missing the image files. Frontpanel II will place an HTML comment in the web page if it can't find the chassis image file (although it doesn't warn about any other component type).

If you've ever seen one of these 24 port switches, you'll know that the ports are split into two groups of 12, and that the port numbers count up from left to right, with odd numbers on the top row and even numbers on the bottom row. This is all described in the portGroup element, which is a convenience to save having to write out (and calculate the layout of) 12 separate port elements. The ports in a port group must all be of the same type, of course! The type attribute tells Frontpanel II which port to look up in port.xml, to find the image to draw. The width and height attributes say how large this port group is (6 x 2 = 12 ports, in a bunch which is six wide and two high). The x and y attributes say where the top left of the port group is in pixels, relative to the top left of the chassis image itself, and the xStep and yStep describe the spacing between the top left corner of each port in the port group, in pixels. Finally, the countDirection attribute is a hint to Frontpanel II as to whether the counting of the ports increases with the width of the group (across) or the height (down) first, before continuing with the other dimension. Right to left or bottom to top counting of ports can be achieved by using a negative value for xStep or yStep.

With this set of attributes, I believe you can describe (almost) any group of ports, with any orientation and count direction. Please let me know if you get stuck!

As well as fixed ports, devices often contain slots for pluggable modular ports (SFP, XFP, and so on). These use the container element, which simply says where the slot is located on the chassis (in pixels from the top left of the chassis image). When a container is empty, that's not a problem; Frontpanel II will discover this from the Netdisco database. Most chassis images have on them a representation of the empty container (e.g. an empty SFP slot) so things 'look right'. Some however, don't, so it's a good idea to use the type attribute and mention the container type. Frontpanel II will then draw an image for the container, just in case; this is described in more detail in the Port section, below. On slot-based based devices, a container might be a line card, rather than merely a port; this doesn't change the chassis description, and we'll come back to modular chassis in the Module section, below.

One additional attribute not featured in this example is rotate. This simply specifies a clockwise rotation in degrees for the image file stored on disk, and can be set to 90, 180, or 270. It's most commonly used in slot-based chassis to rotate containers, such as the Cisco 6500 and 7600 series which take the same line cards in varying orientations, depending on which chassis you have. Both port and container elements, as well as their group siblings, may have a rotation.

There also exists a port element, and a containerGroup element. These follow exactly the same style as their sibling elements in the example above, except for the difference in attributes used. You'll see examples of these in the sections below. We could have represented the two containers in the example above with one container group, but that would probably have been a little excessive. Likewise each of the port groups could have been 12 separate port elements.

Container

The container component (e.g. cevContainerSFP) doesn't need an entry in the XML database, as it's a slot into which something more useful gets put. It does crop up in the port.xml file, though, but that will be covered in the Port section, below.

Module

Experience so far suggests modules turn out to be line cards in slot-based chassis devices. The way to think about a module is that from the perspective of Frontpanel II it's really a kind of chassis-lite - it has ports and containers just like a fixed chassis. In fact the XML description of a module in the module.xml file is exactly the same as for a chassis in chassis.xml, except the outer element is called module rather than chassis.

Sometimes, though, there will be a module in the device component tree (remember, the tree from device_module.html) which doesn't need to be mentioned in module.xml. These modules appear in fixed-chassis devices such as the 24 port switch used in the example previously. The trick to identifying them is that these modules don't sit within a container; sometimes they mention 'Fixed' in the description too, e.g. "WS-C3750G-24TS - Fixed Module 0 (cevModuleCat375024TS)". You can ignore such modules, they'll be skipped as 'dummies' by Frontpanel II.

Port

Whilst the port descriptions, which all live in the port.xml file, are simple in themselves, sadly the manufacturers have made a dog's breakfast of their SNMP reports from devices. What this boils down to is that whilst you think that a port ought to be reported as "cevPort100BaseFX" in fact it might get the code "cevPortFe" or even "cevPort.123" (I'm not kidding!). It appears to be something which gets fixed as manufacturers release new software versions for the device. Anyway, Frontpanel II has a simple system for working around these mistakes, which we'll see below.

Your basic port identifier in port.xml looks like this:

<!-- 10/100/1000 RJ45 port -->
<port-image type="cevPortBaseTEther">
    <up>green.gif</up>
    <down>gray.gif</down>
</port-image>

As you can see, Frontpanel II is using this information to select image files when the port code appears in a module or chassis description. The port state comes from the Netdisco database, so one of the images in the up and down elements will be selected as appropriate. Note that because, by default, Netdisco only polls port state once a day, this is not a reflection of the port's current state on the device.

In the Container section, above, I mentioned that you'll sometimes want to have Frontpanel II draw the image for an empty container if it's missing from the chassis image. In this case you would create a port-image element as in the example above, with the type attribute set to the container's code. Instead of using up or down inner element, use an element called empty to specify the image to be used.

When you're getting the 'wrong' description code for a port, just add another port to the XML file with the same details but a different value for the type attribute's value. Frontpanel II will pick the right one. However your chassis or module spec will also probably be incorrect, so you'll need to double up the port or port group element in that, adding another for the rogue description code you're receiving. Frontpanel II will ignore port and port group elements in a chassis or module which are missing from the device component tree in the Netdisco database.

Even then, sometimes this simple trick isn't going to work. We've seen devices which report LC connector fibre ports as 1000BASE-T (copper) ports. In this case you can't have a port-image for the 1000BASE-T port using the LC connector's image, because all your real 1000BASE-T ports will then be using the wrong image! Okay, don't panic, there is a feature in Frontpanel II to deal with this. The problem crops up usually on one particular type of device, so when specifying the type attribute in a port-image, you have the option to qualify it with the chassis or module and/or container code. The format is quite simple: separate the codes by the underscore character. Here are some examples:

<!-- 1Gig fibre port in an SFP slot in a WS-C3750G-12S -->
<port-image type="cevChassisCat3750Ge12Sfp_cevPortBaseTEther"> ...

<!-- Empty GBIC slot in 6500 chassis 8xGBIC line card -->
<port-image type="cevCat6kWsx6408aGbic_cevContainerGbic"> ...

<!-- 1Gig fibre GBIC module in 6500 chassis 8xGBIC line card -->
<port-image type="cevCat6kWsx6408aGbic_cevPortGigBaseSX"> ...

<!-- 1Gig fibre SFP module in early software releases -->
<port-image type="cevContainerGbic_cevPortUnknown"> ...

You can see from these examples that sometimes it's useful to specify the port code relative to its container, and other times relative to the module (line card) or chassis. The port.xml file has a comment in which explains the valid combinations.

Validating your XML

It's possible to have your XML files validated, which will check for certain common errors in syntax. A RELAX-NG (compact) schema is available at the link below, and you can use the trang and xmllint tools to validate it. The minimum you should expect is that xmllint says your XML files are parsable (it echoes them out), and at best you can get it to use the RELAX-NG schema for a more complete validation.

https://svn.oucs.ox.ac.uk/people/oliver/pub/entity-mib/trunk/entity-render.rnc

Putting it all together

The best thing to do at this point, if you haven't done so already, is to read through the three XML files on your filesystem. All the features mentioned above appear in the current versions of the files.

Once you have edited any of the XML files, you'll need to instruct Netdisco to refresh its cache of device specifications. This is an off-line process; it doesn't involve any SNMP, only database access. Run this command as the netdisco user:

netdisco -f

---

Debian Packages

I'm the maintainer of Debian's Netdisco packages. Of course those packages are tracking stable releases and not the latest code in CVS, however you can rebuild the packages from source. If you add the Frontpanel II patch to the debian/patches/ folder, and add its name to the debian/patches/00list file, when you rebuild the package it will incorporate the Frontpanel II patch. You can also see all our local patches, and a version of the Debian package for Netdisco which already incorporates them, here:

https://svn.oucs.ox.ac.uk/people/oliver/pub/netdisco/branches/oxford-patches/

---

Conclusion

Firstly, thanks for taking the time to read this documentation, and thanks to Peter Ehlin for his original patch which showed how most of this could be done. Undoubtedly there are bugs lurking in this system; I'm no XML expert, and I've only been able to write this solution based on our own experiences and our own devices. No doubt yours will be different, so please do let me know if something isn't working, and I'll do my best to help you out.