A Documented Network Is Easier to Troubleshoot

One of the oldest abbreviations used on the Internet doesn't have anything to do with a specific protocol or network service. It's RTFM. If you ever get this in response to posting a question on a newsgroup, you can probably guess what the letters stand for. For those who don't know, it's something along the lines of "read the fine manual!" although "fine" is often replaced with a slightly different word. Use of this term is intended to point out that your question is a simple one that you can easily find an answer to, so you should quit wasting bandwidth by your postings.

Documentation consists of the manuals that come with software applications, operating systems, switches, and other network components . The quality of this sort of vendor-supplied documentation can vary widely from one vendor to another. You'll find that many companies, such as Cisco, Microsoft, and Novell, provide a lot of online documentation for their products. Often the documentation you get from a vendor is a simplified booklet combined with more extensive documentation on a CD. One of the most widely used formats for creating user documents is the Adobe Portable Document Format (.PDF files), and you can download the Adobe Acrobat Reader application free from www.adobe.com.

However, after you find yourself with an assortment of documentation ”from hard-copy manuals to files on a CD or a Web site ”then it's time to consider what you will use to document how your particular network is laid out, from both the physical and the logical point of view. When it comes time to troubleshoot a problem on the network, it's nice to have documentation that enables you to quickly get an answer to such simple questions as "Where are the configuration instructions for that router stored?" or "Just who is that user anyway?"

Note

Documentation made available online via the Internet can serve two purposes. First, you can quickly search and find information in a problem scenario. Second, you can read through any online documentation a vendor provides before you make a decision to purchase the particular software or hardware product. Along the same lines, you can also get an idea of the type of support you'll receive if you review the documentation before you buy. If the documentation isn't up to par, it might not matter how good the product is ”support is everything.

For individual applications or operating systems, you can visit USENET newsgroups and participate in (or just lurk around and read) discussions about problems with particular products. You may just find your answer there. If not, you can post your question. One of the things that newsgroup members most dislike is someone posting a question without providing the details that led up to the problem. Provide the details! If you read the newsgroups on a regular basis, you may be apprised of problems before they appear on your network.

Some of the important things you should consider as potential candidates for documenting include the following:

• A logical map of the network. This may or may not match up with the physical way the network is laid out.

• A physical map of the network. This documentation should describe each physical component and illustrate the ways in which the different components are connected.

• Cabling and patch panel information. When you've got hundreds of cables in a wiring closet patching together different physical segments, you'll need to know which cable connects this to that.

• Default settings for computers and other devices on the network. A spreadsheet is good for this. An application that manages servers, network components, and client computers is even better.

• Listings of applications and the computers or users that make use of them, as well as software versions, patch levels, and so on. Be sure to know who to contact for a particular application. If you are a network administrator, you are primarily responsible for the underlying network. If a particular application is failing, but the network is up and running, you need to know who to call. There should always be a contact on your list for application managers. A network manager can do only so much.

• Information about the user accounts, and associated permissions and rights, for the users and user groups on the network.

• A network overview. It's nice to be able to give a new user a document that explains what she needs to know about the network. This should be a short document telling the user such things as which drives are mapped to her computer, and which printers offer what features. This should not be an extensive document such as the physical and logical maps described earlier in this list.

• Problem reports . Keep track of problems as they arise, and document the cause and remedy. No need to solve the same problem twice! This also includes outage reports ”keeping track of unscheduled downtime for a computer or network device can tell you over time just how capable the device is.

A logical map of the network shows the relationships between components and the flow of information through the network. A physical map of the network tries to approximate on paper a representation of how each component of the network is connected to the network. For example, a logical map for a Windows network might show computers grouped by domains, even though the computers are not located physically in the same part of the network. A physical map would show the location of each of the computers, the hub or switch to which they are connected, and so on. In general, logical maps can be used to help isolate configuration or application problems, whereas physical maps can be used to isolate a problem that affects only a portion of the network, perhaps a single computer or other device.

