selfhost-updater/selfhost-updater.README

---------------------------------------
 README f<>r den selfhost.de-IP-Updater
---------------------------------------

* Wird die neueste Version eingesetzt? -> 20181020

* Bei Fragen hilft die Mailingliste:

  Abonnieren: Einfach eine leere E-Mail senden an:
    selfhost-subscribe@jonaspasche.de

  Abbestellen: Einfach eine leere E-Mail senden an:
    selfhost-unsubscribe@jonaspasche.de

  In beiden F<>llen kommt erst noch eine R<>ckfragemail, nach deren Beantwortung
  man die Liste abonniert oder abbestellt hat.

  An die Liste schreiben:
    selfhost@jonaspasche.de

  Die E-Mail wird umgehend verteilt (keine Moderation); auch der Absender
  erh<72>lt seine eigene E-Mail selbst, da er ja auch Listenempf<70>nger ist.

  Bitte keine Anfragen zu "Wie mache ich das mit der crontab" - das hat nichts
  mit dem selfhost-updater zu tun, sondern mit der zugrundeliegenden Linux-
  Distribution, deren Dokumentation ausf<73>hrlich die Funktion von crontabs
  erkl<6B>ren sollte.

* Ein Wort zum Support...

  Obwohl die Entwicklung des selfhost-updater f<>r Linux von selfhost.de
  als Auftragsarbeit initiiert wurde, handelt es sich nicht um ein offizielles
  Produkt von selfhost.de (genausowenig wie beispielsweise die Windows-Clients
  im Download-Bereich). Insofern wird Support f<>r den selfhost-updater auch
  _nicht_ von selfhost.de selbst geleistet, sondern von mir (dem Entwickler)
  und den vielen anderen Benutzern dieses Tools.

  Der selfhost-updater wird unter einer freien Lizenz (GPL) zur Verf<72>gung
  gestellt; eine Haftung ist somit in jedem Fall ausgeschlossen. Gleichzeitig
  bedeutet das auch, dass er z.B. f<>r eigene Zwecke angepasst werden kann.
  Die Weitergabe von angepassten Versionen ist jedoch nur gestattet, wenn diese
  selbst wieder der GPL unterliegen.

  Wie bei freier Software <20>blich, wird der Support per Mailingliste geleistet.
  Das hat viele Vorz<72>ge: Zum einen kann jeder zur Probleml<6D>sung beitragen,
  auch wenn ich, der Entwickler, pers<72>nlich einmal nicht verf<72>gbar sein sollte.
  Zum anderen profitieren alle Mailinglisten-Teilnehmer auch durchs Mitlesen
  schon von den Fragen und Antworten anderer. So sind auch schon einige Ideen
  und Anregungen entstanden, die in den selfhost-updater eingeflossen sind.
  Last but not least geht es auch ein bi<62>chen um's Geben und Nehmen: Wer heute
  vielleicht noch Hilfe in Anspruch nehmen muss, kann morgen vielleich schon
  anderen mal ein bi<62>chen weiterhelfen.

  Also: Bestehen Fragen oder Schwierigkeiten, so stehen die Teilnehmer der
  Mailingliste gerne zur Verf<72>gung. Ich lese und schreibe nat<61>rlich auch auf
  der Mailingliste mit. Au<41>erdem ver<65>ffentliche ich dort Meldungen <20>ber Updates;
  das sollte doch schon Grund genug sein. :-)

  Und f<>r alle, die ein bisschen Angst vor vielen E-Mails haben: Keine Sorge, die
  Liste ist nicht sehr hochvolumig. Au<41>erdem werden E-Mail-Adressen nat<61>rlich
  keinesfalls weitergegeben oder f<>r andere Zwecke genutzt; Ehrensache.

* Das Script liegt unter folgender URL zum Download bereit:

  http://jonaspasche.de/selfhost-updater

  In einem Verzeichnis speichern, das im PATH liegt, z.B. /usr/local/sbin;
  anschlie<69>end Ausf<73>hrungsrechte vergeben.

  Beispiel f<>r eine Installation, hier exemplarisch mit wget:

  su -                                          # um root zu werden
  cd /usr/local/sbin                            # hier soll das Script hin
  wget http://jonaspasche.de/selfhost-updater   # Script herunterladen
  chmod 700 selfhost-updater                    # ausf<73>hrbar machen

  Auf Systemen, auf denen wget nicht zur Verfuegung steht (z.B. MacOS X),
  kann auch cURL verwendet werden:

  curl -O http://jonaspasche.de/selfhost-updater

