The "captain's log", as I call it, is a very important part of documenting the work done by system administrators. It records, in a special format that lends itself to reproducing the work, all of the information needed to reproduce a system in its current state.
The captains log is almost a shell script that could be executed on a new computer to create a clone of the first one. In practice, there are a few things that prevent it from simply being executed: 1) the need to reboot in certain places, 2) some interactive (or worse gui) installation programs that don't have command line mode, 3) hardware differences between machines, and 4) new versions of software. So, in reality what tends to happen is that large chunks of the captains-log are copied and pasted into 1) the shell window and 2) the edit window for the captains-log of the new computer.
The captains log comes in very handy, in many situtions, including:
Over the years, I have written over a megabytes worth of captain's logs (about 676 printed pages or 137,852 lines) for about 30 different computers (counting major operating system upgrades as a new machine).
Passwords are normally recorded separately. I usually just replace the password with underscores in the captains log.
Depending on the needs of a specific organization, the captains logs can be stored 1) on the machine in question, 2) in a central location such as on the main system adminstrators workstation, or 3) in gnu arch, CVS, or Subversion. An offline (and offsite) backup should be maintained.
On systems where knowing the exact configuration was sufficiently important (masters for cloning, production servers, etc), I have been known to install a new system and then wipe the hard drive and reproduce it from the captains-log to make sure there are no errors.
It would be EXTREMELY helpful if hardware vendors who supported Linux or *BSD published captains-logs on their web sites for installing selected distributions on their systems or for installing their peripherals. This would significantly increase sales and reduce support costs.
The captains log normally has three sections. The first two sections are normally recorded on another computer (or if necessary, paper) since the computer will not be functional until they are completed.
Normally, before the machine is assembled, I record the model numbers of every board, drive, etc. as well as the part numbers of all major chips on each board. This is important for selecting the right drivers and options. If the machine was already assembled, I often take it apart. Also, it is good to record serial numbers, bios version strings, etc. here.
# Captains log for cervantes.freelabs.com
# Started july 2001
# Mark Whitis <whitis@freelabs.com>
#
# Hardware Configuration:
# - Motherboard: ASUS P5A (alladin chipset), ATX Form Factor
# Aladdin 5 chipset
# Chip: AMD K6-2
# Chip: Li M1541 A1 1000 MHz 9935 T507 XD362660000G TIAWAN
# (Motherboard Chipset, PCI bridge)
# Chip: ALi M1543C 9932 TM05 XB6B8500000E TAIWAN
# (Motherboard Chipset, host bridge, USB controller)
# Chip: tmtech T35L6464AA-5Q (Ram of some sort)
# Chip: ESS Solo 1 (Audio)
# BIOS: Award Bios
# Note: USB is OHCI based
# URL: http://www.ali.com.tw/eng/support/faq/linux_os_faq.htm
# - BIOS
# - File: AL5I107A.AWD
# - Award Modular BIOS v4.51PG
# - ASUS P5A ACPI BIOS Revision 1007.A
# - 07/16/79 Aladdin5 <-00
# - This bios is the latest availible as of July 2001
# - This bios has problems with large hard drives >32GB (no LBA32)
# - Memory: 96MB
# - Hard Drive WDC WD600AB-32BVA0 60GB
# NOTE: We need some shenanigans because the ASUS BIOS is outdated and
# does not support drives >32GB.
# - CD Writer: Vendor: HP Model: CD-Writer+ 9100 Rev: 1.0c
# - Modem
# Bus: ISA
# Model: Phoebe CMV1456VQH-2MRA
# Jumper Settings: COM3 IRQ7
# Features: Data/fax/voice
# URL: http://www.phoebemicro.com
# Chip: Conexant 11596-21 E13382.6 0010 Mexico
# chip: Conexant L2800-38 E10317.4 0007 Mexico
# Chip: RP56D/SP R6764-61 E13254.3 0010 Mexico
# MX 27C2000 PC-90 C699545 TAIWAN VPP=12.5V
# Label: FCC No: H8NTAQI-26018-M5-E
# Label: 200V2300239401 (s/n)
# Label: P/N: A2316720
# Bracket Connections (top to bottom): "Phone", "Line", "SPK", "Phone"
# - 8 Port Serial Card
# Bus: ISA
# Model: Byterunner TC-800
# Chip: 8x 16C550CB BC9804
# Chip: 8x LGS GD75232
# Chip: misc logic and GAL chips not recorded
# Jumper Settings: All ports jumpered to use IRQ11, enabled
# - SCSI Controller
# BUS: PCI
# Model: Advansys ABP-960 (iomega Jaz jet?)
# s/n AE65A633E855
# - Ethernet controller
# Model: Linksys LNE100TX Version 2.X
# Chip: Linksys LNE100TX LC82C115 M9918 TA429401 37BDX
# (tulip compatible)
# Chip: YCC R20PMT04 9918M (hybrid media interface)
# wake on lan connection
# - Video Board:
# Bus: AGP
# Model: ATI All-in-wonder 16 AGP
# Chip: ATI RAGE 128 (Controller)
# Chip: AIW128 59908 (BIOS)
# Chip: Bt829BKRF (TV in?)
# Chip: TDA9850T 472730 DSD990501
# Chip: Impac TV2 213TV2UA21 B2K61 9917AA TIAWAN (TV out?)
# Chip: (8x) 48LCIM16A1 (RAM)
# Bracket Connectors: (top to bottom)
# A/V In MiniDin 8 (external fanout box)
# CATV F connector
# A/V OUT MiniDin 8 (external fanout cable)
# Monitor SVGA 15 pin high density D
# Internal Connectors:
# CD in
# CD out
# - Floppy Drive: 1.44MB
# - irda transceiver
# connected to motherboard
#
# - BIOS
# - Check boot order: A,CDROM, C or similar
# - Check floppy drives are properly configured
# - Check hard drives are properly configured. Typically, you will want
# to use LBA mode. Make sure the settings reflect your current drive
# and not the prior one.
# - Check that any interrupts needed by ISA devices are
# appropriately configured
# - Disable power management shutdown
# - set the time/date (use UTC if appropriate)
# - record the disk geometry in your captains-log
# - enable irda port
# - save and exit setup
#
# To find info on chips:
# http://www.xs4all.nl/~ganswijk/chipdir/
# http://www.elnec.com/ic_logos/ic_logos.htm
Hardware vendors should not which features are and aren't supported here. If, for example, the motherboard audio doesn't work under linux, it should be noted here.
# - Insert CD-ROM [NOTE: should have specified which CD-ROM, i.e redhat x.x disk1]
# - Boot machine (reset or ctrl-alt-delete, if necessary)
# - Boot: expert
# - Do you have a Driver Disk: No
#
# - Choose a language: English
# - keyboard type: US
# - installation method: local CDROM
# - (running annaconda - please wait)
# - (starts x server)
# - Mouse:
# Generic 3 button, PS/2
# Port: n/a (implied PS/2 port)
# Emulate 3 buttons: yes
# - (help screen, continue)
# - Install Type: Install, custom system
# (if you select desktop here instead of custom, you will not get a full
# install).
# - Disk Partitioning: fdisk
# you can also use disk druid but it does not allow fine control or
# display sufficient information to recreate the exact configuration
# later if the table is corrupted.
#
# Disk /dev/hda: 255 heads, 63 sectors, 4111 cylinders
# Units = cylinders of 16065 * 512 bytes
#
# Device Boot Start End Blocks Id System
# /dev/hda1 1 33 265041 83 Linux
# /dev/hda2 34 66 265072+ 82 Linux swap
# /dev/hda3 67 4000 31599855 83 Linux
# /dev/hda4 4001 4111 891607+ 83 Linux
#
#
# (mount point does not appear in fdisk, it is set later.)
#
#
# using fdisk:
# The commands you will use, and the approximate order:
# - p (prints partitions)
# - If necessary, delete all partitions. Don't do this if you have
# already installed another operating system. This is necessary
# if the disk geometry has changed since last partitioned (in which
# case, you will probably want to write the partition table, reboot,
# and run fdisk again just to be safe).
# - Delete any unwanted partitions, using "d"
#
# - Delete any partitions you created to reserve space to be reallocated
# later.
# - Add partitions with the new command "n". There are two types:
# primary and extended. There can be up to 4 primary partitions.
# Multiple Extended partitions are contained in a special type of
# primary partitions (which uses up a primary partition).
# - Change the type of partitions using the "t" command
# Normal linux partions are type 83 (default). Linux swap = 82.
# - print the partition table again. Check for errors. Record
# the information in your captains log.
# - use the "w" command to write the partition table and exit.
#
# - Set mount points
# hda1 /
# hda2 (swap)
# hda3 /disk0
# hda4 /scratch
#
# - Choose Partitions to format: hda1 hda3
# - Check bad blocks: Yes
# - Lilo config:
# - create bootdisk: yes
# - install lilo: yes
# - install boot record on: /dev/hda (MBR)
# (you might want to change this, at least initially, if setting
#
# up a dual-boot system).
# - Use linear mode: yes
# - kernel parameters: hdc=ide-scsi
# (this is just to support my cd burner which is the IDE secondary
# master)
# - Operating systems:
# linux: /dev/hda1, default, linux native
# - Network configuration:
# - Config using DHCP: No
# Don't answer yes even if you are running a DHCP server
# on one of the windows boxes because you will eventually
# make this machine the server.
# - Activate on boot: Yes
# - eth0:
# - IP Address: 192.168.0.1
# - Netmask: 255.255.255.0
# - Broadcast: 192.168.0.255
# - General:
# - Hostname: test71.freelabs.com
# - gateway:
# - Primary DNS: 206.134.144.10
# - Secondary DNS: 207.172.3.11
# - Tertiary DNS:
# - Firewall config:
# - Security level: high
# - use default: no
# - customize: yes
# - trusted devices: none
# - Allow incoming: SSH, HTTP, SMTP, DHCP
# - Language: English (USA)
# - clock settings
# - Time Zone: America/New york (eastern time)
# - System clock uses UTC: Yes
# If you don't use this setting, the clock will probably be wrong
# after daylight savings changes. However, if you do use this
# seting, windoze will be confused since windoze expects/saves
# time in local time.
#
#
# - Account Config:
# - Root:
# - Password: _________
# - User accounts:
# I normally create these later after installing a modified
# version of usermod
# - Auth Config:
# - Enable MD5 passwords: Yes
# - Enable Shadow passwords: Yes
# - Enable NIS: no
# - enable LDAP: no
# - enable kerberos: no
# - Selecting Package Groups:
# - I usually select all groups, including "everything" and click
# select individual (although I usually don't deselect individual
# packages).
# - X Config:
# - Video Card: ATI All-in-wonder 128 Pro AGP
# - RAM: 16MB
# - Monitor: Multisync C500
# - Customize Graphics Config
# - Color Depth: high color ((16 Bit)
# - Screan Resolution: 1280x1024
# - Desktop environment: Gnome
# - Login type: TEXT
# - About to install: click next
# - (Installation takes about an hour at this point, so you can
# do other stuff - however, you will be prompted to change CD-ROMs)
# - Bootdisk Creation: Yes
# (insert floppy)
# - System Reboots
# - Press ctrl-X for text mode when the stupid graphic appears
# - boot: linux single
#
#
In this section, the commands which are done after initial installation are recorded. This includes installing and upgrading packages and routine maintenance done at a later date.
I normally record the commands that need to be executed to reproduce what I did, not necessarily the commands I executed. Therefore, if I make a mistake, I clean up (or at least comment out) the erroneous commands.
One of the areas that is traditionally very poorly documented is
changes to files made with a text editor. I use a much more disciplined
approach. All changes made with a text editor must be recorded
as executable shell commands. Typically, changes are recorded as
commands for the
patch, cat, echo,
sed, or perl programs combined with
redirection of standard input/output, pipes, and shell "here documents"
(inline text in a script which is redirected into standard input).
Files are normally downloaded into the "/dist" directory with wget.
Note that it doesn't hurt to include an example of how to use the program in this section, particularly for programs which are tricky. Do you really want to dig through the man pages every time you use, for example, cdrecord and mkisofs?
# First, lets introduce some of the commands we will
# be using. The commands marked with "***" will be
# covered in detail in later chapters. Refer to the
# man pages for more info.
#
# cat - copies its input to its output
# diff - compares two files ***
# patch - applies the changes in a diff ***
# ncftp - ftp client program
# lynx - text mode web broswer
# tar - pack and unpack tar archives
# cd - change current directory
# make - drives the compilation process ***
# echo - display its arguments
# echo hello, world - says "hello world"
#
# These are some examples of shell magic, see the bash
# man page for more details:
# # - marks a comment line
# foo=bar - set variable foo equal to bar
# export FOO=bar - similar, but subprocesses will inherit value
# echo $(foo) - substitute $(foo) into
# xxx | yyy - pipe output of command xxx into command yyy
# xxx >yyy - redirect the output of command xxx to file yyy
# xxx >>yyy - same, but append to file yyy
# xxx <yyy - redirect input of command xxx from file yyy
# xxx\ - Line continuation character "\"
# yyy - .. continuation of above line, i.e xxxyyy
# xxx <<\...EOF... - "here document" - runs the program xxx
# line1 - .. taking input from the following
# line2 - .. lines in the script up to the line
# ...EOF... - .. which begins with "...EOF...";
###
### Gnozzle
###
# http://www.gnozzle.org/
# This is a sample captains-log entry to install
# a ficticious package called gnozzle
# datestamp produced using "date" command:
# Mon Feb 22 21:39:26 EST 1999
# download it
cd /dist
ncftp -r -D ftp://ftp.gnozzle.com/pub/gnozzle-0.63.tar.gz
# or...
#lynx -source http://www.gnozzle.com/gnozzle-0.63.tar.gz \
>gnozzle-0.63.tar.gz
# Here we unpack the tarball, after first checking
# the directory structure
cd /usr/local/src
tar ztvf gnozzle-0.63.tar.gz
tar zxvf gnozzle-0.63.tar.gz
cd gnozzle-0.63/
# Here we create a permanent record of changes we
# made using a text editor as a patch command. In this
# case, we changed the values of CC and PREFIX in the
# file Makefile. The patch has one hunk which spans
# lines 1 through 7.
#
# the following patch was made like this:
# cp Makefile Makefile.orig
# emacs Makefile
# diff -u Makefile.orig Makefile
# beware of mangled whitespace (especially tabs) when
# cutting and pasting.
patch Makefile <<\...END.OF.PATCH...
--- Makefile.orig Mon Feb 22 21:12:41 1999
+++ Makefile Mon Feb 22 21:13:14 1999
@@ -1,7 +1,7 @@
VERSION=0.63
-CC=pcc
+CC=gcc
CFLAGS=-g
-PREFIX=/usr
+PREFIX=/usr/local
BIN=$(PREFIX)/bin
LIB=$(PREFIX)/bin
MAN=$(PREFIX)/man/man1
...END.OF.PATCH...
# Here we build the program and install it
make clean
make
make -n install # see what it would do first
make install
# Here we create a new file with a couple lines of text
cat >/etc/gnozzle.conf <<\...EOF...
gnozzlelib=/usr/local/lib/gnozzle
allow
...EOF...
# Here, we append a couple lines to the magic file,
# which is used by the some commands to
# guess the type of a file, to add the characteristic
# signature of a gnozzle data file.
cat >>/usr/share/magic <<\...EOF...
# gnozzle
0 long FEDCBA98 Gnozzle data file
...EOF...
Router configuration is often downloaded as a text file. arch, CVS, or subversion can be used to track versions. Changes can also be recorded, along with various other notes, in a captains-log as patches.
Windows is much more tedious to document and reproduce. Mouse clicks are typically recorded something like this: Start -> Control Panel -> System
While you are at it, you may want to start a file that records particularly interesting new incantations you have learned that you are likely to forget but need in the future. Things like sed and perl magic can go here. For example, the examples of captains-log code were converted to html using the following sed command:
sed -e 's/\&/\&/g' -e 's/</\</g' -e 's/>/\>/g'
One may wish to start something similar to a captains-log that just contains usage examples for particular programs that are tricky to use such as CVS, postgresql, gnuplot, etc.
This file is maintained by Mark Whitis (whitis@freelabs.com).
|
Software Development - Electronic Design - Embedded Systems - Device Drivers - System/Network Administration and Security - Motor Control, RobotCNC - Linux/Un*x - 25+ years experience The author of these pages is looking for a new gig. [RESUME] |
| Engineers and electronic hobbyists: The new Open Symbol Project is creating open schematic symbols and PCB footprints for a variety of different CAD packages. |
| Mark Whitis's Website | Home Page | Linux | Book: Linux Programming Unleashed | My Resume | Genealogical Data | Contact Info | Security | About |
All email messages received must pass the turing test or they will be considered SPAM. If it could have been written by a machine, it was.
Under no circumstances are you to email me with questions regarding windoze, any other microsoft operating system or application, or any software which runs under any form of windoze.
*