You can do the same for any Ethernet or other technology-based network. Knowing the physical layout can be a very important factor in troubleshooting a network problem. For example, Unix and some Linux systems use both NIS (Network Information Systems) and now LDAP (the Lightweight Directory Access Protocol).

Note

You can learn more about NIS in Chapter 30, "Network Name Resolution." You can lean more about LDAP in Appendix D, "The Lightweight Directory Access Protocol." If you want to learn about a specific instance of LDAP, read Chapter 31, "Using the Active Directory."

You can use simple tools, such as Microsoft Paint, to create network mapping documents, or you can buy applications that automate the process. Using an application that is written specifically for creating network maps should be considered for anything but the smallest network. The capability to locate components, update them, and produce easy-to-understand printed documentation is the hallmark of a good network diagramming application. One such tool is Microsoft's Visio, which allows you to create complex network drawings, and includes pictographic elements for most modern network devices that you can easily use.

Inside the wiring closet you can have a tangled mess of wires on a patch panel that haphazardly tie one network link to another. Or you can have an orderly system in which each port on the patch panel is labeled, using a standardized method so that making changes won't be a hit-or- miss effort. The same goes for configuration information for other components of the wiring closet, such as switch ports or routers. In-depth documentation is important so that you can re-create the configuration from scratch if it becomes necessary to replace a device.

Applications should be standardized, which means you shouldn't have multiple applications that all perform the same function. It's much simpler to support a standard application, such as an office suite, than it is to support multiple applications. And, although the same configuration might not be appropriate for every user, you can at least try to create several standard configurations for classes of users. This makes deploying a desktop computer for a new employee much easier. On that odd occasion when you find that something nonstandard is required, document that also, and also document the reasons behind the decision to use an alternative configuration.

Keeping track of which applications are in use and how they are configured serves another purpose. Some applications interact with others, or are tied to specific versions of an operating system. If you have adequate documentation of the applications used on your network, you can better plan for upgrades.

After you've documented the physical components of the network and the applications, what's left? Oh, yes, the users. If not for the users, you would not have a job. Having a document of some sort that shows a user profile can be useful for troubleshooting purposes. If you know only a user's logon username and the name of his computer, you have little to go on when he calls in with a problem. If you can quickly locate more information about the user, such as the applications installed on his computer, or the privileges and permissions assigned to the user account or the computer, then you have valuable information to use to help solve problems. Often you can't get all this information from the user over the phone because many users don't know that much about what resides on their system. They know only the applications they use and how they use them.

Lastly, keep track of problems. Record the symptoms, the tools used to troubleshoot the problem, and the resolution of the problem. This documentation can assist you in the future so you can quickly determine the solution to a problem based on the symptoms reported by the users. You can also use this information to assist in creating documentation that you give to new users. By informing them of problems that have occurred in the past, you can help prevent the same problems from happening again.

Documentation and Maintenance ”Keeping Things Up-to-Date

Documentation is an ongoing process. Networks rarely stay the same for a long time. It has been my experience that the larger the network, the faster the rate of change, as users or departments are relocated and new equipment replaces older equipment. So when you consider what means you'll use to create network documentation, be sure to take into consideration that it will need to be updated and you'll need some way for keeping track of changes in an orderly fashion.

Some of the tools you can use to create network documentation include these:

• Word processors and spreadsheets ” Each of these is beneficial. Word processors enable you to create professional-looking documents that can be easily changed and reprinted. Spread-sheets can be used to locate information quickly and that information can be easily organized by indexing.

• Online tools ” Use simple Web pages to create online documentation. If you have a specific application that has been customized for your network, create a frequently asked questions (FAQ) document for it and put it online (on your intranet). Additionally, you might shy away from pointing users to FAQs and other documents available on the Internet, unless they are sites known to contain accurate information (such as www.rfc-editor.org). There is a great deal of information, as well as disinformation, on the Internet.

• Network mapping tools ” Microsoft's Visio and other applications can assist you with developing a complete map of your network. This tool is not inexpensive, but it may prove invaluable in a large installation.