* Erstkonfiguration:

  (Die spitzen Klammern sollen deutlich machen, dass es sich hier um Variablen
  handelt und d<>rfen nicht mit eingegeben werden!)

  Der DynDNS-Username und das DynDNS-Passwort sind *nicht* die Kundendaten bei 
  selfhost, also *nicht* die Daten, mit der man sich auf der selfhost-Website 
  einloggt. Die erforderlichen Daten k<>nnen in den Details des DynDNS-Accounts 
  eingesehen werden. Hintergrund ist, dass es durchaus mehrere DynDNS-Accounts
  unter einer selfhost-Kundennummer geben kann, und die m<>ssen sich dann 
  nat<61>rlich anhand ihrer Zugangsdaten auch unterscheiden.

  selfhost-updater setusr <dyndns-username>
  selfhost-updater setpwd <dyndns-passwort>
  selfhost-updater setdev <ger<65>tename>

  <ger<65>tename> entspricht dabei dem Ger<65>t, <20>ber das die Internet-Verbindung
  l<>uft, also in der Regel ppp0 oder ippp0. Bei Zugang <20>ber einen Router oder
  wenn das Ger<65>t nicht bekannt ist, ``router'' als Ger<65>t angeben; hierbei
  wird die IP-Adresse dann mit Hilfe eines externen IP-Checkers ermittelt.

* Erster Test:

  selfhost-updater update

  Das Update sollte erfolgreich sein. Wenn nicht, Mailingliste fragen, und
  dabei bitte den vollst<73>ndigen Output des Programms mitschicken (copy+paste)

* Wenn "router" als Ger<65>t gesetzt ist, aber beim ersten Aufruf die Ermittlung
  der IP-Adresse fehlschl<68>gt...

  Ein wenig zum Hintergrund: Im Modus "router" benutzt der selfhost-updater
  eine externe URL, um seine eigene IP-Adresse zu erfahren. Dabei stehen
  mehrere wechselnde URLs zur Verf<72>gung, die von selfhost.de nach einem Update
  <20>bermittelt werden. Im Script voreingestellt ist eine Default-URL, die man
  benutzen kann, wenn die "richtige" Liste der IP-Check-URLs noch nicht ver-
  f<>gbar ist - also nur beim allerersten Aufruf des Scripts. Sollte die URL
  des IP-Checkers just bei diesem ersten Aufruf allerdings einmal offline sein,
  so ist das nat<61>rlich problematisch.

  Abhilfe:

  Einfach ein Update durchf<68>hren, bei dem die IP-Adresse manuell angegeben wird,
  z.B. "selfhost-updater update 1.2.3.4". Damit wird die automatische <20>bermitt-
  lung <20>bergangen, sprich, man braucht keinen IP-Checker. Mit der Best<73>tigung
  des Updates erh<72>lt man dann die _aktuellen_ URLs der IP-Checker, die derzeit
  verf<72>gbar sind und kann dann also unmittelbar danach ein normales Update mit
  "selfhost-updater update" durchf<68>hren. Die automatische Ermittlung der IP
  sollte dabei dann funktionieren.

* "...es trat ein tempor<6F>rer Fehler auf", oder allgemein:
* SSL wird vom verwendeten Tool nicht unterst<73>tzt:

  Der selfhost-updater arbeitet seit der Version 20020106 von Haus aus mit
  SSL. Wenn das verwendete Tool (z.B. lynx) jedoch kein SSL unterst<73>tzt,
  kann jedoch das Update-CGI-Script nicht aufgerufen werden. Da der
  selfhost-updater in diesem Fall keine R<>ckmeldung bekommt, geht er von
  einem tempor<6F>ren Fehler aus. Wer diese Meldung also dauerhaft erh<72>lt,
  sollte einmal versuchen, den SSL-Support auszuschalten, in dem er die
  Umgebungsvariable NOSSL setzt:

  NOSSL=1 selfhost-updater update

  In diesem Fall wird wie bisher die unverschl<68>sselte URL benutzt.

