Es gibt keinen Ersatz fuer gute Dokumentationen wenn ein Server um ein Uhr frueh anfaengt, sich komisch zu benehmen. Es gibt auch keine zu ausfuehrlichen Dokumentationen! Ich hab schon einige Mails bekommen, wo ich gefragt werde, was ich alles dokumentiere, wie es strukturiert ist, in welchem Format die Dokumentationen sind, ... Das Problem dabei ist nur, dass ich solche Fragen nicht allgemein beantworten kann, da es je nach Kunde und Aufgabe unterschiedlich ist. Im
einfachsten Fall - davon ausgegangen das der Kunde keine Sonderwuensche in Bezug auf die Dokumentationen hat - laeuft das wie folgt ab: Kunde will einen Server mit $LINUXDISTRIBUTION installiert/konfiguriert/dokumentiert haben:
Format der Dokumentation:
Die Dokumentationen muessen auf jedem System zu lesen sein; deswegen erstelle ich alle Dokumentationen mit
AsciiDoc. Das hat den Vorteil, dass es problemlos moeglich ist die Dokumentationen in verschiedene Formate zu konvertieren (Plain/Text, PDF, X/HTML, Manpage, ..). Ich uebergebe die Dokumentationen in zwei Formen: erstens ausgedruckt auf Papier, damit sie "direkt" vor Ort eingesehen werden koennen und zum zweiten auf einem
read-only-Speichermedium (CDROM), damit immer ein Original vorhanden ist auf das zurueckgegriffen werden kann. Auch die Sprache sollte man sich vorher ueberlegen. Wenn man den Kunden danach fragt kommt entweder "Deutsch" oder "Englisch" (oder beides) als Antwort.
Aber ganz egal in welcher Sprache man sie erstellt: Sie muss anschliessend Korrektur gelesen werden! Rechtschreibpruefungen helfen dabei, aber um die Grammatik muss man sich selbst kuemmern. Ein Schreibfehler kann u. U. verheerende Folgen haben.
Systeminformationen:
Zuerst erstelle ich ein
Merkblatt ueber den Server; darin enthalten sind Informationen ueber die eingesetzte Distribution, den Kernel, Netzwerkkonfiguration, vorhandene Hardware und die Partitionierung.
Dokumentation der installierten Software
Nach Ende der Installation kommt noch eine Liste der installierten Software hinzu. Bei der installierten Software sollte man darauf achten, dass man die
Herstellerseite mit angibt um Verwechslungen auszuschliessen; wenn (optionale) Patche eingespielt wurden, muss ebenfalls auf diese verwiesen werden. Eine solche Liste laesst sich problemlos mit dem Paketmanagementsystem erstellen (aptitude/dpkg, yum, ..), kann aber
sehr gross und umfangreich sein. Was fuer jedes Paket enthalten sein sollte, ist der Name des Paketes incl. Version, Verweis auf die Homepage und eine Beschreibung. Sinnvoll waere noch eine Liste aller im Paket enthaltenen Dateien incl. deren Dateigroesse, configure-Optionen und ggf. eine Auflistung aller Pakete die dieses Paket benoetigen.
Konfigurationsdateien
Konfigurationsdateien fuer die installierte Software sind ein Fall fuer sich. Zuallererst sollte man darauf achten das sie unter /etc zu finden sind und der Dateiname mit dem Dienst assoziiert werden kann (also /etc/vsftpd.conf fuer vsftp, usw.). Damit man aber nicht stundenlang suchen muss welche Dateien neu hinzugekommen sind, kann man sich wie folgt behelfen:
ls -1 -F /etc > ~/etc-list.txt; damit wird eine simple Auflistung aller Dateien unter /etc erstellt und unter ~/etc-list.txt abgespeichert. Nachdem man die Software installiert hat, fuehrt man ein
ls -1 -F /etc > ~/etclist-new.txt aus und vergleicht diese anschliessend mit
diff -udP ~/etc-list.txt ~/etclist-new.txt. Dateien die nach der Softwareinstallation hinzugekommen sind, erkennt man an dem
+ am Zeilenanfang.
Die meisten Programme welche Konfigurationsdateien benoetigen, legen diese nach der Installation automatisch unter /etc ab; jedoch sind diese per Default meist nur bedingt nutzbar und fuer den Kunden unbrauchbar, weswegen ich immer eine neue Konfigurationsdatei erstelle. Die vom Programm abgelegte Konfigurationsdatei verschiebe ich in ein Verzeichnis Namens /etc/default-configurations. Eine Konfigurationsdatei sollte zur besseren Uebersicht folgende Punkte enthalten
- Eine kurze Beschreibung ueber den Zweck dieser Datei,
- mit welcher Softwareversion sie getestet wurde,
- ob (wenn ja, welche) zusaetzlichen Konfigurationsdateien in diese Datei eingebunden sind und
- welche Dokumentationen noch nuetzlich sind (Manpages, ..)
Der Aufbau einer Konfigurationsdatei haengt davon ab welchen Umfang die Datei hat. Man kann die ganzen Variablen/Optionen/Parameter entweder alphabetisch anordnen oder nach Einsatzzweck. Wenn man z. B. 42 User in einer Konfigurationsdatei verwalten muss, macht es mehr Sinn fuer jeden User einen Abschnitt zu schreiben. Wichtig dabei ist nur, dass man die Konfigurationsdateien ausfuehrlich dokumentiert und auch einrueckt. Zum besseren Verstaendnis habe ich zweimal die gleiche proftpd.conf hochgeladen:
proftpd.conf und
proftpd-verbose.conf. Die "proftpd.conf" ist die
abgespeckte Version der "proftpd-verbose.conf". Beide Dateien sind identisch, aber wenn man diese beiden betrachtet, wird man den Unterschied sehr schnell feststellen und spaetestens wenn man sich auf die Fehlersuche machen muss, weiss man wieso man sich die Arbeit gemacht hat.
Dokumentation der Software
Bevor man aber anfaengt die Software zu installieren, sollte man sich die genaue Kommandozeile notieren. Eine Alternative zum "manuellen Aufschreiben" ist das Programm
script(1), welches im Paket
util-linux-ng enthalten ist. Hierbei sollte man darauf achten, dass Escape-Sequenzen (LS_COLORS, PS1, GREP_COLOR, ..) das
Logfile von script(1) unuebersichtlich machen koennen. Die Verwendung von script(1) hat auch den Vorteil, dass man die exakte Fehlermeldung zur Hand hat und darauf eingehen kann. Nach Moeglichkeit sollte man nicht
um das Paketmanagementsystem herum installieren (Sourcen selbst kompilieren/installieren). Wenn sich sowas nicht vermeiden laesst (weil man z. B. die Features von FooBar-2.3.42 benoetigt, aber nur FooBar-1.2.34 als Paket enthalten ist), hat man zwei Moeglichkeiten:
1.) Man kompiliert die Sourcen per Hand (
./configure && make && make install
2.) Man erstellt ein Paket und installiert das mit dem Paketmanagementsystem.
In beiden Faellen muss man die exakten Arbeitsschritte aufschreiben und in der Dokumentation darauf verweisen ob ggf. andere Libs/Header/.. notwendig sind.
Wenn einem Programm Optionen uebergeben werden muessen, dann ist es sinnvoller die "langen" zu nehmen. Ein
pure-ftpd -y 3:20 -c 15 -C 5 -B
kann man ohne nachzulesen kaum verstehen, waehrend ein
pureftpd --peruserlimits 3:20 --maxclientsnumber 15 --maxclientsperip 15 --daemonize
auch nach laengerer Zeit noch verstaendlich ist. Nach Moeglichkeit sollte man auch die Optionen
vor Ort dokumentieren.
Das ist aber noch die einfachste Arbeit; kompliziert ist erst die Wartung der Dokumentationen bzw. die Aenderungen davon. In Firmen administrieren immer mehrere Personen einen Server und es wird immer vorkommen das vorhandene Konfigurationsdateien geaendert werden. Eine Moeglichkeit ist, Aenderungen direkt in der Konfigurationsdatei zu dokumentieren (davon rate ich ab, da diese sonst ziemlich unuebersichtlich werden kann). Man kann auch auch auf sog.
SCM, VCS oder RCS zurueckgreifen, aber die eigentliche Schwachstelle ist der User.
Auf meinen Kisten bin ich der einzige Admin und ich habe mir angewohnt, saemtliche Aenderungen in einem ChangeLog zu dokumentieren, der im gleichen Verzeichnis wie die Datei liegt. Erstellt wird der Eintrag mit folgendem Script fuer Vim:
fun! InsertChangeLog()
normal(1G)
call append(0, strftime("%a %b %d %T %Z %Y") . " Christian Schneider >strcat@gmx.net<")
call append(1, "")
call append(2, " * ")
call append(3, "")
execute ':3'
normal($)
endfun
map ,cl :call InsertChangeLog()>cr<A
Das ist aber nur eine Loesung, wenn man ab und zu mal was aendert; fuer regelmaessige und umfangreiche Aenderungen (ggf. von mehreren Usern) reicht das auf keinen Fall aus. Hier muss man auf ein RCS seines Vertrauens zurueckgreifen.
Und wenn ich endlich mal hier fertig bin und nach Hause komme, dann kann ich mir das Teil auch mal angucken und aufhängen. Nur noch zwei Tage.. Mittwoch bin ich hier endlich fertig.. dann is Schluss mit kaputtoptimierten Servern und Cronjobs die nicht laufen :>
Last ten comments: