Interface descriptions – your last hope

Interface descriptions – your last hope

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.


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.

4 thoughts on “Interface descriptions – your last hope

  1. Was excited to see a new story pop up in my RSS feed. Descriptions + LLDP info is a good general sanity check. It also isn’t too terribly difficult to put together a python module to compare the two automagically and report differences.
    If your configs are programmatically generated, then the descriptions can be part of the offline documentation too, in the config repo.
    When I see up interfaces without descriptions, a part of me dies inside.

    1. Hey Peter,
      I agree on the lack of descriptions, but the lack of descriptions for stuff that can’t be derived from LLDP/CDP or even MAC-endpoint comparison gets me most.
      The concept of adding interface descriptions into the authoritative Config repo is a good one, but worth some debate. I have an idea for a blog post to discuss this. For example if you have a separate tool to do interface descriptions then you have essentially two masters. Same with COPP policy, password rotations etc.
      Feature or business-function focussed tools provide flexibility but create a many-masters situation. Pushing everything thought a central repo and deployment system is great, but it requires either a mature CI system, or a means of preventing one tool pushing a small change (e.g. Interface description) to the config repo, and accidentally pushing a large change (interface description plus un-deployed routing policy change) to the network device. Definitely need to do a post on this, but would love your thoughts.
      P.S. I sorted the triple post-issue. Not sure what the story was there.

      1. 🙂
        I actually meant to refer to the backup configs. Which I like to have in a repo, so that you get the versioning.
        How to generate configs is a whole other ball of shit

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.