UNIX System Administration Handbook - Evi Nemeth [481]
27.10 LOCAL DOCUMENTATION
Documentation is often pushed down in the priority queue in favor of “real work.” It’s quite easy to defer documentation because at the moment you should be writing it, you remember how to do the task in question and have no need for a cheat sheet. Any administration group that includes students probably has serious documentation problems.
Local documentation serves many purposes. Have you ever walked into a machine room needing to reboot one server, only to face racks and racks of hardware, all alike, all different, and all unlabeled? Or had to install a piece of hardware that you’ve handled before, but all you can remember about the chore was that it was hard to figure out? Or gone through hours of localizing a new machine to fit your environment, only to realize that you have forgotten a couple of crucial steps?
Local documentation should be kept in a well-defined spot, perhaps /usr/local/doc . Some documentation is most appropriate as a paper booklet or as a sign taped to a piece of hardware.
All system consoles should bear printed instructions that list the hostname, boot instructions, architecture, and any special key sequence that’s needed to reboot the machine ( Also tape the hostname to other pieces of hardware that are associated with each machine: disk drives, modems, printers, tape drives, etc. If the host is an important citizen (for example, a major server or a crucial router), include the location of its circuit breaker. If a floppy disk or flash memory card is required for bootstrapping, point to its location. Major file servers should have information about disk device names, partition tables, mount points, and the locations of backup superblocks ready to hand. Tape the information to the disk drives themselves or store it in a well-known location in the machine room. Tape drives should be labeled with the device files and commands needed to access them. It’s also a good idea to list the type of tapes the drive requires, the nearest place to buy them, and even the approximate price. Printers should be labeled with their names, brief printing instructions, and the hosts that they depend on. Printers often come with network interfaces and are full citizens of the network, but they may depend on a UNIX host for spooling and configuration. Network wiring must be scrupulously documented. Label all cables, identify patch panels and wall outlets, and mark network devices. Always make it easy for your wiring technician to keep the documentation up to date; keep a pencil and forms hanging on the wall of the wiring closet so that it’s painless to note that a cable moved from one device to another. Later, you should transfer this data to on-line storage. A diary file associated with each machine that documents major events in its life (upgrades, hardware repairs, major software installations, and crashes, for example) provides a central place to review the history and status of a machine. You can point an email alias at the file so that the diary can be carbon-copied on mail sent among sysadmins. This is perhaps the most painless and least organized way of keeping records, but its simplicity makes it easier to enforce. It’s a good idea to prepare a printed document that you can give to new users. It should document local customs, procedures for reporting problems, the names and locations of printers, your backup and downtime schedules, and so on. This type of document can save an enormous amount of sysadmin or user services time. You should