System Documentation

Timothy Evans
tim@timothydevans.me.uk
Copyright 2001 by Timothy D Evans
Please note the usual disclaimer applies.
Unlimited non-commercial distribution o this document in its entirety is encouraged!
please contact the author prior to commercial publication.
22 "ovember 2001
This document discusses #system documentation#. $or the purposes o this document
%ervers and &or'stations are considered. The sub(ect o system documentation could
occupy several boo's) this document discusses some basic ideas. The characteristics o
good system documentation are considered such as *hat orm the documentation should
ta'e. The re+uirements o system documentation are considered and an attempt is made
to deine *hat system documentation should do i.e. *hat its purpose is. The possibilities
or automating system documentation are e,plored.
Characteristics
&hat the characteristics o good system documentation are is diicult to decide. %ome
desirable characteristics are described belo*-
Created for intended audience
The documentation should be created or the intended audience. &hile it may be
appropriate or a #.anagement overvie*# to be created or non-technical people! most
system documentation *ill be used by %ystem /dministrators and other technical people
as an important reerence. %ystem documentation should provide suicient technical
detail.
Specifc
The system documentation should describe the speciic implementation o a given system
rather than provide generic documentation.
Relationship with other documentation
%ystem documentation should be reasonably sel contained) ho*ever it *ill oten be a
component o a *ider collection o documentation and it is reasonable or it to reerence
other documents. There is little value in duplicating inormation rom 0endor1s manuals.
Up to date
The documentation needs to be up to date! but does not necessarily have to be recent. 2
the system has remained completely unchanged or a long period o time! the
documentation can remain unchanged or the same period o time. 2t is important that
*hen systems are changed documentation is updated to relect the changes and this
should be part o any change control procedures.
Sufciently comprehensive
Documentation needs to be suiciently comprehensive to or ill its purpose.
Accessible
The documentation must be held in a location and ormat that ma'es it accessible. 2t is
obviously unacceptable to have the only copy o a system1s documentation held on a
drive that has ailed or on the system itsel should it ail.
2t is very desirable to hold the documentation in a universal standard ormat that does not
re+uire access to a particular *ord processor) /%C22 te,t may be most suitable.
Secure
3ecause system documentation could be useul to troublema'ers! thought may need to be
given to controlling access to the documentation.
Requirements
The +uestion o *hat is the purpose o system documentation is diicult to ans*er.
3elo* are some possible uses o system documentation.
Introduction / overview
%ystem documentation can provide an introduction and overvie* o systems. "e*
/dministrators! contractors and other sta may need to amiliarise themselves *ith a
system) the irst thing that *ill be re+uested is any system documentation. To avoid sta
having to *aste time discovering the purpose o a system! ho* it is conigured etc system
documentation should provide an 2ntroduction.
Disaster Recovery
.any systems are supported by disaster recovery arrangements! but even in such
circumstances! the recovery can still ail. There may be a need to re-build a system rom
scratch at least to the point *here a normal restore rom bac'up can be done. To ma'e a
rebuild possible it *ill be necessary to have documentation that provides ans*ers to the
coniguration choices. $or e,ample it is important to re-build the system *ith the correct
si4e o ile systems to avoid trying to restore data to a ile system that has been made too
small. 2n some circumstances certain parameters can be diicult to change at a later date.
&hen rebuilding a system it may be important to conigure net*or'ing *ith the original
parameters both to avoid conlicts *ith other systems on the net*or' and because these
may be diicult to change subse+uently.
S or Application re!load
Even *hen a disaster has not occurred! there may be times *hen it is necessary to reload
an 5perating %ystem or /pplication) this can either be as part o a ma(or version upgrade
or a drastic step necessary to solve problems. 2n such circumstances it is important to
'no* ho* an 5% or /pplication has been conigured.
"rouble shootin# aid
The beneits o good system documentation! *hen trouble shooting! are airly obvious. /
comprehensive description o ho* a system should be conigured and should behave can
be invaluable *hen coniguration inormation has become corrupted! *hen services have
ailed! or components have ailed.
6ood system documentation *ill include a description o the physical hard*are and its
physical coniguration! *hich can avoid the need to shutdo*n a system in order to
e,amine items such as (umper settings.
$lannin# tool
&hen planning changes or upgrades it *ill be necessary to assess the impact o changes
on e,isting systems. / good understanding o e,isting systems is necessary or assessing
the impact o any changes and or this good system documentation is re+uired.
ther
%ystem documentation can be used or many purposes including /uditing! 2nventory!
.aintenance! etc. The documentation o individual systems orms an important
component o the overall net*or' documentation.
Automating the creation of system
documentation
.ost operating systems include tools to report important system inormation and oten
the output rom such tools can be re-directed to a ile) this provides a means o
automating the creation o system documentation.
.any /dministrators have neither the time nor inclination to produce %ystem
Documentation and given the importance o 'eeping such documentation current!
automation o the creation o system documentation is very desirable.
There are limitations to the e,tent to *hich system documentation can be automated. The
ollo*ing cannot be documented automatically-
Te,tual descriptions that /dministrators may create.
7ard*are coniguration items that cannot be detected through sot*are 8perhaps
such as *hich slot on a bus a card occupies or ho* (umpers are set9.
5ther items that cannot be detected through sot*are such as serial numbers! the
physical location o a system etc.
The documentation o items that cannot be documented automatically can be acilitated
by such means as having standard template documents and creating such documentation
*hen systems are irst installed. $ortunately this 'ind o documentation is less
susceptible to change and is oten less critical. 2t may be useul to create a simple ile in a
standard location 8perhaps root9 on systems that contains #e,ternal# inormation such as
serial numbers! asset numbers etc.
.ost 5perating %ystems have tools or automating their deployment 8e.g. unattend.t,t or
"T! :ump%tart or %olaris! ;ic'start or <edhat =inu, etc9. /lthough these tools are
primarily intended or deploying large numbers o systems they can be used or
individual systems. &hile the coniguration scripts used in these tools are not very
readable! they are in te,t orm! and can be read by technical sta. %uch scripts oer the
great advantage that a system is documented in an unambiguous *ay that guarantees that
the system can be rebuilt e,actly the same *ay it *as irst built.
$or most systems it should be possible to create a simple script 8or batch ile9 that uses
several system tools to report system inormation and out put the results to a ile. The use
o such tools together *ith simple print commands 8e.g. echo #line o te,t#9 can readily
produce a useul document. 2t should be possible to adapt such scripts to produce the
documentation re+uired in terms o content and level o detail etc.
2 standard tools do not provide suicient inormation! there are many third party tools
and ree tools that can be used! ho*ever the potential problems o using additional tools!
rather than (ust #built-in# tools! has to be *eighed against the advantages. /lternative
scripting languages 8such a Perl9 may provide additional beneits.
Appendix: Tools for Automation
3elo* are (ust a e* e,amples o some tools that can be used to automate the creation o
documentation or various 5perating %ystems.
%icrosoft &indows '" ()*
&2".%D
The command-
winmsd /af
*ill create a te,t ile called >computername>.t,t
*here >computername> is the name o the computer. The ile contains e,tensive
inormation about the system.
%icrosoft &indows +***
msino?2.e,e
\Program Files\Common Files\Microsoft
Shared\MSInfo\msinfo32.exe /report filename
outputs a te,t ormat ile to the speciied ile filename. The ile contains e,tensive
inormation about the system.
'ovell 'et&are
C5"$26."=.
C5"$26."=. and C5"$6"UT."=. are loaded at the %erver console to create a te,t
ile 8C5"$26.T@T9 in the %A%-%A%TE. directory) i the ile already e,ists it is
over*ritten.
T*o s*itches can be used-
Use the command-
L!" C#FI$ /d
to include the %A%TE. ile listings.
Use the command-
L!" C#FI$ /s
to include the %ET parameters. 3oth s*itches can be used together to produce a
comprehensive output-
L!" C#FI$ /ds
Solaris
The ollo*ing tools and commands can be used-
%olaris tools
Command Information produced
%name
system inormation
eeprom
eeprom settings
df
dis' settings
ifconfig &a
net*or' settings
cat /etc/hostname.le'
hostname
en(
environment settings
patchadd &p
patches
p)ginfo
pac'ages
Redhat ,inu-
The ollo*ing tools and commands can be used-
<edhat =inu, tools
Command Information produced
cat /etc/fsta*
mount inormation
ifconfig &a
net*or' settings
%name
system inormation
en(
environment settings
cat /etc/s+sconfig/hwconf
hard*are settings
cat /etc/lilo.conf
lilo coniguration
rpm &,a
pac'ages