Veni, Vidi, VISA

besser gesagt meine Mindestanforderungen.. insbesondere bei Programmen die OpenSource sind.

Requirements/Systemanforderungen
Am besten mit Programmversionen und Links zum Herunterladen dazu; ich hab keine Lust Foo-Bar 0.23pre zu installieren, weil Foobar mit der stabilen Version nicht klarkommt oder erst danach zu suchen.

Installationsanleitung
Am besten für den Source. Mir treibt es regelmäßig das Essen aus dem Magen wenn ich mir die Manpages von optionalen Programmen (autoconf, automake, autohell, ..) durchlesen muss oder weil Foobar so geil konzipiert wurde, dass es per Default nur unter /usr/local/share/aclocal nach libtool.m4 sucht.

Brauchbare Verzeichnisstruktur
Wenn ich ein Archiv herunterlade, dann will ich nach dem Entpacken ein neu angelegtes Verzeichnis haben in dem ich arbeiten kann und nicht alle Dateien des Archives unter $PWD rumliegen haben.

Dokumentationen
Damit meine ich keinen User Guide oder ein komplettes Handbuch; wäre zwar schön, aber nicht überlebenswichtig. Damit meine ich kommentierten und übersichtlich strukturierten Quelltext, eine README in der die wichtigsten Punkte (Zweck des Programms, Links zur Homepage des Programms, optional notwendigen Programmen, kurze Erklärung der wichtigstens Optionen/Parameter ..) aufgeführt sind, eine FAQ und eine INSTALL (und damit meine ich eine brauchbare und nicht den Dreck der vom GNU autohell-Dreck erzeugt wird) und dokumentierte Konfigurationsdateien. Und das ganze als text/plain! Bei neueren Versionen einen Changelog. Und zwar einen in dem die gemachten Änderungen ausführlich beschrieben sind.

Screenshots/Screencasts
Die einzigen Programme in denen man auf die verzichten kann, sind Shells und Editoren welche ohne GUI auskommen. Ich will wissen wie das Ding aussieht das ich installiere, weil ich weder Zeit, noch Lust habe einen Windowmanager oder ein komplettes Desktop Environments auf Verdacht zu kompilieren.

Deinstallieren
Es ist teilweise erbärmlich das der Großteil aller Developer es nicht auf die Reihe bringen, eine Rule Namens uninstall ins Makefile zu schreiben die auch funktioniert. Highlight war mal eine Rule Namens "uninstall" die "clean" aufgerufen hat, welche dann alle *.o unter ${PWD}/ gelöscht hat. Ist ja nicht erste Mal das ich das anspreche und es gibt auch checkinstall und stow, aber - um mal Gerhard Polt zu zitieren - Brauchts des?! HA!? BRAUCHT ES DAS?!

