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.

API Versionen Popup

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.

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 "./" 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.

Upload Historie

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.