{"id":3524,"date":"2023-06-12T07:00:00","date_gmt":"2023-06-12T05:00:00","guid":{"rendered":"https:\/\/www.my-it-brain.de\/wordpress\/?p=3524"},"modified":"2023-06-06T20:15:59","modified_gmt":"2023-06-06T18:15:59","slug":"wp-fail2ban-gutes-plugin-mit-ausbaufaehiger-dokumentation","status":"publish","type":"post","link":"https:\/\/www.my-it-brain.de\/wordpress\/wp-fail2ban-gutes-plugin-mit-ausbaufaehiger-dokumentation\/","title":{"rendered":"WP fail2ban: Gutes Plugin mit ausbauf\u00e4higer Dokumentation"},"content":{"rendered":"\n

WP fail2ban<\/a> ist ein Plugin zum Schutz von WordPress-Installationen vor Brute-Force-Angriffen<\/a>. Installation und Konfiguration habe ich bereits im Artikel WordPress mit Fail2Ban vor Brute-Force-Angriffen sch\u00fctzen<\/a> dokumentiert. Dieser Text besch\u00e4ftigt sich mit der offiziellen Dokumentation des Plugins, bzw. dem Text, der sich als Dokumentation ausgibt.<\/p>\n\n\n\n

Ich stelle hier meine Erwartung an eine Dokumentation heraus, zeige die Schw\u00e4chen der exemplarisch ausgew\u00e4hlten Dokumentation heraus und gebe einen Tipp, wie man weniger schlechte Dokus schreibt. Ich schlie\u00dfe mit Fragen an meine Leserinnen und Leser und freue mich auf eure R\u00fcckmeldungen.<\/p>\n\n\n\n

In meinen Augen sind folgende drei Abschnitte zwingender Bestandteil einer jeden Dokumentation:<\/p>\n\n\n\n

    \n
  1. Was ist dies f\u00fcr eine Anwendung? Wof\u00fcr wird sie verwendet und wof\u00fcr nicht?<\/li>\n\n\n\n
  2. Wie wird diese Anwendung installiert?<\/li>\n\n\n\n
  3. Wie wird diese Anwendung konfiguriert?<\/li>\n<\/ol>\n\n\n\n

    Die ersten beiden Punkte mag ich als erf\u00fcllt betrachten. Beim dritten Punkt sehe ich ein Problem.<\/p>\n\n\n

    \n
    \"\"<\/a>
    Bildschirmfoto der WP fail2ban-Installationsanleitung. Zeitstempel 2023-06-04T20:54+02<\/figcaption><\/figure>\n<\/div>\n\n\n

    Die Installationsanleitung ist pr\u00e4gnant. Sie enth\u00e4lt einen Link, der suggeriert, zur Konfigurationsanleitung zu f\u00fchren. Dort erwartet den neugierigen Leser folgendes Bild.<\/p>\n\n\n

    \n
    \"\"<\/a>
    Bildschirmfoto vom Einstieg in die WB fail2ban-Konfigurationsanleitung. Zeitstempel 2023-06-04T20:59+02<\/figcaption><\/figure>\n<\/div>\n\n\n

    Hier gibt es noch keine n\u00fctzlichen Informationen zu sehen. Die Seite ist in meinen Augen \u00fcberfl\u00fcssig. Aber gut, ein Satz tut nicht weh. Mit einem Klick auf \u201eNext\u201c geht es weiter.<\/p>\n\n\n

    \n
    \"\"<\/a>
    Bildschirmfoto WP fail2ban-Dokumentation. Zeitstempel 2023-06-04T21:04+02<\/figcaption><\/figure>\n<\/div>\n\n\n

    Hier steht im Wesentlichen, dass Nutzer, welche sich bereits auskennen, zum n\u00e4chsten Abschnitt gehen k\u00f6nnen. Leider finden sich f\u00fcr neue Nutzer hier kaum brauchbare Informationen. Der Hinweis, die Datei wp-config.php<\/code> zu sichern, bevor man diese bearbeitet, ist nett, mehr nicht. Es wird erw\u00e4hnt, dass die freie (im Sinne von Freibier) Version des Plugins durch Definition von Konstanten in der Datei wp-config.php<\/code> konfiguriert wird. Wie so eine Konstante aussieht oder wo man weiterf\u00fchrende Informationen dazu findet, steht hier nicht. Ich habe an dieser Stelle entsprechende Hinweise erwartet. Gut, ich kann ja noch auf \u201eNext\u201c klicken.<\/p>\n\n\n

    \n
    \"\"<\/a>
    Bildschirmfoto WP fail2ban-Dokumentation, Abschnitt Logging. Zeitstempel 2023-06-04T21:14+02<\/figcaption><\/figure>\n<\/div>\n\n\n

    Auch in diesem Abschnitt findet sich keine Information, was man nun mit der Datei wp-config.php<\/code> soll. Immerhin gibt es in Abschnitt 4.2.1. einen Link, der Nutzer, welche nicht mit der Konfiguration vertraut sind, zur Konfigurationsanleitung f\u00fchren soll. Ich habe ein D\u00e9ja Vu und f\u00fchle mich langsam ver\u2026hohnepiepelt. Also klicke ich auf den n\u00e4chsten LInk. Es hei\u00dft ja schlie\u00dflich: \u201eWas lange w\u00e4hrt, wird endlich gut.\u201c<\/p>\n\n\n\n

    TL;DR: Auch auf der n\u00e4chsten Seite erfahren wir nichts \u00fcber die wp-config.php<\/code>.<\/p>\n\n\n

    \n
    \"\"<\/a>
    Bildschirmfoto der URL: https:\/\/docs.wp-fail2ban.com\/en\/5.0\/configuration\/fail2ban.html#configuration-fail2ban. Zeitstempel 2023-06-04T21:21+02<\/figcaption><\/figure>\n<\/div>\n\n\n

    Zur Erinnerung: Ich nutze die freie Version des Plugins WP fail2ban, welches angeblich durch die Definition von Konstanten in der Datei wp-config.php<\/code> konfiguriert wird. Welche Konstanten dies sind und wie man diese konfiguriert, wird auch auf Seite 4 immer noch nicht mit einem Wort erkl\u00e4rt.<\/p>\n\n\n\n

    Stattdessen lernt man in Abschnitt \u201e4.3.1.1. Typical Settings\u201c, dass die Dateien wordpress-hard.conf<\/code> und wordpress-soft.conf<\/code> in das Verzeichnis fail2ban\/filters.d<\/code> zu kopieren sind. Hier wurden in meinen Augen zwei Fehler gemacht:<\/p>\n\n\n\n

      \n
    1. Es wird nicht erw\u00e4hnt, wie man die Dateien wordpress-,{hard,soft}.conf<\/code> erh\u00e4lt bzw. erstellt. Als unerfahrener Nutzer strandet man hier. Zum Gl\u00fcck hatte ich mir das damals aufgeschrieben<\/a>.<\/li>\n\n\n\n
    2. Es wird eine relative Pfadangabe fail2ban\/filters.d<\/code> genutzt. Dies ist nicht ganz so wild, ich pers\u00f6nlich bevorzuge es, wenn vollst\u00e4ndige Pfadangaben genutzt werden, damit Nutzer das entsprechende Verzeichnis sicher finden.<\/li>\n<\/ol>\n\n\n\n

      Fazit<\/h2>\n\n\n\n

      Eine Dokumentation sollte die notwendigen Informationen bereitstellen, mit denen auch neue Nutzer eine Anwendung installieren und konfigurieren k\u00f6nnen. Dies ist nicht so leicht, wie es auf den ersten Blick erscheint, leiden Autoren, welche die Anwendung bereits kennen, doch h\u00e4ufig unter Betriebsblindheit und k\u00f6nnen sich nur schwer in die Rolle des unerfahrenen Nutzers versetzen.<\/p>\n\n\n\n

      Wenn ich selbst Dokumentationen schreibe, gebe ich diese meist Kolleginnen und Kollegen zu lesen und arbeite deren R\u00fcckmeldungen mit ein. Dies hat in der Vergangenheit zu deutlich besseren Ergebnissen gef\u00fchrt.<\/p>\n\n\n\n

      Die hier kritisierte Dokumentation ist ein Beispiel daf\u00fcr. Sie befindet sich damit leider in guter Gesellschaft im Internet.<\/p>\n\n\n\n

      Ohne meinen Eingangs erw\u00e4hnten Artikel hier im Blog w\u00e4re ich nicht in der Lage gewesen, mir dieses Plugin wieder einzurichten. Nun werde ich einige Tage pr\u00fcfen, ob es wie erhofft arbeitet und dann ggf. einen Merge-Request mit einigen Verbesserungsvorschl\u00e4gen einreichen.<\/p>\n\n\n\n

      Fragen an meine Leserinnen und Leser<\/h2>\n\n\n\n

      Wie steht ihr zu Dokumentation? Ist das eher etwas f\u00fcr alte wei\u00dfe M\u00e4nner mit grauen B\u00e4rten? Oder w\u00fcnscht ihr euch ebenfalls belastbare und ausf\u00fchrliche Dokumentationen zu den von euch verwendeten Anwendungen?<\/p>\n\n\n\n

      Tragt ihr selbst zu Dokumentationen bei? Welche Erfahrungen habt ihr dabei gemacht? Welche Tipps k\u00f6nnt ihr Schreiberlingen geben, die ihr Projekt dokumentieren m\u00f6chten?<\/p>\n\n\n\n

      Bitte hinterlasst mir eure Antworten in den Kommentaren oder im Chat<\/a>.<\/p>\n","protected":false},"excerpt":{"rendered":"

      WP fail2ban ist ein Plugin zum Schutz von WordPress-Installationen vor Brute-Force-Angriffen. Installation und Konfiguration habe ich bereits im Artikel WordPress mit Fail2Ban vor Brute-Force-Angriffen sch\u00fctzen dokumentiert. Dieser Text besch\u00e4ftigt sich mit der offiziellen Dokumentation des Plugins, bzw. dem Text, der sich als Dokumentation ausgibt. Ich stelle hier meine Erwartung an eine Dokumentation heraus, zeige die [Weiterlesen…]<\/a><\/span><\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_metis_text_type":"","_metis_text_length":0,"_post_count":0,"footnotes":""},"categories":[67],"tags":[669,668],"class_list":["post-3524","post","type-post","status-publish","format-standard","hentry","category-wordpress","tag-fail2ban","tag-wp-fail2ban"],"_links":{"self":[{"href":"https:\/\/www.my-it-brain.de\/wordpress\/wp-json\/wp\/v2\/posts\/3524","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.my-it-brain.de\/wordpress\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.my-it-brain.de\/wordpress\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.my-it-brain.de\/wordpress\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.my-it-brain.de\/wordpress\/wp-json\/wp\/v2\/comments?post=3524"}],"version-history":[{"count":2,"href":"https:\/\/www.my-it-brain.de\/wordpress\/wp-json\/wp\/v2\/posts\/3524\/revisions"}],"predecessor-version":[{"id":3531,"href":"https:\/\/www.my-it-brain.de\/wordpress\/wp-json\/wp\/v2\/posts\/3524\/revisions\/3531"}],"wp:attachment":[{"href":"https:\/\/www.my-it-brain.de\/wordpress\/wp-json\/wp\/v2\/media?parent=3524"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.my-it-brain.de\/wordpress\/wp-json\/wp\/v2\/categories?post=3524"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.my-it-brain.de\/wordpress\/wp-json\/wp\/v2\/tags?post=3524"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}