• Hard copy ” Printed paper documentation. Two words: Read it.

Word Processors and Spreadsheets

These two tools can be useful for creating documentation. You can use either one to gather information about the network and organize it to locate information quickly and easily. Word processing and spreadsheet applications are easy to update, and for instances in which printed documentation is necessary, most of these programs provide excellent formatting and printing capabilities. For example, you can use tables in Microsoft Office's Word program, or possibly a spreadsheet, to create a list of all the network devices and computers that have an IP address assigned to them. If you want to locate a particular item of data, Word enables you to search a document, and spreadsheets allow you to create multiple indices so that important identifiers are sorted to make it easy to locate information.

For a typical LAN today, it's likely that you'll have only a few important devices or servers that have static IP addressing information assigned. It's easier to use DHCP servers to allocate IP configuration information to computers automatically when they boot. To keep track of dynamically assigned IP configuration information, you can consult the DHCP server application to determine what listing or reporting features are available. For computers or devices you configure with static IP information, you can use a spreadsheet to keep track of this information. Then, when it becomes necessary to replace a router or similar device, you can consult the documentation to get the required configuration information to use on the replacement.

Note

The Dynamic Host Configuration Protocol (DHCP) is discussed in detail in Chapter 29, "BOOTP and Dynamic Host Configuration Protocol (DHCP)." If you use the Microsoft DHCP server that comes with Windows 2000 Server and the Windows 2003 family of servers, you can also enter into the DHCP database the static information that you manually configure some of your servers or devices to use. You can do this by entering static IP addresses and setting up reservations using the GUI for the DHCP service. In addition to being sure that the DHCP server doesn't try to use an address that you've already manually assigned to another computer, this enables you to use the DHCP database for reporting and analysis. Microsoft's DHCP server and many others allow you to export data to files, such as comma-delimited ASCII text files, that can be imported into programs such as spreadsheets or other databases.

Many other programs and utilities have "output" capabilities so that you can send their information to a file. For example, on Windows (both workstation and operating-system platforms) from earlier versions to Windows Server 2003 servers, the IPCONFIG command can be used to display information about the current IP configuration on the computer. If you use the syntax ipconfig /all > % computername %.txt , the output from the command is sent to the file named the same as the computer's name with the .txt extension instead of to the screen. The point is that you don't necessarily have to manually create all your documentation. Instead, make use of the tools and utilities provided by the operating system and applications to get the data, and then import it into other programs that make it easier to manage.

Other important things you may want to consider keeping track of for individual computers include the particulars of the hardware that make up the system, any customizations made on the system that aren't part of a standard, and the user(s) of the system. If the computer is a server on your network, it's a good idea to keep track of contact phone numbers for client representatives so that you can keep them informed during any troubleshooting efforts or downtime.

Online and Paper Documentation

The paperless office that was forecast during the early days of the PC revolution in the 1980s has yet to come about. No matter how small PDAs and laptops become, it's generally easier to sit down with a printed manual. Having to stare at a screen for hours at a time can be a lot more cumbersome. Although word processors and other programs are great at making it easy to find information quickly, sometimes the best option is to print things for easier handling.

Today it is not uncommon to find paper documentation being replaced by hyperlinked text files on a Web site. Instead of looking in the index of a book to find the information you need, you can utilize the Web. A Web site can be useful for several reasons. First, for common problems, a simple FAQ document can help end users solve problems themselves so that your help desk doesn't get a call. Second, for those who do sit at a help desk, clicking through a set of links to find information can be faster than having to juggle one or more manuals and talk to the end user on the phone at the same time.

User Feedback Can Improve Documentation

You can easily judge how well your documentation assists end users by soliciting feedback. If you create the greatest looking documents that can possibly be created, that won't matter if the end user can't make sense of the content. After you've created any kind of documentation, be sure to provide a mechanism that can enable users to provide you with questions or comments on the documentation. Take these suggestions into consideration when it comes time to make updates.