Archivformat
*.tar, *.gz, *.tar.gz oder *.bz2 bitte! Danke! Ich will kein unzip, unace oder unrar installieren, weil $DEVELOPER anscheinend mit der Bedienung von tar(1) und Co. überfordert ist. Und weil wir gerade dabei sind: Nicht nur die aktuelle Version, sondern auch die Vorgängerversion zum Herunterladen anbieten, damit man bei Problemen erstmal prüfen kann ob auch wirklich das Programm schuld ist (weil man z. B. die Vorgängerversion schon genutzt und die auch funktioniert hat oder weil die neue Version nicht abwärtskompatibel ist.

Homepage
Jungs.. die Zeiten von comp.unix.sources sind (leider) vorbei. Es sollte doch möglich sein eine Homepage zu erstellen (Sourceforge bietet das sogar kostenlos an) wo man als User eine Anlaufstelle hat und weitere Informationen/Hilfe (Mailingliste, Trac, ..) finden kann. Und weil wir gerade dabei sind: Navigationsmenüs in Flash oder JavaScript haben auf einer Seite nichts verloren. Read my lips: Nein! Die braucht keine Sau! Eine Seite die man nur mit aktiviertem JavaScript und Flash-Plugin nutzen kann, ist Schweinescheisse³. Ich will mich auch nicht erst kostenlos registrieren damit ich im Board mitlesen oder suchen kann.

Christian *over-and-out*

➣ Meine Konfigurationsdateien (Irssi, Zsh, Eggdrop, ZNC, ..) ausmisten, ausführlicher kommentieren und wieder online stellen.
➣ Dokumentationen zu einigen Programmen schreiben (Hat mal wer 'ne Tüte Motivation für mich?!).
➣ Den Bot um einige Scripte erweitern (Ja. Mach ich ganzganz sicher_raptor_! Gib Ruhe jetzt :p).
➣ Mein Git-Repo auf dem VServer erstellen/auslagern.
➣ Mein glorreiches "Neue Version von $SOFTWARE verfügbar!"-Script erweitern

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.

Heute ist wieder einer dieser Tage.. Vorhin bekam ich eine Mail, in der mir dessen Verfasser mitteilt, dass er es nicht in Ordnung findet das ich auf meiner Homepage zusammenkopierte und geklaute Texte als meine eigenen Dokumentationen ausgebe. Er bezieht sich darauf u. a. auf meine Zsh-Seite und den Abschnitt Tipps & Tricks, da diese Beispiele nicht von mir sind. Mir ist zwar nicht ganz klar was an

A collection of tips out of the mailinglists (zsh-users and zsh-workers), google, newsgroups or by myself.

unverstaendlich ist, aber na gut. Das ist ja nicht das einzige was von mir kopiert wurde; eigentlich besteht die ganze Seite aus "zusammenkopierten Texten".
Features ist aus zsh-4.3.4/FEATURES und Differences between some shells ist ein Auszug aus http://www.faqs.org/faqs/unix-faq/shell/shell-differences/. Dann ist da noch die Tatsache, dass ich mich mit fremden Federn ruehme. Ich hab naemlich die Manpage zsh-lovers ebenfalls als mein Werk ausgegeben und er (der Verfasser der Mail) ist am Ueberlegen ob er das -mika- sagt. Naja.. wenn ich ganz ehrlich bin bezweifle ist das Michael Prokop das noch nicht weiss; immerhin ist die "Ur-Manpage zshexamples(1) auf meinem Mist gewachsen und wurde nach und nach zur jetzigen zsh-lovers(1) (welche ebenfalls von mir im Asciidoc - Format geschrieben/konvertiert wurde).
Bin gespannt was als naechstes kommt. Wahrscheinlich krieg ich Anschiss weil ich die FAQ von vsftpd und/oder RFC1180 uebersetzt habe. Manchmal fuehl ich mich einfach nur noch muede..

"eine Kopie der vorhandenen Dokumentation fuer das System per Mail schicken?!"
Na sicher doch:

$ for i in /usr/share/doc/**/*(.) /usr/src/linux/Documentation/**/*(.)

> do

>        mutt -s "${i##*/}" -a $i hirn@hein.er

> done

Chris'Mittag machend'tian

Ich hab unter http://www.strcat.de/eigenes/signale.html eine kurze Zusammenfassung ueber Signale hochgeladen. Den Text hab ich hauptsaechlich geschrieben, weil ich zur Zeit dabei bin mich mit AsciiDoc zu befassen.

AsciiDoc ist fuer mich optimal, weil ich nicht mehr gezwungen bin, mich mit diesem schwulen HTML-Scheissdreck zu befassen und das Ding per Default W3C-Konformes HTML und CSS erzeugt *g*

Es ist immer wieder schoen zu neuen Taten motiviert zu werden; insbesondere wenn man so nette Mails wie

nur weil du meinst dich mit irgendwas auszukennen heißt das noch lange nicht das du was besseres bist! deine wichtigtuerei langweilt und deine kopierten texte braucht niemand!

Na wenn ich schon so freundlich gebeten werde, dann werd ich natuerlich keinen Traffic mehr mit meinen kopierten Texten erzeugen. "Hach ja.." vollständig lesen