System Documentation

Timothy Evans

tim@timothydevans.me.uk

Copyright 2001 by Timothy D Evans

Please note the usual disclaimer applies.

Unlimited non-commercial distribution of this document in its entirety is encouraged, please contact the author prior to commercial publication.

22 November 2001

This document discusses "system documentation". For the purposes of this document Servers and Workstations are considered. The subject of system documentation could occupy several books; this document discusses some basic ideas. The characteristics of good system documentation are considered such as what form the documentation should take. The requirements of system documentation are considered and an attempt is made to define what system documentation should do i.e. what its purpose is. The possibilities for automating system documentation are explored.

Characteristics

What the characteristics of good system documentation are is difficult to decide. Some desirable characteristics are described below:

Created for intended audience

The documentation should be created for the intended audience. While it may be appropriate for a "Management overview" to be created for non-technical people, most system documentation will be used by System Administrators and other technical people as an important reference. System documentation should provide sufficient technical detail.

Specific

The system documentation should describe the specific implementation of a given system rather than provide generic documentation.

Relationship with other documentation

System documentation should be reasonably self contained; however it will often be a component of a wider collection of documentation and it is reasonable for it to reference other documents. There is little value in duplicating information from Vendor's manuals.

Up to date

The documentation needs to be up to date, but does not necessarily have to be recent. If the system has remained completely unchanged for a long period of time, the documentation can remain unchanged for the same period of time. It is important that when systems are changed documentation is updated to reflect the changes and this should be part of any change control procedures.

Sufficiently comprehensive

Documentation needs to be sufficiently comprehensive to for fill its purpose.

Accessible

The documentation must be held in a location and format that makes it accessible. It is obviously unacceptable to have the only copy of a system's documentation held on a drive that has failed or on the system itself should it fail.

It is very desirable to hold the documentation in a universal standard format that does not require access to a particular word processor; ASCII text may be most suitable.

Secure

Because system documentation could be useful to troublemakers, thought may need to be given to controlling access to the documentation.

Requirements

The question of what is the purpose of system documentation is difficult to answer. Below are some possible uses of system documentation.

Introduction / overview

System documentation can provide an introduction and overview of systems. New Administrators, contractors and other staff may need to familiarise themselves with a system; the first thing that will be requested is any system documentation. To avoid staff having to waste time discovering the purpose of a system, how it is configured etc system documentation should provide an Introduction.

Disaster Recovery

Many systems are supported by disaster recovery arrangements, but even in such circumstances, the recovery can still fail. There may be a need to re-build a system from scratch at least to the point where a normal restore from backup can be done. To make a rebuild possible it will be necessary to have documentation that provides answers to the configuration choices. For example it is important to re-build the system with the correct size of file systems to avoid trying to restore data to a file system that has been made too small. In some circumstances certain parameters can be difficult to change at a later date. When rebuilding a system it may be important to configure networking with the original parameters both to avoid conflicts with other systems on the network and because these may be difficult to change subsequently.

OS or Application re-load

Even when a disaster has not occurred, there may be times when it is necessary to reload an Operating System or Application; this can either be as part of a major version upgrade or a drastic step necessary to solve problems. In such circumstances it is important to know how an OS or Application has been configured.

Trouble shooting aid

The benefits of good system documentation, when trouble shooting, are fairly obvious. A comprehensive description of how a system should be configured and should behave can be invaluable when configuration information has become corrupted, when services have failed, or components have failed.

Good system documentation will include a description of the physical hardware and its physical configuration, which can avoid the need to shutdown a system in order to examine items such as jumper settings.

Planning tool

When planning changes or upgrades it will be necessary to assess the impact of changes on existing systems. A good understanding of existing systems is necessary for assessing the impact of any changes and for this good system documentation is required.

Other

System documentation can be used for many purposes including Auditing, Inventory, Maintenance, etc. The documentation of individual systems forms an important component of the overall network documentation.

Automating the creation of system documentation

Most operating systems include tools to report important system information and often the output from such tools can be re-directed to a file; this provides a means of automating the creation of system documentation.

Many Administrators have neither the time nor inclination to produce System Documentation and given the importance of keeping such documentation current, automation of the creation of system documentation is very desirable.

There are limitations to the extent to which system documentation can be automated. The following cannot be documented automatically:

The documentation of items that cannot be documented automatically can be facilitated by such means as having standard template documents and creating such documentation when systems are first installed. Fortunately this kind of documentation is less susceptible to change and is often less critical. It may be useful to create a simple file in a standard location (perhaps root) on systems that contains "external" information such as serial numbers, asset numbers etc.

Most Operating Systems have tools for automating their deployment (e.g. unattend.txt for NT, JumpStart for Solaris, Kickstart for Redhat Linux etc). Although these tools are primarily intended for deploying large numbers of systems they can be used for individual systems. While the configuration scripts used in these tools are not very readable, they are in text form, and can be read by technical staff. Such scripts offer the great advantage that a system is documented in an unambiguous way that guarantees that the system can be rebuilt exactly the same way it was first built.

For most systems it should be possible to create a simple script (or batch file) that uses several system tools to report system information and out put the results to a file. The use of such tools together with simple print commands (e.g. echo "line of text") can readily produce a useful document. It should be possible to adapt such scripts to produce the documentation required in terms of content and level of detail etc.

If standard tools do not provide sufficient information, there are many third party tools and free tools that can be used, however the potential problems of using additional tools, rather than just "built-in" tools, has to be weighed against the advantages. Alternative scripting languages (such a Perl) may provide additional benefits.


Appendix: Tools for Automation

Below are just a few examples of some tools that can be used to automate the creation of documentation for various Operating Systems.

Microsoft Windows NT 4.0

WINMSD

The command:
winmsd /af
will create a text file called %computername%.txt
where %computername% is the name of the computer. The file contains extensive information about the system.

Microsoft Windows 2000

msinfo32.exe

\Program Files\Common Files\Microsoft Shared\MSInfo\msinfo32.exe /report filename
outputs a text format file to the specified file filename. The file contains extensive information about the system.

Novell NetWare

CONFIG.NLM

CONFIG.NLM and CONFGNUT.NLM are loaded at the Server console to create a text file (CONFIG.TXT) in the SYS:SYSTEM directory; if the file already exists it is overwritten.

Two switches can be used:
Use the command:
LOAD CONFIG /d
to include the SYSTEM file listings.
Use the command:
LOAD CONFIG /s
to include the SET parameters. Both switches can be used together to produce a comprehensive output:
LOAD CONFIG /ds

Solaris

The following tools and commands can be used:

Solaris tools
Command Information produced
uname system information
eeprom eeprom settings
df disk settings
ifconfig -a network settings
cat /etc/hostname.le0 hostname
env environment settings
patchadd -p patches
pkginfo packages

Redhat Linux

The following tools and commands can be used:

Redhat Linux tools
Command Information produced
cat /etc/fstab mount information
ifconfig -a network settings
uname system information
env environment settings
cat /etc/sysconfig/hwconf hardware settings
cat /etc/lilo.conf lilo configuration
rpm -qa packages

Valid XHTML 1.0!