adr alix android apu asa auswahl backup bash bewegung bom buecher c cfengine checklisten cisco computernetz container crypto debian denog dhcp docker dokumentieren duply dvcs ebtables email epub fairphone2 fedora firewall fossilscm git gns3 gre grep hardware i2c iproute ipsec iptables ipv6 kalender konferenz kpartx latex laufen libgcrypt lighttpd linux lua lur make mikrotik monotone mount mysql netbox netflow nfdump nfsen openvpn openwrt pac paketfilter pcap performance perl postfix programmieren projekt proxy pxelinux python qubes-os rancid rezension rfc rpm rs232 schreiben script seriell sftp shell software spiel stehen switch sysadmin syslog systemd termux test troubleshoot ubuntu uci vcs virtualbox virtuell vpn wine wireshark xen xml

Konfiguration und Dokumentation

Fällt mir bei der Fehlersuche oder normalen Administrationsarbeit eine merkwürdige Konfiguration auf, frage ich mich oft, warum das so und nicht anders konfiguriert wurde und ob ich es nicht umkonfigurieren sollte. Bei der Fehlersuche ist der Drang groß, das dann "korrekt" zu konfigurieren, insbesondere, wenn der Fehler dadurch behoben ist.

Aber gerade wenn diese Konfiguration schon längere Zeit so bestand, während der Fehler erst seit kurzem auftrat, muss ich mich natürlich fragen, welchem Zweck diese Konfiguration diente? Das Problem verlagert sich dann von der reinen Fehlersuche nach der Frage der Intention, die mit dieser - scheinbar fehlerhaften - Konfiguration verfolgt wurde.

Praktisch ist dann wenn ich auf eine gut gepflegte Dokumentation zugreifen kann, die nicht nur das faktisch Konfigurierte sondern auch die Gründe für diese Konfiguration dokumentiert.

Ganz abgesehen davon, dass ich das Warum von Entscheidungen bisher nur in wenigen Fällen dokumentiert vorfand, gibt es das Problem, dass die Anforderungen an ein System sich im Laufe der Zeit ändern. Und selbst wenn anfänglich die Gründe für bestimmte Entscheidungen dokumentiert waren, so werden die Gründe für Änderungen, meist an anderer Stelle dokumentiert oder gar nicht.

So divergiert auch eine vorbildliche Dokumentation im Laufe der Zeit immer mehr von der tatsächlichen Konfiguration.

Eine Ursache dafür ist, dass die Pflege der Dokumentation neben der eigentlichen Konfiguration, doppelte Arbeit ist, und wenn überhaupt ausgeführt, nicht immer mit der Realität übereinstimmt. Besser ist, wenn es auch hier eine single source of truth gäbe.

Dafür habe ich mehrere Möglichkeiten:

  • Ich generiere die Konfiguration aus der Dokumentation,

  • oder ich generiere die Dokumentation aus der Konfiguration.

Konfiguration aus der Dokumentation generieren

Die Konfiguration aus der Dokumentation zu generieren, hat den Vorteil, dass die Dokumentation umfangreicher sein kann und auch das Warum, also die Intention und Randbedingungen, enthalten kann. Für die Konfiguration zieht man nur das heraus, was die Maschine braucht.

Nachteilig ist hier allerdings, dass sich ad-hoc-Konfiguration verbietet, wenn sie nicht auf schnellstem Wege in der Dokumentation abgebildet wird und anschließend eine neue "offizielle" Konfiguration generiert wird.

Außerdem ergibt sich das Problem, wie man aus einer für "normale" Menschen verständlichen Dokumentation, eine für Maschinen lesbare Konfiguration generiert. Dafür gibt es jedoch bereits Lösungen, in der Softwareentwicklung zum Beispiel Literate Programming, dass sich in angepasster Form auch für die Konfiguration anwenden lässt.

Dokumentation aus der Konfiguration generieren

Dieser Ansatz hat den Vorteil, dass die Dokumentation immer die vorhandene Konfiguration abbildet.

Ein Nachteil ist jedoch, dass Meta-Informationen, wie Intention und Randbedingungen, normalerweise nicht aus der Konfiguration herausgelesen werden können. Diese sind dann nicht vorhanden, oder müssen extra gepflegt werden, was dem Prinzip single source of truth widerspricht.

Für den Fall, dass die Konfiguration Freitextkommentare zulässt, lassen sich die fehlenden Informationen eventuell darin unterbringen.

Kombination beider Varianten

Beide Möglichkeiten zu kombinieren, erlaubt die Intention und Randbedingungen relativ einfach zu dokumentieren und die tatsächliche mit der gewollten Konfiguration am Ende zu vergleichen.

Wie gehe ich dazu vor?

  1. Ich sichere die aktuelle Konfiguration sowieso regelmäßig. Ad-hoc-Konfigurationen sind an der Tagesordnung.

  2. Ich installiere ein System, dass mir die gewünschte Konfiguration aus der vollständigen Dokumentation generiert und installiert.

  3. Ich kontrolliere regelmäßig automatisch, ob die generierte Konfiguration mit der gesicherten übereinstimmt. Bei einer ad-hoc-Konfiguration ergibt sich eine Abweichung und ich werde darauf aufmerksam gemacht.

Jenachdem, wie schnell ich die Dokumentation nachführen kann und wie wichtig die ad-hoc-Konfiguration ist, schalte ich das automatische Ausbringen der Konfiguration dann ab, bis die Änderung in der Dokumentation nachgeführt ist.

Das birgt allerdings die Gefahr, das Dokumentation und Konfiguration wieder auseinanderlaufen, wenn es ständig abgeschaltet ist. Ohne einen sinnvollen Prozess dafür funktioniert es nicht.

Posted 2025-10-20 Tags:

Konfiguration und Dokumentation
Posted 2025-10-20
Default-Konfiguration finden
Posted 2025-09-23
Git einrichten
Posted 2025-08-03
Verbindungsprobleme im VLAN
Posted 2025-04-19
Kalender 2025
Posted 2024-12-23
Texte mit less untersuchen
Posted 2024-09-17
Kalender 2024
Posted 2023-12-31
Kontrolliertes Ping
Posted 2023-02-15
Kalender 2023
Posted 2023-01-03
Kalenderwoche
Posted 2022-09-05