Listen, Subscribe & Follow:
A favorite topic among network engineers, documentation is a source of both wonder and horror. Network documentation is difficult to get right. How much detail is enough? How old is that diagram, really? Can’t this be automated? Wait, the automated generator spit out *that*?
In this show, the Packet Pushers along with former guest Dominik discuss their documentation experiences, good and bad. What have we gotten right? What have we gotten wrong? What’s been worth the trouble? What was a waste of time? What did we wish we’d documented before we really needed it?
Introductory Chat
- Why it is a good idea to have a proper documentation.
- Who are you documenting for? Each audience results in different documentation.
- For yourself more than anyone else. Perhaps also the person that comes after you.
- Other IT teams to fit into system and application architecture diagrams.
- 3rd parties who require technical comprehension to integrate (may require scrubbing).
- End customers (people consuming your network).
- What should be documented.
- Main / HQ network
- Closets
- Think “middle – out”
- Include all transit devices. If packets flow through it (i.e. not an endpoint), then it’s part of the network.
- Nice to have, hard to maintain.
- VLAN lists
- Subnet descriptions
- Remote sites
- B2B connections
- DMZ / proxy architectures (can be complex)
- Templated/standard configurations
- Unusual configurations that solve a specific problem
- Main / HQ network
Concepts
- High Level Documentation — includes all general information applied to all gear
- Don’t include too much detail in a high level diagram
- You want a general idea of all sites, major network ingress/egress points, and interconnections
- Low Level Documentation — includes all the specific details
- Vendor specific
- Location/site specific
- Network specific
Documentation Toolbox
- Self-documentation
- Interface descriptions
- Appropriately named objects
- Junos allows for embedded comments
- Vector graphic diagram applications
- Visio
- Working with Layers in Visio
- Omnigraffle
- Scapple
- http://draw.io
- Visio
- Cable Management Tools
- Every cable with a special number, referenced in a central tool.
- Vinyl-wrapped cable labels
- Fiber Mountain’s unique approach
- Rack Management Tools
- RackTables
- Kuwaiba (open source Network Inventory System)
- RackView
- APC InfrastruXure Manager
- Knowledge Database / Wiki
- IPAM IP Address Management
- phpipam
- NIPAP
- Infoblox
- 6connect
- Configuration backup
- Rancid
- Oxidized
- SolarWinds NCM
Interactive Tools
- NetBrain
- NagVis
Links
- http://ethancbanks.com/2013/12/29/new-years-thoughts-start-with-documentation/
- http://networkautobahn.com/2015/03/11/documentation-needed/
- https://packetpushers.net/how-to-draw-clear-l3-logical-network-diagrams/
- http://racktables.org/
- http://kuwaiba.neotropic.co/get-started/
- http://phpipam.net/
- http://spritelink.github.io/NIPAP/
- http://www.nagvis.org/
Share this episode
“The Noc Project” has a very good IPAM:
https://kb.nocproject.org/pages/viewpage.action?pageId=1507406
We’re currently evaluating Efficient IP SOLIDServer for DDI. At first glance, the UI isn’t as sexy as Infoblox, but it’s much quicker to get the data you need — it feels more like a power user’s tool and you get a lot more for the same price.
Custom attributes are also much closer to the core of their IPAM system. DNS entries can be built on the object class attributes. IPs can be auto-assigned within a pool based on object class. The biggest downside we’ve run into during the demo is that it’s more difficult to have multiple views on the same DNS server. So we’re going to spec out different servers for each view, which isn’t a big deal for us and still wound up coming under Infoblox’s price.
Netbrain is really extraordinary. I was recently working in a network with a lot of dark corners (after three years, I was finding new things almost weekly that I had never heard of before) and Netbrain was invaluable there. I put it in place and it quickly became the first place everybody would go to troubleshoot something.
If you have a good documentation practice in your enterprise, it is most probably not necessary. But if you have poor documentation and a lot of dark places… man is it ever useful.
Yeah absolutly agree with you in a network with dark spots in the topology netBrain can help a lot. But even in a good documented network it helps with keeping all the maps up to date wich can be really time consuming when it is done manually.
I want to mention two opensource software that can be really useful, Netdisco and Netdot. They do an SNMP scan and create an inventory on your network and can for example:
– draw L2 diagrams of your network
– basic IPAM functionality
– track where mac-address X was last seen
– list all devices with software X on them
Check out their homepages for more info.
Just stumbled on this podcast (luckily I have enough traffic jams each day to get some solid listening time in)..
Now I haven’t finished the whole podcast yet but I wanted to point out another reason why documentation is important (you guys came close to it at the start of the show though).
My argument is mostly a financial one (as that seems to trigger management more).
Let’s say we hire a new network guy how much effort (=money) is involved to get them fully up to speed so they can operate independently?
Assuming I have all my documents, visio-diagrams and wiki information (troubleshooting guides, how-to’s etc) it might tike him one or two weeks to read everything and ask the odd question to get things clarified.
Without documentation I’m basically sacrificing an additional employee to help guide the new guy causing an even bigger strain on the already stretched resources (why would I otherwise bring in a new guy)..
And I actually have heard a manager once say “I don’t have the resources to train a new guy to reduce the workload”…
On a side note, Marcus mentioned Netdisco, I’ve worked extensively with this tool at an ISP and can say it is the best discovery/inventory tool I’ve ever worked with (fun thing to do is export the netmap as a SVG which you can import into visio).
The guys involved with the project are usually on IRC and are fast to help out when you have a question (plus it’s completely Open Source).
Good comments on NetDisco – thanks. Always hard to tell which projects get decent support. And as far as documentation to help get the new guy up to speed. Yep! Can’t hurt. One of the networks I took over, the previous caretaker headed out the door before I started. I was handed a pile of diagrams, passwords, SNMP community strings, and that was all I needed to get started. Off I went. Without those diagrams? Ouch.