* lynx unterst<73>tzt den SSL-Modus nicht korrekt, obwohl es SSL kann

  Tests haben gezeigt, dass einige lynx-Versionen eine Pr<50>fung des Zertifikats
  durchf<68>hren. Im interaktiven Modus von lynx wird dann nachgefragt, ob das
  Zertifikat akzeptiert werden soll; im Shell-Modus wird eine fehlgeschlagene
  Pr<50>fung ohne aussagekr<6B>ftige Fehlermeldung als Fehler dargestellt.

  Um lynx allgemein die Pr<50>fung von Zertifikaten abzugew<65>hnen (funktioniert
  einfach, ist aber nicht empfohlen, wenn Sie lynx noch zu anderen Zwecken
  benutzen), tragen Sie in /etc/lynx-site.cfg ein:

  FORCE_SSL_PROMPT:NO

  Alternativ k<>nnen Sie das benutzt Root-Zertifikat von GeoTrust in Ihren
  lokalen Zertifikatsspeicher installieren. Laden Sie es sich von dieser URL
  herunter:

  https://www.geotrust.com/resources/root_certificates/certificates/Equifax_Secure_Global_eBusiness_CA-1.cer

  Um es in den Zertifikatsspeicher zu kopieren, f<>gen sie einfach den Inhalt
  dieser Datei an den bestehenden Zertifikatsspeicher an. Unter Fedora Linux
  findet er sich beispielsweise in /usr/share/ssl/cert.pem. Bei anderen Distri-
  butionen kann er auch woanders liegen.

  Hinweis: Die meisten aktuellen _grafischen_ Browser unterst<73>tzen das
  Root-Zertifikat von GeoTrust direkt, allerdings ist es nicht bei allen
  Distributionen auf im von lynx genutzten Zertifikatsspeicher vorhanden,
  wodurch obiges Problem auftritt.

* Bestimmten Web-Client benutzen

  Der selfhost-updater ermittelt automatisch, ob wget, lynx oder links vorhanden
  sind (in dieser Reihenfolge). Wer einen bestimmten Web-Client verwenden will,
  kann dessen Namen in /etc/selfhost/tool hinterlegen, z.B. "lynx" - hier wird
  dann die automatische Ermittlung <20>bergangen und lynx benutzt, auch wenn wget
  auf dem System installiert ist.

* Wenn alles klappt: Einen Cron-Job einrichten, der das Tool periodisch aufruft.

  Beispiel f<>r den Eintrag in einer crontab ("crontab -e" als root):
  */10 * * * * /usr/local/sbin/selfhost-updater update | logger -t selfhost

  Damit wird alle 10 Minuten die IP-Adresse gepr<70>ft und ggf. aktualisiert.
  Die Ausgabe des Scripts wird dabei <20>ber den Befehl "logger" zum syslog-
  Daemon geschickt und findet sich z.B. in der Datei /var/log/messages wieder
  oder allgemein dort, wohin syslog Meldungen der Klasse user.notice schreibt.

  Die genaue Beschreibung der Handhabung von Crob-Jobs w<>rde diese README spren-
  gen; Dokumentation dazu sollte sich aber zum einen im Handbuch der verwendeten
  Linux-Distribution und zum anderen auf der manpage ("man crontab") finden.

* Benachrichtigungsmeldungen vom selfhost-updater

  Wer gerne nicht nur ein Logfile haben m<>chte, sondern automatisch eine
  E-Mail bekommen will, wenn ein erfolgreiches Update lief oder ein Update
  fehlschlug, kann die gew<65>nschte E-Mail-Adresse in /etc/selfhost/notify
  setzen und wird dann automatisch benachrichtigt. Daf<61>r muss das Programm
  "mail" auf dem Linux-Rechner installiert sein, und ein Mailserver die
  Mail auch nach drau<61>en schicken k<>nnen.

  Wichtig: Hier bitte m<>glichst _NICHT_ eine Adresse auf dem DynDNS-Host
  angeben. Nach einem Update braucht's noch einen Augenblick, bis die neue
  IP online ist, und vor allem Fehlermeldungen <20>ber Fehler beim Updaten
  von meinhost.selfhost.de lassen sich nicht wirklich gut an die Adresse
  info@meinhost.selfhost.de zustellen (es sei denn, der Mailserver l<>uft
  auf dem gleichen Rechner).

* Update auf bestimmte IP-Adresse (ohne automatische Ermittlung):

  Unter bestimmten Umst<73>nden kann es praktisch sein, manuell die IP-Adresse
  festzulegen, die beim Update verwendet werden soll. Die automatische
  Ermittlung wird in diesem Fall <20>bergangen. Und so geht's:

  selfhost-updater update <ip-adresse>

* Update erzwingen:

  Das Script speichert seine aktuelle IP in /etc/selfhost/ip - wenn die
  aktuell gefundene mit der dort gespeicherten <20>bereinstimmt, wird kein
  Update veranla<6C>t. Wer eins erzwingen will, braucht nur diese Datei zu
  l<>schen und erneut ein Update zu starten.

  Achtung, selfhost.de l<><6C>t aus Sicherheitsgr<67>nden nur eine begrenzte
  Anzahl von Updates in einem Zeitraum zu. Es kann also sein, dass ein
  Host f<>r einige Minuten gesperrt wird, wenn er zuviele Updates an
  selfhost.de sendet. Bei krassen F<>llen (hunderte von Updates...) kann
  auch eine Sperrung bis zum n<>chsten Tag erfolgen. Diese kann jedoch
  auch vorzeitig im Web-Konfigurationsmen<65> von selfhost.de entsperrt
  werden. In eigenem Interesse sollte man aber zuerst schauen, was die
  Ursache f<>r derart viele Updates war.

