update
update | |
---|---|
Zweck / Funktion | |
Befehl zur Aktualisierung der FHEM-Installation | |
Allgemein | |
Typ | Befehl |
Details | |
Dokumentation | EN / DE |
Support (Forum) | Sonstiges |
Modulname | 98_update.pm |
Ersteller | rudolfkoenig (Forum / Wiki) |
Wichtig: sofern vorhanden, gilt im Zweifel immer die (englische) Beschreibung in der commandref! |
update ist ein Befehl zur Aktualisierung der FHEM-Installation direkt über das FHEM Webfrontend. Von den Entwicklern bis zu einem bestimmten Zeitpunkt freigegebene Änderungen sind jeweils morgens ab 8:00 Uhr über die Update Funktion verfügbar. Änderungen, die später freigegeben werden, werden dementsprechend erst am nächsten Tag verfügbar.
Syntax
update [<fileName>|all|check|force] [http://.../controlfile]
oder
update [add source|delete source|list|reset]
Hinweise:
- FHEM sichert mit den Standardeinstellungen während des Updates "nur" die aktualisierten Modul(Installations-)dateien und bei Standardinstallationen (Beitrag) ab Updatestand 29.10.2016 die Konfiguration und fhem.save, aber beispielsweise nicht Plots oder FileLogs. Soll vor dem Update ein vollständiges Backup von FHEM erstellt werden, muss das mit dem Attribut
backup_before_update
eingeschaltet werden. - Lesen Sie aufmerksam die nach dem Update auf dem Monitor erscheinenden Meldungen zu Neuerungen und Änderungen.
- Nach einem Update ist immer ein shutdown restart erforderlich.
- geänderte und neu eingecheckte Module werden grundsätzlich erst am Folgetag ab ca. 8.00 Uhr durch den Update-Befehl verteilt.
- Mit dem Befehl version lässt sich die Version einzelner oder aller benutzten Module bestimmen.
Parameter
Details zu Parametern des update Befehls:
Standardaufrufe
update
Die ganze FHEM-Installation wird auf die neueste Version gebracht. Vorhandene Module werden akualisiert und neue Module installiert.
update check
Es werden alle Module aufgelistet, von denen eine neuere als die bereits installierte Version verfügbar ist. Es wird nicht installiert.
update force
Das Update wird erzwungen (falls es beim regulären update Probleme geben sollte). Dieser Befehl ist nur mit Bedacht und ausschließlich im Notfall einzusetzen. Sollte ein reproduzierbares Problem existieren, dies bitte im FHEM-Forum berichten, damit dem nachgegangen werden kann.
update <Dateiname>
Mit z.B. update 02_HTTPSRV.pm
wird nur von der Datei 02_HTTPSRV.pm eine neue Version installiert. Alle anderen FHEM-Dateien werden nicht angetastet.
update all
Alle offiziellen Module von FHEM sind in einem gemeinsamen Repository gespeichert. Nur diese Module werden in der Standardeinstellung durch den update-Befehl mit den bisher aufgeführten Standardaufrufen aktualisiert bzw. installiert. Einige Entwickler stellen ihre Module jedoch aus verschiedensten Gründen nicht im gemeinsamen Repository zur Verfügung, sondern nutzen eigene, separate Repositorys. Diese sogenannten "Thirdparty-Module" (auch bezeichnet als inoffizielle Module) können ebenfalls über update installiert und aktualisiert werden, wenn der Entwickler eine sogenannte Kontrolldatei (controlfile) in seinem Repository zur Verfügung stellt.
Zur Installation bzw. Update jedes einzelnen Thirdparty-Moduls ist nachfolgender Befehl aufzurufen (Webadresse und Kontrolldateiname sind modulabhängig passend zu ersetzen):
update all http://thirdparty.com/controls_funnymodule.txt
Die in den vorherigen Abschnitten erläuterten Standardaufruf (bis auf update
) können durch Ergänzung um Webadresse und Kontrolldateiname (http://.../controlfile beim Befehls-Aufruf für das Update von einzelnen Thirdparty-Modulen genutzt werden.
Repository-Verwaltung
In den Standardeinstellungen von FHEM ist für jedes einzelne Repository ein separater Aufruf der Standardaufrufe zur Aktualiserung/Installation notwendig. Zur Vereinfachung des Update-Prozesses hat der update-Befehl eine eingebaute Repository-Verwaltung. Mittels der Repository-Verwaltung lassen sich die Standardaufrufe so beeinflussen, dass mit einem einzigen Aufruf sowohl die Module aus dem FHEM-Repository als auch aus verschiedenen Thirdparty-Repositorys beim Update berücksichtigt werden.
update add
Fügt ein zusätzliches Repository zur vereinfachten Nutzung über die Standardaufrufe hinzu. Ein Aufruf von update <Dateiname>|all|check|force
berücksichtigt dann automatisch neben dem FHEM-eigenen Repository auch das hinzugefügte "Thirdparty-Repository".
Nach dem Hinzufügen durch beispielsweise update add http://thirdparty.com/controls_funnymodule.txt
entfällt somit der manuelle Aufruf der Form update all http://thirdparty.com/controls_funnymodule.txt
zur Aktualiserung. Er kann aber weiterhin genutzt werden, um ausschließlich für ein bestimmtes Repository ein Update zu erhalten und und nicht für alle.
Die Liste der Repositorys wird in der Verwaltungsdatei FHEM/controls.txt gespeichert.
update delete
Entfernt eine Repository aus der Verwaltungsdatei.
update list
Listet alle in der Verwaltungsdatei enthaltenen Repositorys auf.
update reset
Entfernt alle Fremd-Repositorys aus der Verwaltungsdatei. Nur das eigene Repository von FHEM wird noch von den Standardparametern berücksichtigt.
Syntax controlfile
Das Controlfile für thirdparty Module unterliegt einer festen Syntax. In jeder Zeile steht ein Dateiname und ein Befehl, was damit passieren soll. Ein Zeilenumbruch wird durch ein \n dargestellt.
Es können drei Befehle verwendet werden: CRE, MOV und UPD.
CRE - Anlegen einer Datei
Hiermit können vom Entwickler Dateinamen festgelegt und entsprechende Initial-Dateien verteilt werden; der Inhalt der Datei liegt nach dem ersten Verteilen in Anwenderhänden (z.B. nützlich bei *-user.css-Dateien).
CRE <Datum> <Dateigröße> <Datei inkl. Pfad>
Das Anlegen wird nur ausgeführt, wenn
- die Datei noch nicht vorhanden ist.
MOV - Verschieben oder Umbenennen einer Datei
MOV <Quelldatei inkl. Pfad> <Zieldatei inkl. Pfad>
Da Dateien nicht vollständig gelöscht werden können, kann eine Datei mit dem MOV Befehl in einen speziellen Ordner namens "unused" verschoben werden:
MOV <Quelldatei inkl. Pfad> unused
UPD - Aktualisieren einer Datei
UPD <Datum> <Dateigröße> <Datei inkl. Pfad>
Die Aktualisierung wird nur ausgeführt, wenn
- das Datum der lokalen Datei sich vom Datum der Update-Datei unterscheidet.
- die Dateigröße der Update-Datei mit der Dateigröße im UPD Eintrag übereinstimmt.
Beispiel:
UPD 2018-10-04_20:17:35 55143 FHEM/55_MyFirstFile.pm
UPD 2018-09-27_23:26:21 17121 FHEM/55_MySecondFile.pm
Beispiel für die Erzeugung der UPD Einträge:
#!/usr/bin/perl
use File::Basename;
use POSIX qw(strftime);
use strict;
my @filenames = ( "55_MyFirstFile.pm",
"55_MySecondFile.pm");
my $prefix = "FHEM";
my $filename = "";
foreach $filename (@filenames)
{
my @statOutput = stat($prefix."/".$filename);
if (scalar @statOutput != 13)
{
printf("error: stat has unexpected return value for ".$prefix."/".$filename."\n");
next;
}
my $mtime = $statOutput[9];
my $date = POSIX::strftime("%Y-%m-%d", localtime($mtime));
my $time = POSIX::strftime("%H:%M:%S", localtime($mtime));
my $filetime = $date."_".$time;
my $filesize = $statOutput[7];
printf("UPD ".$filetime." ".$filesize." ".$prefix."/".$filename."\n");
}
Attribute
Zur weiteren Beeinflussung der Funktionsweise des update Befehls können Attribute verwendet werden. Diese müssen für das Objekt global gesetzt werden, also mit einem Konfigurationsbefehl der Art
attr global ...
backup_before_update
siehe auch backup
restoreDirs
siehe Rücksichern beim Update überschriebener Dateien
exclude_from_update
Mit der Definition
attr global exclude_from_update ...
kann eine Liste von Dateien spezifiziert werden, die bei der Ausführung des update Befehls nicht aktualisiert werden sollen. Dateien können auch über reguläre Ausdrücke definiert werden, die einzelnen Einträge werden durch Leerzeichen voneinander getrennt.
Einen Spezialfall stellt die commandref dar, die seit einer Modifikation des Update Prozesses (März 2015, beschrieben in dieser Forendiskussion) nicht mehr heruntergeladen wird, sondern auf dem Benutzersystem durch Extraktion der Dokumentation aus den einzelnen Modulen generiert wird, angezeigt durch die Meldung im fhem.log:
- Calling /usr/bin/perl ./contrib/commandref_join.pl, this may take a while.
Sollte dieser Prozess (z.B. auf einem langsamen Rechner) zu lange dauern, bleibt die Meldung
- update finished, "shutdown restart" is needed to activate the changes.
aus. Wird commandref in das exclude_from_update
Attribut eingetragen, entfällt dieser Schritt, die lokale commandref wird allerdings dann auch nicht mehr aktualisiert. Die modulspezifische Hilfe, die z.B. über help modulname
aufgerufen werden kann, ist davon nicht betroffen.
Anwendungsbeispiel / Problembehebung
Durchführung eines Updates
Zunächst kann mit dem Befehl
update check
überprüft werden, ob es überhaupt ein neues Update gibt und welche Dateien hierbei ausgetauscht würden (die angezeigten Infos sollten in einer Textdatei gesichert werden. Mit diesen Infos kann gezielter nach Problemen, die vielleicht nach einem Update auftreten, gesucht werden). Anschließend kann mittels:
update
das Update eingespielt werden. Hierbei ist zu beachten, dass die Befehle auf der FHEM Webseite oben (Befehls-Eingabefeld) eingegeben werden und anschließend die "Enter" Taste auf der Tastatur gedrückt werden muss.
Gibt es kein Update für FHEM, sieht die Ausgabe z.B. nach "update check" wie folgt aus:
List of new / modified files since last update:
nothing to do...
Rücksichern beim Update überschriebener Dateien
Sollte nach einem update etwas ganz oder teilweise nicht mehr funktionieren, kann man auf den Stand vor dem Update zurückgehen. Die Befehle sind für die FHEM Kommandozeile.
Man kann sich einen Überblick über die Funktion des Befehls restore verschaffen:
help restore
Man kann die gesicherten Versionen listen
restore list update
Available for restore in update:
2020-11-01
Man kann in der Verzeichnis Ebene tiefer suchen
restore list update/2020-11-01
Available for restore in update/2020-11-01:
CHANGED
FHEM
MAINTAINER.txt
configDB.pm
fhem.cfg
fhem.pl
lib
log
Man kann gezielt wiederherstellen, entweder den kompletten Pfad oder einzelne Dateien.
restore update/2020-11-01/FHEM
restore update/2020-11-01/FHEM/10_CUL_HM.pm
Weitere Informationen:
- Per default werden vor dem Überschreiben durch update alle Dateien in einem neuen Verzeichnis (restoreDir/update/YYYY-MM-DD) gesichert.
- Mit dem restoreDirs Attribut kann man die Anzahl der aufgehobenen Sicherungen (== Datum-Verzeichnisse) bestimmen, die Voreinstellung ist 3. Mit 0 kann man das Feature komplett abschalten.
- Ab Updatestand 29.10.2016 können bei Standardinstallationen (Beitrag) die fhem.cfg und fhem.save mit der Option -a des restore-Befehl wiederhergestellt werden.
- Zu Neuerungen ab Updatestand 18.03.2018 siehe Beitrag.
Update ging schief - restore letzte funktionierende Version
Sollte der Fall eintreten, dass FHEM nach dem Update nicht mehr startet, kann das restore des letzten Standes auch auf Systemebene durchgeführt werden. Anzeigen der vorhandenen Sicherungen:
ls /opt/fhem/restoreDir/update
Die Pfad-Angabe YYYY-MM-DD durch das gewünschte Datum ersetzen:
sudo -su fhem cp -R /opt/fhem/restoreDir/update/YYYY-MM-DD/* /opt/fhem/
Die Berechtigungen bleiben durch die Verwendung des Users fhem erhalten. Danach sollte sich FHEM normal starten lassen. Im Zweifelsfall ist ein reboot des Systems die einfachste Lösung.
Einzelne Dateien aus dem SVN holen
Manchmal wird im Forum die Empfehlung gegeben: Die Fehler-bereinigte Datei bitte direkt aus dem SVN holen. Dies kann mit der Perlfunktion { Svn_GetFile('from SVN Path', 'to local Path') } direkt in der FHEM Kommandozeile erfolgen, hier ein paar Beispiele:
{ Svn_GetFile('FHEM/DevIo.pm', 'FHEM/DevIo.pm') }
{ Svn_GetFile('contrib/86_FS10.pm', 'FHEM/86_FS10.pm') }
{ Svn_GetFile('fhem.cfg', 'minimal.cfg') }
Wie man sieht, kann man sich damit auch aktuelle Dateien aus dem SVN contrib Pfad in den lokalen FHEM Pfad holen. Der lokale contrib Pfad wird beim update NICHT aktualisiert und befindet sich damit immer auf dem Stand der Erstinstallation!