Have you ever received a cell phone call while you are sitting in a canoe in the middle of a lake? Or maybe your phone has rung while lying beside the pool? Perhaps you were driving along the coastline enjoying the scenery when your phone rang and destroyed the reverie? If this has happened to you, chances are that you are bad at documentation. Do not fear, though, because you are not alone. Maybe that should make you really afraid instead. Documentation tends to be the bane of nearly any IT professional’s existence. I think it would require a different type of professional to figure out why, so let’s instead focus on what can be done about the problem.

Writing up formal documentation on every system to have sitting in a binder looks impressive, but what good is that binder when you are twenty miles away at your house working because you have some kind of emergency like plumbing or sick children? Electronic documentation is far more useful, especially when much of your workforce is mobile in some way. It is also quite useful when the system has its own documentation features so that the information required is right there beside what you are about to change. In an effort to help make everyone’s vacations more cell-phone-free, here are a few commonly overlooked places to document the systems with which we work every day.

Anyone who has taken our Check Point Essentials class has probably heard me almost preach the use of the comment fields in Check Point. Everything in Check Point has a place for some kind of description or name, so take advantage of it! Objects, Rules, and Session Descriptions are only the beginning of what Check Point offers in self-documentation. Having quality documentation in your firewall will help your backup admin understand the purpose of rules and objects so there is no guesswork in adding something to the system. In addition, utilizing the ticket numbers from a ticketing or change control system makes it even easier to see all of the related detail for a particular rule.

Yes, contrary to popular belief, we work on a lot of Cisco devices. While Cisco’s command line interface does not provide nearly the capability for commenting as Check Point, there are still plenty of ways to help out your colleagues. Every interface has a description field, which means every permanent connection to the device should be documented in this field. Does the interface connect to a provider? You had better put the circuit ID or other designation into the description. Does the interface connect to a server, or another switch? You should document what it connects to. The Cisco Discovery Protocol can also be helpful for deducing connections in a live environment, but it also has many vulnerabilities that can be exploited. If you decide to use CDP, make sure that it is only enabled on the switchports that require it.

Of course, the most important thing to document in a Cisco environment is an access list. We have encountered many Cisco environments with multi-page access lists and not a comment anywhere to be seen in any of it. They are easy to add, just use the “remark” command instead of “permit” or “deny”. Comments at the top describing the overall purpose of the access list combined with comments in the middle for each section make reading through those lines and lines of text much less frightening. Remember, a frightened admin is always going to make that phone call, so make the text as easy to read as possible.

If you have ever looked at the configuration files for software like BIND or Apache, you will notice a lot of lines beginning with some odd symbols, such as the octothorpe/hash/pound symbol “#”, or perhaps a semicolon “;”, or even a double slash “//”. You might even see lines that begin with “/*” and somewhere later end with “*/”. All of these are different types of comment formats in UNIX configuration files. Most default installs come with a fully annotated configuration file describing what each setting does, giving possible options, and showing the default setting. How nice of the programmer or software packager to provide such rich detail! When changes are made to the configuration, it is quite easy to follow in those footsteps and provide the same level of detail to your co-workers. Your spouse will thank you for the lack of intrusion while you are trying to take in the sun on the beach.

Now that we have all the nitty-gritty details recorded in the systems themselves, it is time to focus on the forest rather than the trees. What do we do about that general overview of a system? We need to have a new hire or new member of the team get oriented with everything, but handing over a stack of configurations and printouts is just going to overwhelm the person. Our solution to getting people’s feet wet is using a wiki to do both general and more detailed views of systems and networks. The formatting is fairly free, so laying out information the way it makes sense to your organization is simple. Most wiki software also includes a template system so that each type of page can have a consistent format. This makes browsing through multiple pages looking for one key piece of information much easier than sifting through disparate pages laid out by different people.

Combining these with your existing change control measures will make it easy for anyone from auditors to backup admins to understand what is going on and cross-reference against the business needs for the system you primarily support. Face it: Will it not also help you understand the system yourself? We have seen a number of instances of the primary administrator go back to something created years ago and say, “Hmm.. Do we still need that? I wonder what it is for?” With proper documentation, you will never need to ask those questions of yourself, nor will your colleagues have to ask them of you while you are sitting in a cabin enjoying the wilderness.