SSFile - Integration der Synology File Station
Das Modul 50_SSFile ist noch in der Entwicklung und kann über den nachfolgenden Download bezogen werden.
Bitte den Befehl so komplett mit den Ausführungszeichen am Anfang und Ende in der FHEMWEB Kommandozeile eingeben:
"wget -qO ./FHEM/50_SSFile.pm https://svn.fhem.de/fhem/trunk/fhem/contrib/DS_Starter/50_SSFile.pm"
Danach FHEM restarten.
FHEM muß aktuell sein, insbesondere die Files im Verzeichnis /opt/fhem/lib/FHEM/SynoModules.
Arbeitsweise
Das Modul SSFile arbeitet mit der Synology File Station zusammen, d.h. das Paket File Station muß auf der Diskstation aktiviert sein. Für die Kommunikation mit der File Station, d.h. um Files/Ordner hoch- bzw. herunterzuladen, wird ein User der Diskstation verwendet. Dieser User muß natürlich die Rechte besitzen um die beabsichtigten Lese- und Schreiboperationen auszuführen.
Alle Operationen des Moduls sind Queue gesteuert. Das bedeutet, alles durchzuführenden Aktivitäten werden zunächst in eine Queue gestellt und danach abgearbeitet. Bei den meisten Befehlen wird die Abarbeitung der Queue implizit gestartet. Aber z.B. die set-Befehle prepareDownload und prepareUpload erstellen lediglich die Queueeinträge. Um die Abarbeitung zu starten, ist in diesen Fällen ein abschließer Befehl
set <Name> startQueue
nötig wenn nicht durch das gesetzte Attribut interval ein regelmäßiger Queue-Start automatisch erfolgt.
Mit diesem Modul sind zum Beispiel regelmäßige Backups des gesamten FHEM-Systems möglich. Auch gezielte Restores von ausgewählten Dateien oder Verzeichnissen ohne Zippen oder Entzippen sind möglich.
Durch die asynchrone Queue-Abarbeitung werden auch Ausfallzeiten der Diskstation toleriert. Ist die Diskstation zum Beipiel im Wartungsmodus oder im Sleep-Mode, bleiben die Einträge in der Queue erhalten und werden abgearbeitet sobald wieder eine Verbindung zur Diskstation hergestellt werden kann.
Das Modul benötigt keinerlei Mounts von freigegebenen Verezichnissen der Diskstation auf dem FHEM-Server. Die Datenverarbeitung erfolgt komplett nicht-blockierend. Dadurch und dass die API-Schnittstelle genutzt wird, dauert die Datenübertragung länger als bei Nutzung von Betriebsystem Kopierkommandos.
Definition
Die Definition ist sehr einfach, z.B.:
define SynFile SSFile 192.168.2.20
Die IP-Adresse ist dabei die Adresse der Synology Diskstation. Sie kann auch ein DNS-Name sein. In diesem Fall bitte auch das globale Attribut dnsServer nicht vergessen zu setzen.
Es kann ebenfalls das https-Protokoll oder ein vom default abweichender Port verwendet werden, z.B.:
define SynFile SSFile 192.168.2.20 9001 https
oder
define SynFile SSFile 192.168.2.20 5010 http
Nach der initialen Definition müssen zunächst die Credentials für die Verbindung zur Synology DS definiert werden:
set <Name> credentials <User> <Passwort>
Sind die Credentials gespeichert, kann die Funktion einfach getestet werden mit dem Befehl:
get <Name> apiInfo
Wird der Login erfolgreich ausgeführt, erscheint nach kurzer Zeit ein Popup mit den aktuell vorhandenen und verwendeten API-Versionen.
Upload von Objekten zur Synology Diskstation (Backup)
Es können ein oder mehrere Files sowie ganze Ordner in einen Zielpfad auf der Synology Diskstation hochgeladen werden. Zum Hochladen stehen zwei Set-Kommandos zur Verfügung:
- Upload
- die angegebenen Files/Ordner werden durch das Modul bewertet und danach der Upload sofort gestartet
- prepareUpload
- die angegebenen Files/Ordener werden durch das Modul bewertet und nur in die interne Queue zur Abarbeitung gestellt.
Erst nach dem Kommando set <Name> startQueue wird die Abarbeitung gestartet. Alternativ kann auch das Attribut interval verwendet werden, was ebenfalls die Queue-Abarbeitung alle X Sekunden automatisch triggert.
Der Zielpfad wird mit dem Argument dest= bestimmt und beginnt immer mit einem auf der Synology angelegten "shared Folder". In dem Zielpfad werden alle Objekte Struktur erhaltend, d.h. inkl. ihrer Quellverzeichnisse gespeichert. Das Verhalten ist mit dem Argument struc= veränderbar.
Benötigte Unterverzeichnisse werden im Standard automatisch im Zielpfad angelegt.
Die generelle Syntax für beide möglichen Upload-Befehle ist:
set <Name> Upload "<File>[,<File>,...]" | "<Ordner>[,<Ordner>,...]" <args>
bzw.
set <Name> prepareUpload "<File>[,<File>,...]" | "<Ordner>[,<Ordner>,...]" <args>
Die hochzuladenden Dateien bzw. Ordner werden durch Komma getrennt angegeben. Files und Ordner können kombiniert im Set-Befehl angegeben werden. Die Arbeitsweise des Upload-Befehls wird durch Argumente (<args>) gesteuert, die kombiniert werden können:
- dest=
- <Ordner>: Zielpfad zur Speicherung der Files im Synology Filesystem (der Pfad beginnnt mit einem shared Folder und endet ohne "/"). Diese Angabe ist verpflichtend. Es können POSIX %-Wildcards als Bestandteil des Zielpfads verwendet werden. Prominente Vertreter sind:
* %d Tag des Monats (01..31)
* %m Monat (01..12)
* %Y Jahr (1970...)
* %H Stunde im 24-Stunden Format (00..23)
* %M die Minute (00..59)
* %S die Sekunde (00..60), (Der Bereich ist bis zu 60, um gelegentliche Schaltsekunden zu ermöglichen)
- ow=
- true: das File wird überschrieben wenn im Ziel-Pfad vorhanden (default), false: das File wird nicht überschrieben
- cdir=
- true: übergeordnete(n) Ordner erstellen, falls nicht vorhanden. (default), false: übergeordnete(n) Ordner nicht erstellen
- mode=
- full: alle außer im Attribut excludeFromUpload angegebenen Objekte werden berücksichtigt (default)
inc: nur neue Objekte und Objekte die sich nach dem letzten Upload verändert haben werden berücksichtigt
- struc=
- true: alle Objekte werden inkl. ihrer Verzeichnisstruktur im Zielpfad gespeichert (default)
false: alle Objekte werden ohne die ursprüngliche Verzeichnisstruktur im Zielpfad gespeichert
Der lokale Pfad zum File bzw. Ordner kann entweder ein absoluter Pfad oder eine relativer Pfad zum FHEM-Wurzelverzeichnis (siehe globales Attribut modpath) sein. Alle Quellen, Files/Ordner, müssen insgesamt in Quotes (") eingeschlossen werden.
Nachfolgend einige Beispiele (Upload kann auch durch pepareUpload ersetzt werden):
- set <Name> Upload "./text.txt" dest=/home/upload
- die Datei "text.txt" aus dem FHEM-Wurzelverzeichnis wird in das Zielverzeichnis "/home/upload" übertragen
- set <Name> Upload "/opt/fhem/old data.txt" dest=/home/upload ow=false
- die Datei "old data.txt" im Verzeichnis "/opt/fhem" wird nach "/home/upload/opt/fhem" übertragen sofern sie dort noch nicht existiert
- set <Name> Upload "./log" dest=/home/upload mode=inc
- die Dateien im Verzeichnis "log" des FHEM-Wurzelverzeichnisses werden nach "/home/upload/log" inkrementell übertragen
- set <Name> Upload "./log" dest=/home/upload mode=full struc=false
- die Dateien im Verzeichnis "log" des FHEM-Wurzelverzeichnisses werden nach "/home/upload" übertragen unabhängig davon ob sie seit der letzten Übertragung geändert wurden
- set <Name> Upload "./log" dest=/home/upload/%Y_%m_%d_%H_%M_%S mode=full struc=false
- wie voriges Beispiel. Der Zielpfad wird dynamisch mit dem aktuellen Datum + Uhrzeit ergänzt
- set <Name> Upload "./" dest=/home/upload mode=inc
- die Dateien des gesamten FHEM-Systems werden nach "/home/upload" inkrementell Struktur erhaltend übertragen
- set <Name> Upload "/opt/fhem/fhem.pl,./www/images/PlotToChat.png,./log/fhem-2020-10-41.log" dest=/home/upload
- nur die angegebenen Dateien werden nach "/home/upload/<entsprechendes Unterverzeichnis>" übertragen
Informationen über den Uploadstatus
Das Reading QueueLength enthält die Anzahl der in der Queue befindlichen Befehle. Hier werden nicht nur Upload-Befehle berücksichtigt, sondern sämtliche noch offene (oder mit Fehlerstatus behaftete) Einträge.
Wird der Upload ausgeführt, erfolgt ein permanentes Herunterzählen dieses Readings bis auf "0" im Idealfall. Sollte nach Abarbeitung von Befehlen das Reading QueueLength noch den Wert größer "0" haben, konnten nicht alle Befehle abgearbeitet werden. Sätze mit permanenten Fehlerstatus werden zukünftig von der Abarbeitung ausgenommen, andere Einträge mit einem zeitlichen Versatz wiederholt. Zum Beispiel wenn die Synology Diskstation zum Zeitpunkt des Uploads down war.
Die Ergebnisse der Uploads wird in einer internen Datenabank gespeichert. Man kann sich die Upload-Historie ausgeben lassen mit dem Befehl:
set <Name> listUploadsDone
Die Übersicht zeigt die übertragenen Quelldateien mit ihrem Ursprungspfad, dem Zielpfad sowie das Datum + Zeit der Übertragung. Diese Informationen bleiben auch nach einem FHEM Restart erhalten und sind die Grundlage für die Bewertung einer inkrementellen Übertragung.
Die Historie kann bei Bedarf gelöscht werden mit:
set <Name> deleteUploadsDone
Die auf der Synology gespeicherten Files werden durch diesen Befehl aber nicht gelöscht.
Beschränkungen und Known Bugs
- es werden bei Upload/prepareUpload nur Dateien/Verzeichnisse berücksichtigt deren Name kein @ beinhaltet.