* Server offline schalten:

  selfhost-updater offline

  Damit wird der dynamische DNS-Eintrag auf die IP-Adresse von selfhost
  geschaltet, wo eine Offline-Meldung hinterlegt ist. Macht sich z.B. gut
  in if-down.local, um den DNS-Eintrag offline zu schalten, wenn der Server
  heruntergefahren wird.

* Auswahl ob IPv4 oder IPv6 Adresse aktualisiert werden soll
  
  In der Konfigurationsdatein ipversion kann eingestellt werden, ob die
  IPv4 oder die IPv6 Adresse aktualisiert werden soll. 
  Zwei Angaben in der Datei sind als einzelner Wert m<>glich: "IPv4" oder
  "IPv6".
  Die Einstellung konkurriert mit der Angabe "router" als Device. Die Angabe
  "router" meint tats<74>chlich ausschlie<69>lich die Adresse des Routers, 
  nicht etwa des Servers hinter einem Router. Es wird automatisch eine
  IPv4 Adresse bei Selfhost aktualisiert, auch wenn die IP-Version auf
  "IPv6" lautet. Dies m<>sste in der Programmierung erst abgefragt werden.
  Stattdessen wird eine IPv6 Adresse an Selfhost gemeldet, wenn die Angabe
  in der Datei "device" nicht "router" hei<65>t.
  Bei der Ermittlung der IP-Adresse wird darauf geachtet, dass keine ULA an
  Selfhost gemeldet wird, sondern die globale IPv6.

* Mehrere Accounts verwenden:

  Die Konfiguration wird standardm<64><6D>ig in /etc/selfhost gespeichert. Dies
  kann jedoch <20>ber die Umgebungsvariable CONFIGDIR ge<67>ndert werden. Der
  Aufruf sieht dann wie folgt aus:

  CONFIGDIR=/etc/mydir selfhost-updater update

  Entsprechend mu<6D> dann auch die Konfiguration f<>r dieses Verzeichnis mit
  der Angabe von CONFIGDIR erfolgen, zum Beispiel:

  CONFIGDIR=/etc/mydir selfhost-updater setdev router

  CONFIGDIR kann hierbei z.B. auch im eigenen home-Verzeichnis liegen, so
  dass der selfhost-updater auch ohne root-Rechte aufgerufen werden kann!

* Wenn sich der selfhost-updater selbst gesperrt hat:

  Wenn selfhost bei einem Update einen Statuscode der Klasse 4xx zur<75>ck-
  liefert, deutet dies auf einen Konfigurationsfehler hin (z.B. Zugangsdaten
  ung<6E>ltig, Domain ist keine DynDNS-Domain, Domain ist noch nicht verf<72>gbar,
  Mahnverfahren), der in jedem Fall eine Analyse und konkrete Fehlerbehebung
  erfordert. Der selfhost-Support und die Mailingliste k<>nnen hier unterst<73>tzen.
  Der selfhost-updater sperrt sich dabei vorerst selbst, um nicht ein fehlerhaftes
  Update nach dem anderen zu selfhost zu schicken.

  Der selfhost-updater entsperrt sich selbst automatisch nach 24 Stunden. Soll
  die Sperre fr<66>her aufgehoben werden, einfach /etc/selfhost/locked l<>schen.

  WICHTIG: Alle Fehler der Klasse 4xx (400-499) deuten IMMER auf einen Konfi-
  gurationsfehler hin. Solche Fehler l<>sen sich (im Gegensatz zu Fehlern der
  Klasse 5xx, die nur tempor<6F>r sind), NIE von alleine.

* Debugging

  Bei Problemen bitte einen Aufruf von "selfhost-updater update" mit DEBUG=1
  durchf<68>hren:

  DEBUG=1 selfhost-updater update

  Hierbei wird sowohl der verwendete Web-Client als auch die aufgerufene URL
  (Passwort ausgeblendet) als auch die vollst<73>ndige R<>ckmeldung des Tools aus-
  gegeben. Bei Problemberichten an die Mailingliste bitte immer diese Ausgabe
  per Copy+Paste mitschicken!

* Autor: Jonas Pasche <mail AT jonaspasche.de>

  Bitte keine Fragen und Problemberichte an mich direkt senden; daf<61>r steht
  die Mailingliste zur Verf<72>gung.