No, I’m not starting a naming war. Not really. I don’t care if you use ! or # or >> or {} to mark your interface descriptions. I don’t care if you use all-caps or lowercase, or if you feel a fundamentalist zeal about other punctuation.
I want to brave the flames of a naming war to propose that we include ‘hidden’ or ‘undiscoverable’ devices in our interface descriptions. If there is a hidden device, a bump in the wire for example, between you and your neighboring network device then you should mention it in the interface description.
Hidden topology & undiscoverable devices
I’ll admit that this isn’t exactly ground breaking news. We’ve always been told to include circuit_id references in our WAN links, and we’ve done an okay-ish job of keeping WAN interface descriptions up to date.
However, in an ethernet-everything world, it’s hard to know just what is or isn’t a WAN link. WAN links aren’t the only booby-trapped part of the network either. I’ve added a few other examples of hidden topology elements below:
- Inline optical taps
- Inline Layer-1 switches
- Bump-in-the-wire firewalls
- MPLS PseudoWires
- DWDM Circuits
- Media Converters
- L2 Protocol Tunneling on L2 Switches
Why does it matter?
All of these hidden elements are potential land mines, and subject to failure. If you don’t know they exist you will spend hours troubleshooting links, sending datacenter techs tracing cables and confusing yourself and many others. Oh the laughs you’ll have. These devices are really hard, if not impossible, to detect from your known network devices. Most do not have a MAC layer and those that do are purposefully trying to hide it from you.
The transparency of these devices is their killer feature but also their achilles heel. You can’t regenerate this information or auto-discover it from the CLI after the fact. If you don’t record this information when the link goes into service, then you’ll need to rely on tribal knowledge or a cable-tracing party to gather that intelligence later.
Summary
You absolutely should have documentation that exists outside of network configuration. However when a Sev-1 is in full flight, I sure do appreciate a good interface description pointing out that there is a media converter or other hidden node in the path I’m troubleshooting.