The Wall of Fire – 05 – Documentation

There comes a point in all deployments when an installation transitions from deployment to support. This involves handover documentation and for many people what this encapsulates varies. The importance of having comprehensive documentation on handover cannot be overstated. It should provide the information in a way that in conjunction with a high level and detailed level design guide provides anyone the ability to rebuild the installation.

How I personally develop an install will involve the following process. After garnering requirements from business requirements and interpreting the technology that will be used to achieve this. The interpretation of the business requirements with the appropriate technology yields a document known as a high level design document. This high level design states business requirements, constraints, assumptions, and at a high level how the solution achieves this. This document is the overarching piece that will serve as a reference point for a detailed design, implementation walk through, and verification testing.

The detailed design should cover every single technology used. It should have a brief outline about what role it plays, then contain all the settings and values used and configured. For example if the solution has used VLANs there would be a paragraph with an overview of VLANs in relation to the deployment, a table stating the relevant device, VLAN name, and VLAN ID. If this VLAN also had a L3 gateway there would be a table outlining information pertaining to the SVI.

For me the following documents or information should accompany a handover. If it is not in your high level design or detailed design it should be given with the hand over documents. This list below is an example and should not be considered comprehensive.

Physical layout – this involves rack diagrams, physical port configurations, location, PDU outlet, modules, and other details pertaining to environment information.

  • Layer 2 – in a firewall based deployment this would involve bridge groups, port channels, transparent firewall settings, VLANs, trunks, and the like.
  • Logical layout – this involves layer 3 information such as addressing, routes, routing protocols, routing instances, NAT, and VPNs.
  • Application – documenting technologies used such as anti-virus, web filtering, malware, and vendor specific L7 technologies.
  • Supplementary information – access lists, QoS, objects, service-groups,  AAA, TACACS and configurations that support other sections are listed here.

There are some great examples already around the community of developing documentation and diagramming which would be extremely useful in your high level and detailed designs. Greg Ferro over at Ethereal Mind has a plethora of posts pertaining to documentation here. He also has a superb Visio series for those who use this software and this is the first post in that series. There is also some great advice from a few smart gentlemen over at the PacketPushers website with a focus on diagramming. Charles wrote a post on physical and circuit drawing and has a focus on how to keep track of it. Jaakko has a post focusing on L3 logical network diagrams. Both are worth reading. The provide perspective and insight into a process where many people actually miss the mark.

In additional to the aforementioned diagram offerings is my own gem which has aided vastly in documentation. The standardisation of names through a naming convention. — is the format I use. This allows me to accommodate via geographic location first. Second is company. This might seem odd to some but when an administrator manages more than one company this makes sense. Device can be named by type, function, or role and number is self explanatory. An example would be MEL-IBM-SLB-01.

It is important to note that this piece looks at what should be documented and how it should be done as a part of any piece of work. What is outside this document is the notion of continuous updating of all moves, adds, and changes in a network architecture. There are applications, processes, and entire frameworks which are dedicated to this.

There are many parts about documenting that generally get overlooked. The time of transition provides a great opportunity to look at existing processes and what is included and how you should look at your end to end architecture. The more up to date and current information you have the more likely you will be able to understand the changes occurring.

Leave a Reply

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