Awesome Conferences

How to maintain network documentation?

How do you keep your network documentation up to date?

(more after the jump)

Dear Tom/Christine/Strata, I have read The Practice of System and Network Administration. I still use it as a reference and find it very useful when training new employees at [my company].

One big problem I still have is network documentation. We use many tools to document our client networks. Some work OK. Some are very cumbersome to use. It is very hard to get techs to document their work and changes. It's even harder when they have 20 different tools to use and they do not know how/can't remember how to use all of them.

We are currently using Word to keep our documentation in. We start off with a template and fill in the fields. This is OK except the template fields change over time and the older network documentation for clients does not get updated with the new fields. Also, the formatting in Word gets all out of sorts and the techs spend a lot of time trying to get the document formatted properly.

I am looking for a web-based, database driven system for network documentation. Ideally, the system would allow me to create database forms/templates to fill in for standards based documentation and allow me to create free-hand documents like a wiki. Then I would like to organize the pages into a book format and print it off. I would also like to be able to search on it too.

Am I asking for too much? Do you know of such a system?

Networked in Texas

Dear Networked,

Thanks for writing! We're glad you enjoy the book enough to share it with new employees.

Having so many tools can be very painful to learn. Any reason to not use a tool is going to be employed, especially if people don't feel the pain when documentation gets out of date. The best inventory/documentation systems feed other systems so that the encouragement to get the database right is that nothing works if they don't :-). For example, having the docs feed the monitoring system (or somehow influence if the payroll system works properly :-) ).

I've seen a number of home-grown systems that maintain databases and present web front-ends. I don't think I've seen commercial or free ones. Though, Brent Chapman has been doing interesting things at Netomata I don't think that's what you are looking for. I know that there is network inventory stuff available for maintaining fiber plants around the world, but I don't think that's useful in this situation. Visio has a network diagram mode that can actually do network discovery. Not sure if that helps.

The home-grown system I use right now uses YAML files that get checked into a source code repository. On check-in we run "make" which builds HTML pages that are diagrams of what various racks contain. We also use pre-submit checks to trigger programs that verify the data is consistant. Sadly updating YAML files requires more technical skill than a web front end.

Rather thank MS-Word, have you considered something that stores the data in a structured format so other systems can process the data? Everyone knows how to edit an Excel spreadsheet. It is easy to write scripts that extract the data to be sent to something that draws the diagrams in HTML.

Rather than expect people to learn many tools often it is better to have a single tool for data input (web form, YAML, Excel, Google Spreadsheets, etc.) and let a Makefile or cron job do the rest of the work. That way they only have to learn one tool but all the ancillary tasks still happen.

I work at Google so if you don't mind me plugging one of our products: Google Spreadsheets has three benefits here: (1) the document is stored online, so there is no confusion from emailing spreadsheets around, (2) multiple people can be editing a spreadsheet at the same time, so there is no locking needed, (3) there is an API that lets you manipulate the spreadsheet form Python or other language, therefore you can extract the data from a script you run to do useful things with the data. The API permits updates, so you could write web front ends (or even shell scripts) that add data to it.

Thanks, Tom

P.S. Ok, blog readers! Do you have a tool or suggestion for this reader! Please post to the comments section with your solutions!

Posted by Tom Limoncelli in Questions from the Readers

6 Comments | Leave a comment

Here at the University of Oregon, we use a home-grown tool called NetDot for network documentation. It has grown into a rather large open source project and has hooks into our DHCP and DNS systems, making configuration and documentation the same thing in some cases. Perhaps it will do what you need.

I'll 2nd That YAML thing. I need to do better @ documenting other details, but our many vhosts are listed in a human-readable YAML document, annotated with comments, and version controlled. I then use this to create configuration files based on templates, but it would be easy to output these things to HTML or some other kind of HTML format when I have to bring someone up to speed quickly.

I'm still investigating other tools (like OCSInventory) for listing physical machine details as well. Our rack is not a complex affair (yet), so simple text lists + wiki pages of where things are help. We do have workstations that ought to be tracked and inventoried too...

The real challenge is to work this documentation into your day-to-day incident tracking and response so when details about these resources change you have the record that needs changing on hand, but more importatnly, you have historical perspective on what was changed and why ...

Thanks, Tom, for the Netomata plug!

Part of my vision for Netomata is to turn the question around... That is, address the question "how do I make my network match my documentation?", rather than the more traditional question of "how do I keep my documentation up to date with my network?"

Basically, I've concluded that it's hopeless to try to document how something is configured, if the configuration can change independently from the documentation. To keep things in sync, you either need to derive the documentation from the configuration, the configuration from the documentation, or both configuration and documentation from some common source. Historically, most effort has been focused on the first one of those options, deriving the documentation from the configuration.

What I've been working on with the open source Netomata Config Generator (NCG) tool are the second and third of those options: start with a description of how your network should be, and derive all of your device and service configuration files from that. The source description may serve as your "documentation", or you might generate more human-friendly documentation (HTML pages, for example) from that source.

While I think it's hopeless to try to manually document how your network is configured, I think its essential to document why your network is the way it is. I wrote an article about this distinction for the USENIX magazine, ;login:, called "What are your intentions?".

By the way, I'll be teaching a full-day class on automating network configuration and management (covering Netomata's open source tool, as well as various other tools) at the USENIX LISA conference in San Jose on Friday, 12 November 2010.

Brent Chapman <[email protected]>

... You eventually should have a look at racktables ( We use this tool for documentation of our switches, servers and their positions at the racks (good visualisation), for documentation of their connections and also to assign the IP ranges and addresses. A great tool, with the possibility to import switchports via snmp. This does not solve all problems, but nevertheless it absolutely is worth a look.



Thanks! I'll take a look!

I actually work for Graphical Networks and we make a web-based automated network documentation solution called netTerrain. It pretty much addresses all of the points you touched upon - def. check it out if you are still in the market!

Leave a comment