Network Documentation–Cisco Managing Networks
It often seems no one in network engineering enjoys documenting their networks. What every engineer enjoys, especially at 2 a.m., when the network is down, and they are on the phone with technical support, is having access to good network documentation.
Engineers also really like to have thorough documentation on hand when they are planning changes. Documentation can answer questions like
• Which ports are in use, and which are unused?
• Where does a cable run?
• Which routers are running which routing protocol?
• Where are the failure and security domains?
• Where does a virtual topology land? Where are the tunnel head- and tail-ends?
If you do not document your network, where will the documentation you need to plan and troubleshoot come from?
No “network documentation monsters” will wander around your network, building brilliant documentation for you.
The bottom line is—network documentation is important enough for you to overcome your distaste and do it.
There are five basic kinds of network documentation:
• Network diagrams
• Descriptions
• Failure reports
• Hardware and software
Chapter 10, “Basic Network Hardware, ” explained network diagrams. The other four documentation types are considered in one of the following sections.
Descriptions
Network descriptions should include anything helpful to a new engineer trying to understand how a network works and why it works that way. Examples include:
• The principles used in designing the network. Documenting what was considered important and what was not can be helpful many years later.
• Applications the network was designed to support and their requirements.
• The intent behind each device’s configuration. While many parts of a device’s configuration will be obvious—IP addresses assigned to each interface, for instance—many parts of a device’s configuration will not be intuitive. A good rule of thumb here is if you had to explain this to a vendor’s technical support person at 2 a.m., you should document why it is configured this way.
• The device naming system.
• The IP addressing system and why this naming system was chosen.
• The expected flow of control plane (routing) information and data through the network.
• The way any automation works, how to find the source code, what servers it runs on, and anything else to make automation easier to understand.
Network operators should not be afraid of writing too much.
Anything useful should be written down somewhere easily accessible to every network engineer.
Baselines
Suppose a user calls the help desk and complains about an application. According to the user, the application is taking too long to create a critical report, so can you please fix it?
The problem is “too long” could mean
• The user is late to an important meeting, so the application seems to take a long time to create the report.
• The application is taking longer than usual to complete the report, but the report is still being created within the application’s original design specification.
• The application is taking longer than usual to complete the report, but the network is seriously overloaded right now because someone released a new viral cat video.
• The application is taking longer than usual to complete the report because of network problems.
You cannot know if something is broken—or even how it is— unless you know how something was designed to work, how it should work, and how it normally works. These are three very different things.
Baselining measures how things work, so you have something to compare future performance against.
Network operators should have baselines for just about everything involving events and performance, including
• Bandwidth utilization pattern on each link.
• How often a link flaps or fails.
• How long it takes for each section of the network to converge.
• How often a router, switch, optical interface, etc., fails.
• The average delay across each section of the network. Each baseline should be updated over time so operators can see trends. For instance, if you measure the bandwidth utilization of your Internet connection every week, you can probably figure out when the link might need to be upgraded.