Everybody agrees network documentation is extremely important, but there tends not to be a lot of agreement on what that documentation should include. The short answer is that it should include everything that’s relevant—but what that means varies between networks.
For example, in a really small network with one switch and a firewall and perhaps a single wireless access point, there isn’t much to document. It might be enough to put everything in a single diagram.
But in a bigger network, you need to follow the general principle that somebody else will need to support this thing one day and you want to be remembered positively.
So the actual documents you need will vary depending on the network, but the following table shows the relative importance for a typical network.
|Critical||Layer 1 or Layer 1 / 2||Diagram||Should show key infrastructure|
|Critical||Layer 3||Diagram||Should show key infrastructure|
|Critical||Circuit numbers||Table||Sometimes this is done within a trouble ticketing system|
|Critical||IP Address allocation||Table||This could be a tool rather than a spreadsheet to allow easy sharing|
|Useful||Rack layout||Diagram||Particularly for data centre|
|Useful||WiFi layout||Diagram||Depending on how important the WiFi is|
|Useful||Cable plan||Diagram||Particularly useful if the drops are not numbered the same as the desk locations|
|Useful||Routing protocol||Diagram||Becomes critical if you run a routing protocol of any complexity|
|Useful||Security view||Diagram||This is more useful for explaining your security than for troubleshooting|
|Useful||Cloud services||Diagram||Becomes critical if you run a cloud of any complexity|
|Useful||Patching table||Table||Particularly useful during implementation|
|Useful||Asset tracking||Table||Particularly infrastructure assets and support contracts|
|Useful||Password vault||Table||Should be encrypted|
|Nice to have||Detailed design document||Document||Becomes critical in larger environments with lots of support staff|
|Nice to have||Support document||Document||Depends on support organization|
|Nice to have||Routing and spanning tree snapshots||Document||Useful for troubleshooting|
Critical network documentation
Layer 1 and 2 diagram
A Layer 1 diagram shows the physical connections between the critical pieces of network infrastructure. It includes things like link speeds and cabling types. I like to see individual port numbers or designations on a Layer 1 diagram. Normally I represent the faster links using thicker lines and I use different colours for fibre and copper as well as for storage and data networks.
I often combine Layer 2 features onto the Layer 1 diagram because they seem to go naturally together. Layer 2 features include things like VLAN numbers, link aggregation, and trunk connections. Also, any Layer 2 diagram must include spanning tree information such as the root bridge and any bridge and link priorities that have been changed from their defaults.
If you aren’t running spanning tree, then you probably need a separate diagram just to thoroughly document what you’re doing with TRILL or alternatives. And if you don’t have spanning tree or TRILL and you have more than one switch, you’re doing it wrong.
Layer 3 diagram
Layer 3 diagrams include all your IP segments and all the network devices that interconnect them. That generally mean Layer 3 switches, routers, and firewalls. The IP segments should indicate any relevant VLAN ID numbers and a brief one or two-word description of the intended function, as well as the IP network number and mask. I like to put the IP addresses of the network devices on this diagram as well.
Any important redundancy mechanisms like HSRP or VRRP should be clearly indicated on the Layer 3 diagram. However, I don’t put end devices like servers on a Layer 3 diagram unless they have some extremely important network function — for example, a DHCP, DNS, or LDAP server.
Those are the network diagrams you absolutely need to have. In addition, you should have diagrams that represent other important features of your network. What’s considered important will depend on the network.
Circuit number table
Another piece of critical documentation, particularly if you have any WAN circuits or voice circuits, is a detailed listing of all of your circuit numbers. The list should include the circuit numbers and the network provider, as well as any information about where the circuit goes.
If it’s an MPLS circuit, the spreadsheet should include all of the MPLS provisioning information. If it’s an Internet circuit, then the amount and detail of the information could vary wildly depending on the provider and the type of circuit. And if it’s a point-to-point circuit, then it makes sense to include information about what’s on the other end.
I like to include support information in this listing of circuit numbers. What phone number do I call if this circuit goes down? If I need to provide special support contract information when I make that call, it should also be recorded here.
IP address allocation table
Next is the IP address allocation spreadsheet or database, which should include every internal and external, registered and private, IPv4 and IPv6 address you have in your environment. Every subnet should be listed separately, and every individual device should be recorded. If you’re using DHCP, which is also a good practice, for a range of addresses, just indicate these are dynamic addresses. But every static address allocation should be recorded.
Also, and this is most important, you need to be able to reserve addresses that you intend to use for a particular purpose in the future. Otherwise you’ll inevitably wind up giving out the same addresses to two different projects and creating completely avoidable conflicts.
I like to have a separate spreadsheet for all of my NAT addresses in which I describe exactly what each address is used for. If I have multiple internal or DMZ devices mapped to a single external address on different ports, then I carefully record each NAT rule. This makes life much easier the next time you need to add a new NAT rule.
Useful network documentation
Rack layout diagram
A rack layout diagram shows the server room or wiring closet racks with all of the equipment and patch panels. If you have equipment mounted to be accessible from both the front and back of the cabinet, then you should have diagrams for both the front and the back.
A rack layout diagram should be meticulously accurate about what equipment is mounted in which numerical position on the rack.
You’ll use a rack layout diagram when planning for where to put that next piece of equipment, as well as when talking to technicians and other IT staff about where to find things. It’s extremely important when you’re telling somebody to shut off the power to a particular device that they get the right one.
Rack layouts can also specify things like which aisle is hot and which one is cold, as well as power distribution. However, I don’t recommend putting patch cords on a rack diagram. That information is likely to change regularly, and it only clutters up the picture without adding much useful information. I’ll talk about how to record patching information later.
If you have an important Wi-Fi component to your network, that should be documented. For Wi-Fi, I like to see floor layouts showing the physical locations of all access points (APs), preferably with RF radiation patterns indicated. This is particularly important if there are any special antennas in use with non-symmetrical radiation patterns.
As well, a good Wi-Fi diagram shows all of the SSIDs along with their intended purposes and security mechanisms. And if there are central Wi-Fi controllers, this information should be indicated in a text box.
A similar diagram that comes in handy whenever you’re troubleshooting an office network problem (like finding the guy who created a loop by cleverly plugging two jacks into the same unauthorized workgroup switch) is a cable plan. This diagram allows you to map the usually inscrutable jack numbers to physical locations in your building.
Routing protocol diagram
Another useful diagram is a routing protocol design. If there are separate routing domains that don’t directly exchange routes with one another, I often make them separate diagrams. For example, if I have an internal OSPF or EIGRP routing domain and an external Internet BGP routing domain, I always make these separate diagrams.
The routing protocol diagram should indicate all autonomous systems, internal areas, and redistribution points and it should clearly indicate special features such as route tagging or filtering.
Another special-purpose network diagram I like to include in my documentation package is a security view. It’s similar to the Layer 3 diagram except that it focuses on things like the Internet edge, as well as any internal or Internet DMZs.
Of course, all special security equipment needs to be clearly indicated on this diagram.
The standard Layer 3 diagram includes firewalls, but the security diagram needs to also include any special security probes, IDS/IPS devices and passive or active taps. I also want to see central management devices like SIEMs and log servers on this diagram. If there are any important NAT rules or firewall rules, it’s often useful to indicate these as well.
Cloud services diagram
If you have any cloud services like AWS, you should document them. Cloud service diagrams need to include all of the security zones, and should probably also include all of the virtual servers in the environment.
If you have any special network security infrastructure in your cloud services like firewalls, load balancers, or WAF virtual devices, they need to be clearly described so that the next person can easily understand what you’ve done and how to manage it.
If you have a VPN between the cloud and your internal network, it’s extremely important to include that feature on the diagram because it’s here the most sensitive information will typically be sent, and it’s also a potential backdoor into your network.
In a data center, you should document your patch panels. Data centres usually have many different kinds of links, from fibre and copper to perhaps some twinax or Infiniband. And every device is both important and potentially unique. Mistakes could take down the entire network.
Conversely, the patch panels that support all of the users in the west wing of the third floor probably has most of those users connected to identically configured switch ports. It’s certainly useful to keep a good patch table for it, but it’s really not as critical as the data centre patching information. As I mentioned earlier, though, you do want to have a physical map showing where all of those office cables go so you can troubleshoot problems down to the end user.
At a minimum, the patching documentation should show, for every port in the panel, exactly what’s connected on the other end of the cable. If the device or panel on the other end has lots of ports, then the destination port should be uniquely identified along with the device.
The documentation should also indicate what type of patch cord is used. Is it Category 6? Is it fibre? If it’s fibre, is it single mode or multi-mode and what are the connector types on both ends? If the patch cords have unique identifying numbers, which is a good practice, those numbers should be included as well.
It’s very useful to have a table of asset tracking information. For this, I’m usually not too concerned about commodity items like phones, printers, or workstations. Instead, the list should include the critical pieces of infrastructure like switches, routers, and firewalls, as well as any critical pieces of server hardware.
In the asset tracking information table, I want to see manufacturer names, models, serial numbers, and license numbers. You also want to include support contract numbers so you know who to call if something goes wrong.
One important and useful piece of documentation is a password vault. If you have static administrative passwords on any of your network appliances, store these credentials in an encrypted vault of some kind. In general, I prefer the devices to use a central authentication system like RADIUS or TACACS, but inevitably there will be some devices that need static passwords. And in most cases, you’ll also have fallback passwords that can be used if the central authentication system breaks.
Nice-to-have network documentation
Some other pieces of network documentation depend on the situation.
Network design document
If I’m designing a network for a client, I often do a detailed design document. It’s often a fairly long document in which I describe the design and explain the intended functions of every new feature and new section in the network.
It can be helpful to include a decision log where you identify all of the key design decisions and explain why they were made. For example, perhaps you’ve chosen to use a particular routing protocol because of the need to support a particular legacy requirement. Or you might have wanted to implement a more sophisticated and robust feature in part of the network, but ran into compatibility problems so you had to resort to a brute force solution instead. These notes becomes very useful later when you wonder why something was done a particular way and whether it’s safe to change it.
Network support document
I sometimes write a support document to help with migrating the infrastructure to production. It includes things like suggestions for how to implement new systems within the framework that I’ve made, and recommendations for where and how to modify security restrictions to allow new services through the firewalls without compromising the design. It might also include troubleshooting notes. For example, I might list the expected symptoms of common failure modes like circuit failures.
If you run a particularly large network, it’s often useful to maintain a good set of routing snapshots of the routing tables for use when troubleshooting. This could include routing protocol information as well. And you could similarly record other dynamic topology information like spanning tree link states for the same reason.
Now that I’ve outlined what to collect and document, there’s still the question of how you will do it — that’s your documentation process. Tools can help you automate the process so you’re not spending all your time manually collecting and maintaining information. They can also ensure that all members of your team always have the same accurate information.
But no matter what method you use, what’s important is a consistent process that produces quality information and keeps that information up to date.
The No Sweat Guide to Network Topology
How to build and document your network topology like a pro.