Network documentation is arguably both the most important and most over looked tasked a network administrator does. A good network diagram is invaluable for understanding how a network is working, for troubleshooting when its not working, and a great source of information when onboarding new employees to the network team or, more important to me, getting vendors and partners up to speed on how the existing network is configured.
Over the years I have seen some amazing network diagrams, and some not so amazing diagrams; from the most detailed Visio diagrams, to what could be considered a sketch on the back of a napkin. Unfortunately I often receive documentation that is incomplete or inaccurate. As network engineers and administrators we often focus on planning for and making changes to our networks, then forget to document those changes and move on to the next project. At some point we have all been guilty of this! So in this post I am going to go over how I document a network, and the ways my diagrams are rich with information, yet easy to read. My hope is by showing you how I diagram you can elevate your diagraming game and maybe implement some of what I do into your diagrams.
Physical vs Logical
Network diagrams can be categorized into two different types of diagrams; physical and logical. The physical diagram is as it says, the way the network is physically cabled. A good physical diagram not only shows that two devices are connected to each other, but on which ports are they connected. Often I see diagrams showing devices with lines connecting them; and that's it. This way of diagraming lacks necessary information such as what ports are used to connect the devices, what speed is the port, and what medium is used to make that connection (copper, single or multimode fiber, direct attach, etc.).
The way that I like to represent a physical diagram is by color coding the different components. Below is a fake diagram I threw together using Lucid using the same templates I use for my actual customers. As you can see I color coded both the port and the medium. This conveys this information without the diagram looking too wordy.
My physical diagrams not only show the layer 1 connections between devices, but also show layer 2 vlan and port-channel information. I include a vlan mapping in the corner along with the description of that vlan. Additionally I add the vlan information to every layer 2 link. This information helps when trying to figure out what ports can talk directly with on another.
The Logical diagram is one that shows how devices communicate from the device perspective. This effectively is a layer 3 diagram. This diagram shows where subnets are terminated, as well as routing information. I have seen some diagrams where they tried to combine the logical diagram on top of the physical diagram, however those diagrams tend to become too messy and wordy. Because of this, I tend to create a separate logical diagram.
Above is an example of a logical diagram. Notice that only the devices that participate in routing are represented and the connections between devices are logical ones. Again I like using color to determine meaningful information; in this case different routing protocols and VPN tunnels. I also use circles to show the boundaries of the routing protocols, suggesting route redistribution where the circles overlap. Lastly, I show every SVI and routed interface configured.
Diagram per location
Whenever I work with large companies I notice that often times I am presented with a large extremely detailed diagram with all locations represented on that single diagram. While this starts out as a fairly simple diagram, over time as more sites are added, new 3rd party services are integrated, and new WAN technologies are implemented, this single diagram approach quickly becomes a mess. Because of this I always go with a per location diagram, with the WAN marking the boundary of the location.
Just about all diagramming tools have the ability to add new tabs to the file, making per location diagrams logical. For my diagrams every location has at least 2 tabs, one for the physical and the other logical diagrams. If down the road you need to add another site, well just add 2 more tabs; no more needing to figure out how to move things around to keep the diagram from looking messy.
This format is also perfect for when you have a complex WAN setup. You can add a new tab and format it in such a way that you provide enough detail to convey how the WAN is configured without bothering the reader with unnecessary information. In the diagram below, you can see how I created a WAN diagram showing the fake MPLS circuits at each site. I also included information used in determining which circuit is preferred, something that was left out of the location diagrams.
The whole point of a network diagram is to provide clarity to how the network is supposed to operate. While this information could be included in a single large diagram, often times all the location specific information just clutters the page and slows down any troubleshooting efforts. By using tabs and creating per location and/or per technology diagrams you quickly convey the important information in a clear and concise way.
Beyond the types of diagrams I've described thus far, I usually include one or two other diagrams that are specific to the project that I am working on. The following is a short list of other diagrams that I have used in specific situations:
- Wireless AP placement
- Server Connectivity
- Authentication Integration
- Network controller connectivity
- Rack Elevations
The wireless AP placement diagram is simply a floorplan with AP placement. This includes AP names, as well as SSIDs and or AP group info. This type of diagram is extremely helpful when trying to troubleshoot wireless.
Server Connectivity diagrams are a physical diagram showing how servers and storage connect back to the network. This diagram seems to either be extremely simple, or very complex depending on the server environment.
With how complex hybrid cloud installments have become, coupled with zero trust security designs I have started diagraming how user authentications are integrated between cloud services and on-prem equipment.
Similar to Authentication Integration, I started creating separate diagrams showing Network controller connectivity. This can be anything from SD-WAN controllers, to cloud controlled wireless access points. With the proliferation of centralized controllers it makes sense to diagram this design to better understand how management and control traffic flows through the network.
Finally the last optional diagram is the good ol' rack elevation. Whenever I am apart of a green field build it becomes important to have a rack elevation to show any installers how to rack the gear. In addition to the rack elevation a MDF layout also makes sense showing a top down view of the MDF.
In summary, it is very important to document your network, and the network diagram is the heart of this documentation. Having clearly defined and detailed diagrams makes deploying a new project easier, makes troubleshooting an issue in the network less stressful, and makes selling the idea of why you need new gear to management that much easier. Hopefully you took something from how I document network diagrams and are inspired to elevate your documentation game!
If you would like to get a better network diagram as well as be provided network recommendations based on vendor validated best practices, reach out to LookingPoint for a network assessment. Please reach out to us at LookingPoint at email@example.com, we can help!
Trevor Butler, Network Architect