NetLay: Does the map still tell the truth?

The problem I started with#

Right back at the beginning of this series I said the thing that annoys me about network documentation is that it rots. Somebody moves a printer, nobody updates the drawing, and eighteen months later the drawing is a work of fiction that people still trust.

The importer from last time stops the rot at the moment of import. It does nothing about afterwards.

"I am going to have to manually build these maps until they get back to me, so the reality check is a great idea to bridge the two."

That is the other half, and it turned out to be almost free, because I had already built the hard part.

The same parser, asking a different question.#

The reality check takes exactly the same pasted output and builds exactly the same plan the importer would build. Then, instead of offering to apply it, it compares that plan with the switch already on your map and reports the differences.

That is the whole idea. One parser, two questions. What should be here, and what is here, and tell me about the gap.

Nothing is written unless you accept a specific fix. If the switch is not on the map at all then there is exactly one finding, which is that you should import it.

What drift actually looks like.#

The list of findings is a decent summary of all the ways documentation goes wrong.

A device has moved, which it knows because the MAC address it learned on port nine is the one your map has on port four. A device the switch can see that is not on the map at all. A device on the map that the switch has learned nothing about. A device sitting on a port that is administratively shut, which is usually either a decommission nobody finished or a mystery worth chasing. A device with no MAC recorded, so it cannot be checked either way.

Then the port level. A VLAN on the map that does not match the VLAN on the switch. A module that is missing, or smaller than the switch says it is.

Then the links. An uplink the switch reports that your map has not got. An uplink on your map that CDP does not mention. A neighbour switch that is not on this layout yet.

Findings are sorted high, medium and low. The one I want to defend is that "device the switch has not seen" is only low. A device that has not spoken recently is not evidence of anything much. It might be switched off, it might be a printer that sleeps, it might be somebody's laptop at home. Ranking that as urgent would bury the findings that matter under a list of things that are fine.

One click each.#

Every finding carries its own fix, and the fix is always the same shape, which is to accept the switch's version of events.

Import it. Add the module. Set the VLAN to twenty. Add the device. Move it to the port it is actually on. Add the uplink. Record the MAC address. Each one is a tiny plan with that single row ticked, run through the same code path as a normal import, so there is nothing new to go wrong.

While you are in the reality check, the devices involved get a red, amber or grey exclamation badge on the map with the finding as its tooltip, so you can see where your drift is rather than reading a list. They clear when you leave.

What it will not do.#

It can only judge devices if you gave it a MAC table, and only judge uplinks if you gave it CDP output, so the summary line says what was actually checked rather than implying a clean bill of health from a partial paste.

And it trusts the switch. That is a design decision and not always the right answer, because MAC tables hold entries for things that left the building twenty minutes ago, and a switch will cheerfully tell you about a device that has been in a drawer since March. So every finding is a suggestion with a button next to it, and the person decides.

The use I did not expect is the one I now use it for most. I have been building these maps by hand while waiting for exports, and pasting the real output afterwards is the fastest possible way of finding out which bits I got wrong. It has caught me putting a device on the wrong member of a stack more than once, which is precisely the mistake the port naming work from post two was supposed to prevent me making.

Next time, the part of the network that is not in the cabinet or on the desk, the bit of cable in between.

NetLayNetworking