Documentation needed

documentation_neededIn the past I worked as an external consultant for different customers. When I arrived I would ask for the documentation to get an overview of the network. In some cases you get an unpleasantly long silence and some admin has to admit that there is no documentation at all. You hear something  like “mmh we usually only do port discriptions on the switches”. In my opinion that is not a good idea. Running  a network without proper documentation can end you up in a very uncomfortable situation, especially when something breaks and you have to start figuring out how everything is connected to each other before you can start to debug the actual problem. I have a simple rule, first do the documentation and when that is finished a change or rollout can start. The key is to implement the documentation into the workflow. It starts with simple things like that every device gets a label with the device name on it. I also recommend  a lable at every patch cable with a unique  ID and the start and end point of both sides of the cable. All the information  needs to be put in a database, so that you can get the information very quickly with a simple search. It depends on your needs if you use an free open source database or one of the commercial tools that come with a lot of fancy features.  At the end  of the day  the goal is that you have everything documented in your database and can find all hardware components and connections here. Checking out all the cabling of a device in the moment that it is broken is absolutely  no alternative.  I´ve been there and don´t want  to face it again.

IPAM IP Address Management

I guess that still Excel is the most common tool for IP Address management  and IMHO one of the worst choices for that job.  Maintining a few hundred IP Addresses  in an Excel list will work , but there are so many better tools out there for IP Address Management than Excel. Besides open source tools like NIPAP or phpIPAM,  there are also powerful commercial solutions available. I like the concept of Infoblox IPAM solution that is a combination of IPAM, DNS and DHCP Server in one box. Most devices need a DNS name or DHCP lease with a combined server, that does the documention at the same time. When that device is provisioned and roled out you have always an up to date documentation. It is a real challenge to keep the documentation up to date and the integration of IPAM, DNS and DHCP solves that problem very clever. With IPv4 some network engineers had all the local IPv4 addresses in their heads and didn´t see the need for an IP Address management. I believe with IPv6 even these guys will consider to use an IPAM solution.

Network Diagrams

Microsoft is often trashed by engineers, but for me one of the products that Microsoft has done right is Visio. Visio is still the standard and gives all the needed features for a vector graphic programm that is specialized for network diagrams. You can get visio shapes from most vendors. What you choose depends on your personal style if you want to use more symbolic shapes or the ones that are a 1:1 picture of the actual used device. I prefer the vendor shapes so I can directly see what kind of devices I am dealing with and have a general feeling what a device  looks like in case I have to find it on a rack. I like to have an extra visio for each site / network. In addition to the network diagram I add some additional information,  like the local facility manager that can be called if you have a power failure. On top of the physical network diagram you can add additional layers with macros like you have in photoshop. In case of different overlay networks or different vrfs it is really handy just to switch the different layers in vision so that you only see the relevant layer. To much information in one diagram makes it harder to find a particular information. To use macros and layers is the better option.

Config Backups

Last but not least an often forgotten source for information are the configs of all the devices in the network. I see that also as a documentation source. The oldschool way was to connect to a device via ssh and type some show commands to get the needed information. That works good for a particular information on a particular device. You get more comfort when you grep something across all your devices by a script put the output into a database and search for an information in this output. That can also be done for the config backups. For example you grep all configs from your devices every day make a diff to the previous config and put that into a database . So you can track more easy which changes have been made on a device.

The Network Autobahn view:

It is always good to have a valid up to date documentation of the network. The two big challenges are: keeping the documentation up to date and having a nice structure so you can access the needed informations fast and easy. The Documentation has to be maintained on a regular basis by all IT folks. This is not a job for only one documentation guy, it is a team effort. That can be time consuming and is not popular a job with many engineers, but it is necessary.  When there is a big failure in the network you earn the benefits of spending time on documentation as it helps you to figure out what is going on and to fix the problem faster.

About Dominik

Network problem solver
This entry was posted in All. Bookmark the permalink.

5 Responses to Documentation needed

  1. IJdoD says:

    An integrated IPAM/DNS/DHCP tool is very practical, although having used infoblox for a couple of years I’ve found it somewhat lacking in that IPAM department. I’ve seen some very clever home-grown network tools which pulled all kinds of information from the network and combined that into a search engine. Saves a lot of time troubleshooting, but it does pose a potential maintenance risk: often it’s just a single engineer who knows how all the bits work together under the cover.

    • Dominik says:

      Year I absolutly agree that in most cases only one person has the overview how everything works together. We recently reserved 2x a /32 IPv6 block here I suggest that no single single person can handle that without a proper IPAM documentation tool. Sometimes a self programmed tool that is customized for your enviroment is the best choice.

  2. John says:

    Great article. Do you have an example with Visio and using layers you would be able to share? We have talked about this where I work, but really have struggled in effectively using the layers.

Leave a Reply

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

14 − one =