Quelltext der Seite SSFile - Integration der Synology File Station

Das Modul 50_SSFile wird ab dem 26.05.2021 offiziell per Update verteilt.

Die aktuelle Entwicklungsversion bzw. Testmodulversion  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:

<pre>
 "wget -qO ./FHEM/50_SSFile.pm https://svn.fhem.de/fhem/trunk/fhem/contrib/DS_Starter/50_SSFile.pm"
</pre>

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 Verzeichnissen der Diskstation auf dem FHEM-Server. Die Datenverarbeitung erfolgt komplett nicht-blockierend. Da die API-Schnittstelle genutzt wird, dauert die Datenübertragung länger als bei der 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.

[[Datei:ssfile1.PNG|right|thumb|300px|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 Dateien, sowie ganze Ordner in einen Zielpfad auf der Synology Diskstation hochgeladen werden.
Zum Hochladen stehen zwei Set-Kommandos zur Verfügung:

; Upload: die angegebenen Dateien/Ordner werden durch das Modul bewertet und danach der Upload sofort gestartet

; prepareUpload: die angegebenen Dateien/Ordener werden durch das Modul bewertet und nur in die interne Queue zur Abarbeitung gestellt.<br> Erst nach dem Kommando '''set <Name> startQueue''' wird die Abarbeitung gestartet. Alternativ kann auch das Attribut '''interval''' verwendet werden. Das triggert ebenfalls die Queue-Abarbeitung alle X Sekunden automatisch.



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 strukturerhaltend, 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. Dateien 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 Dateien im Synology Dateisystem (der Pfad beginnnt mit einem shared Folder und endet ohne "/"). Diese Angabe ist verpflichtend. Es können [https://metacpan.org/pod/POSIX::strftime::GNU POSIX %-Wildcards] als Bestandteil des Zielpfads verwendet werden. Prominente Vertreter sind:<br><br> * %d Tag des Monats (01..31)<br> * %m Monat (01..12)<br> * %Y Jahr (1970...)<br> * %H Stunde im 24-Stunden Format (00..23)<br> * %M die Minute (00..59)<br> * %S die Sekunde (00..60), (Der Bereich ist bis zu 60, um gelegentliche Schaltsekunden zu ermöglichen)

;ow=: 	'''true''': die Datei wird überschrieben, wenn sie im Ziel-Pfad schon vorhanden ist (default), '''false''': eine bereits vorhandene Datei 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)<br> '''inc''': nur neue Objekte und Objekte die sich nach dem letzten Upload verändert haben werden berücksichtigt<br> '''nth:<Tage>''': nur Objekte neuer als <Tage> werden berücksichtigt (gebrochene Zahlen sind erlaubt, z.B. 3.6) 

;struc=: '''true''': alle Objekte werden inkl. ihrer Verzeichnisstruktur im Zielpfad gespeichert (default)<br>'''false''': alle Objekte werden ohne die ursprüngliche Verzeichnisstruktur im Zielpfad gespeichert 



Der lokale Pfad zur Datei bzw. zum Ordner kann entweder ein absoluter Pfad oder eine relativer Pfad zum FHEM-Wurzelverzeichnis (siehe globales Attribut modpath) sein. Alle Quellen, Dateien/Ordner, müssen insgesamt in Quotes (") eingeschlossen werden.
 
Nachfolgend einige Beispiele (Upload kann auch durch pepareUpload ersetzt werden):


::<b>set <Name> Upload "./text.txt" dest=/home/upload</b>
::die Datei "text.txt" aus dem FHEM-Wurzelverzeichnis wird in das Zielverzeichnis "/home/upload" übertragen


::<b>set <Name> Upload "/opt/fhem/old data.txt" dest=/home/upload ow=false</b>
::die Datei "old data.txt" im Verzeichnis "/opt/fhem" wird nach "/home/upload/opt/fhem" übertragen sofern sie dort noch nicht existiert 


::<b>set <Name> Upload "./log" dest=/home/upload mode=inc</b>
::die Dateien im Verzeichnis "log" des FHEM-Wurzelverzeichnisses werden nach "/home/upload/log" inkrementell übertragen.


::<b>set <Name> Upload "./log" dest=/home/upload mode=full struc=false</b>
::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.


::<b>set <Name> Upload "./log" dest=/home/upload/%Y_%m_%d_%H_%M_%S mode=full struc=false</b>
::wie voriges Beispiel. Der Zielpfad wird dynamisch mit dem aktuellen Datum + Uhrzeit ergänzt.


::<b>set <Name> Upload "./" dest=/home/upload mode=inc</b>
::die Dateien des gesamten FHEM-Systems werden nach "/home/upload" inkrementell und strukturerhaltend übertragen.   


::<b>set <Name> Upload "/opt/fhem/fhem.pl,./www/images/PlotToChat.png,./log/fhem-2020-10-41.log" dest=/home/upload</b> 
::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 offenen (oder mit Fehlerstatus behafteten) 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, z.B. wenn die Synology Diskstation zum Zeitpunkt des Uploads nicht erreichbar war.

[[Datei:ssfile2.PNG|right|thumb|300px|Upload Historie]]
Die Ergebnisse der Uploads werden 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 Dateien werden durch diesen Befehl aber nicht gelöscht.


<br>
= Download von Objekten zum FHEM-Server (Restore) =

Zum Herunterladen von Dateien oder ganzen Ordnern stehen die Befehle '''Download''' bzw. '''prepareDownload''' zur Verfügung.
Die Syntax und das Ergebnis ist bei beiden Befehlen identisch, nur werden bei prepareDownload die herunterzuladenden Objekte zunächst nur in die Ausführungsqueue gestellt. Zum Starten ist dann der Befehl 
[[Datei:ssfile3.PNG|right|thumb|300px|Ausgabe von set <> listQueue]]

 set <Name> startQueue

auszuführen. Der Setter Download führt die Anweisung sofort aus.
Die mit '''prepareDownload''' erzeugten Queueeinträge können vor der Ausführung mit dem Befehl:

 set <Name> listQueue

anzeigt werden. Diese Liste könnte zum Beispiel so aussehen:

 5 => retryCount=>0, reqtype=>GET, params=>&path="/backup/Carport-20200625-1147065130.jpg", opmode=>download, method=>download, header=>Accept: application/json, dest=>./Carport-20200625-1147065130.jpg, api=>DOWNLOAD

Am Anfang steht immer der Index des Eintrags, hier ist es der Index 5.
Unerwünschte oder falsche Downloads können bei Bedarf noch gelöscht werden. Der Befehl

 set <Name> purgeQueue <Index> 

löscht den angegebenen Eintrag mit dem Index, z.B. 5.

Beim Download von Dateien/Ordnern ist zu beachten, dass die Objekte immer in den FHEM root-Ordner, überlicherweise /opt/fhem, geladen werden. Allerdings kann der Zielordner auf dem FHEM-Server durch den Zusatz von '''dest=''' bestimmt werden.

Als Argument von dest= kann angegeben werden:

::* <Filename>: das Objekt wird mit neuem Namen im default Pfad gespeichert
::* <Pfad/Filename>: das Objekt wird mit neuem Namen im angegebenen Pfad gespeichert
::* <Pfad/>: das Objekt wird mit ursprünglichen Namen im angegebenen Pfad gespeichert. '''Wichtig:''' der Pfad muß mit einem "/" enden.



Wird als herunterzuladendes Objekt ein ganzer Ordner des Synology Dateisystems bestimmt, wird der Inhalt des Ordners in ein zip-Archiv verpackt und im Ziel auf dem FHEM-Server gespeichert. Die Dateien sind dann entsprechend aus dem Archiv zu entpacken.

Nachfolgend ein paar Beispiele. Wichtig is es, die angegbenen Objekte in '''""''' einzuschließen, was besondere Bedeutung hat, wenn die Dateien/Ordner Leerzeichen enthalten. Mehrere Objekte (Files, Ordner oder beides gemischt) werden durch Komma getrennt.

<pre>
set <Name> Download "/backup/Carport-20200625-1147065130.jpg"
set <Name> Download "/backup/Carport-20200625-1147065130.jpg" dest=carport.jpg
set <Name> Download "/backup/Carport-20200625-1147065130.jpg" dest=./log/carport.jpg
set <Name> Download "/backup/Carport-20200625-1147065130.jpg" dest=./log/
set <Name> Download "/Temp/Anträge 2020,/backup/Carport-20200625-1147065130.jpg"
set <Name> Download "/backup/Carport-20200625-1147065130.jpg,/Temp/card.txt" dest=/opt/ 
</pre>

[[Datei:ssfile4.PNG|right|thumb|300px|Ausgabe von get <> remoteFolderList]]
Um sich einen Überblick über die auf der Synology vorhandenen Dateien zu verschaffen, kann man sich vor dem Download ein Liste der Objekte erstellen lassen. Dazu verwendet man den Befehl:

 get <Name> remoteFolderList 

Ohne weiteres Argument erstellt der Befehl eine Übersicht aller auf der Synology vorhandenenen shared Folder. Um  den Inhalt eines bestimmten Ordners anzuzeigen, wird dieser Ordner (inkl. eventueller Unterordner) als Argument mitgegeben, z.B.:

 get <Name> remoteFolderList "/FHEM-Prod/2020_11_29"

Das Ordnerobjekt beginnt immer mit einem '''/''' und wird in '''""''' eingeschlossen, um auch Ordnernamen mit Leerzeichen verarbeiten zu können.
Es können noch weitere Optionen mitgegeben werden,um die angezeigten Informationen zu beeinflussen (siehe Commandref zu SSFile). 



<br>
= Beispiele zur Anwendung =

== Backup des FHEM Filesystems über Synology Kalendereinplanung ==

Es wird vorgestellt, wie man mit Hilfe des Synology Kalenders Backups des FHEM-Filesystems einplant und ausführen lässt. Dabei werden sowohl Full-Backups als auch inkrementelle Backups erstellt. 

Das Backupregime verfolgt folgendes Ziel bzw. Features:


* jede Woche Montag wird ein Full-Backup des gesamten FHEM-Verzeichnisses angefertigt
* die restlichen Tage der Woche werden nur neue oder geänderte Dateien gesichert (inkrementelles Backup)
* jede Sicherung wird auf der Synology in einem gemeinsamen Ordner (z.B. /FHEM-Prod) in jeweils einem separaten Verzeichnis gespeichert
* die Ordnerstruktur der Quelle bleibt innerhalb der Sicherung erhalten (d.h. man weiß genau wohin eine Datei der Sicherung in der Quelle gehört)
* die Sicherungsdateien können direkt wiederhergestellt werden, d.h. es ist kein dekomprimieren oder entpacken nötig.
* bei Bedarf können die Sicherungen ihrerseits durch Synology Backup Werkzeuge (z.B. Hyper Backup) auf externe Datenträger versioniert werden und stehen dadurch lange Zeit zur Verfügung 
* die Sicherungen des laufenden Monats bleiben auf der Synology online verfügbar, ältere Backupverzeichnisse werden gelöscht und können bei Bedarf von einem externen Datenträger wiederhergestellt werden 
* eine grafische chronologische Übersicht der auszuführenden Sicherungen (und Löschungen) ist z.B. zur Anzeige auf einem Tablet verfügbar 

   
Für das vorgestellte Scenario werden die Module SSFile und SSCal ([[SSCal - Integration des Synology Calendar Servers]]) verwendet. Das Modul SSCal zur Steuerung des Synology Kalenders wird hier nur insofern erläutert,wie es für den hier vorgesehenen Einsatzzweck benötigt wird. Weiterführende Informationen findet man in dem [[SSCal - Integration des Synology Calendar Servers|Wiki-Artikel]] zu SSCal.

Um das oben definierte Scenario umzusetzen, werden die dazu nötigen Schritte nachfolgend beschrieben. Es sind dazu '''keine Volume-Mounts''' auf dem FHEM-Server '''nötig'''. Jede Kommunikation und Datenübertragung wird über das lokale Netzwerk abgewickelt. 

<br>
=== FHEM Backup-Device anlegen ===

Zur Durchführung der Backup wird ein SSFile Device mit dem Namen '''SynFile''' definiert. Es wird in dem Beispiel die Verbindung zur Synology mit der Adresse 192.168.2.10 hergestellt.

[[Datei:ssfcb0.PNG|right|thumb|400px|Backup Device SynFile]]

<pre>
defmod SynFile SSFile 192.168.2.10
attr SynFile alias Backup auf Synology (API)
attr SynFile devStateIcon .*running:control_arrow_rightward .*done|.*Upload\squeue\sfill\sfinished:control_on_off:startQueue .*Error:control_arrow_rightward@red .*Initialized:control_standby@orange
attr SynFile excludeFromUpload ./FHEM/FhemUtils/cacheSSCam.*,\
./www/SVGcache.*
attr SynFile group Backup
attr SynFile icon system_backup
attr SynFile interval 0
attr SynFile noAsyncFillQueue 0
attr SynFile room Dienste->Allgemein
attr SynFile showPassInLog 0
attr SynFile stateFormat <b>letzter Update:</b> lastUpdate\
<br>\
1:state
attr SynFile verbose 2
</pre>

Nach der Erstdefinition sind die Credentials zur Verbindung mit der DS einzutragen. Im Attribut '''excludeFromUpload''' angegebene Objekte werden von den Backups ausgeschlossen. In dem Beispiel sind es gecachte Daten die im Restorefall nicht benötigt werden.

Dieses Backup-Device wird später von automatisch erstellten at-Devices angesprochen. 


<br>
=== freigegebenen Ordner auf Synology DS erstellen ===

Als Ziel für die auszuführenden Backups wird auf der Synology ein freigebener Ordner '''FHEM-Prod''' angelegt.
Die Schritte dazu sind in dieser [https://www.synology.com/de-de/knowledgebase/DSM/help/DSM/AdminCenter/file_share_create Online-Hilfe] beschrieben.


<br>

=== Synology Kalender anlegen ===
[[Datei:ssfcb1.PNG|right|thumb|200px|Synology Kalender]]
Für die vorgesehenen Steuerungen wird ein Kalender auf der Synology DS angelegt wenn noch nicht vorhanden. Im vorliegenden Beispiel wird dazu der Kalender '''Haussteuerung Prod''' verwendet.

Wie ein Synology Kalender angelegt wird, ist z.B. in diesem [https://www.synology.com/de-de/knowledgebase/DSM/help/Calendar/calendar_creating_calendars Hilfeartikel] beschrieben bzw. ist in diversen Onlinemedien abrufbar.

Die von mir verwendete Definition des Synology Kalenders zur Aufnahme von Haussteuerungseinträgen zeigt nebenstehende Abbildung.



<br>

=== den angelegten Synology Kalender in FHEM integrieren ===

Zur FHEM Integration wird das Modul 57_SSCal verwendet. Dieses Modul ist speziell für die Integration des Synology Calendar Servers entwickelt und verfügt über Features die die Erstellung automatisierter Vorgänge in FHEM sehr vereinfachen. Die umfangreichen Möglichkeiten des Modul sind im [http://sds1.myds.me/mediawiki/index.php?title=SSCal_-_Integration_des_Synology_Calendar_Servers|SSCal Wiki-Artikel] näher beschrieben.  

Zur Integration des vorher angelegten Kalenders '''Haussteuerung Prod''' wird folgende RAW-Definition des Kalenderdevices '''SynControl''' verwendet:

<pre>
defmod SynControl SSCal 192.168.2.10
attr SynControl alias Synology Kalender Haussteuerung
attr SynControl asyncMode 1
attr SynControl createATDevs 1
attr SynControl cutLaterDays 2
attr SynControl cutOlderDays 1
attr SynControl event-on-update-reading .*Summary.*,state
attr SynControl group Haussteuerung
attr SynControl icon time_calendar
attr SynControl interval 400
attr SynControl room Dienste->Kalender
attr SynControl stateFormat <b>Status:</b> state - <b>Last Update</b>: lastUpdate - <b>Next Update</b>: nextUpdate
attr SynControl tableFields Begin,End,DaysLeft,Weekday,Summary,Status,Calendar
attr SynControl tableSpecs {\
  "cellStyle"  =>            {\
                               "noHeader"           => "0",\
                               "headerAlign"        => "center",\
                               "columnAlign"        => "center",\
                               "columnSymbolAlign"  => "center",\
                               "columnSummaryAlign" => "left",\
                             },\
  "columnMapIcon"         => [{\
                               "Status" => "eq 'ended' ",\
                               "icon"   => "rc_WEB@grey",                                \
                             },\
                             {\
                               "daysLeft" => ">= 1 ",\
                               "icon"   => "rc_WEB",                                \
                             }],\
  "columnMapProvider"     => "GoogleMaps",\
  "columnStateIcon"       => [\
                             {\
                               "Status"   => "eq 'ended' ",\
                               "icon"     => "1px-spacer",\
                             },\
                             {\
                               "Status"   => "eq 'started' ",\
                               "icon"     => "10px-kreis-gruen",\
                             },\
                             {\
                               "Status"   => "eq 'upcoming' ",\
                               "icon"     => "10px-kreis-gelb",\
                             },\
                             {\
                               "Status"   => "eq 'alarmed' ",\
                               "icon"     => "10px-kreis-gruen",\
                             },\
                             ],\
 "columnSymbolIcon"       => "time_manual_mode", \
}
attr SynControl usedCalendars Haussteuerung Prod
</pre>

[[Datei:ssfcb2.PNG|right|thumb|400px|grafische Kalenderübersicht]]
Nach der Erstdefinition des Devices muss der verwendete User mit seinen Credentials im Device gesetzt werden. Dadurch werden automatisch alle verfügbaren Kalender der in der DEF angegebenen Synology Diskstation (hier die DS mit der Adresse 192.168.2.10) abgerufen. Der/die relevante(n) Kalender werden danach mit dem '''Attribut usedCalendars''' selektiert.

Wichtig ist das Attribut '''createATDevs'''. Es bewirkt, dass eine im Feld '''Beschreibung''' eines Kalendereintrags vorhandene Codedefinition automatisch in ein at-Device in FHEM umgesetzt wird. Die dazu nötige Syntax wird im Abschnitt "Anlegen eines Kalendereintrags" näher erläutert.

Das Attribut '''tableSpecs''' legt die gewünschten Merkmale zur Gestaltung der graphischen Kalenderanzeige in FHEM fest. Nebenstehende Abbildung zeigt die Kalendergrafik des fertig angelegten Kalenderdevices. Die Übersicht enthält bereits Einträge zur Haussteuerung die es allerdings in einem frisch defninierten Kalender noch nicht gibt und erst durch die nachfolgend beschriebenen Verfahren hinzukommen.
  
Der im Attribut interval eingestellte Wert 400 definiert einen Abruf der Kalendereinträge alle 400 Sekunden. Dabei werden eventuell im Feld Beschreibung des Kalendereintrags enthaltene Codefinitionen ausgewertet aund automatisch korrespondierende at-Devices angelegt bzw. auch gelöscht/verändert wenn ein Kalendereintrag gelöscht oder entfernt wurde.

<br>

=== den Eintrag für Full-Backup im Synology Kalender Haussteuerung vornehmen ===
 
Ein Full-Backup soll wöchentlich jeden Montag um 02:15 ausgeführt werden. In der Synology Kalenderapplikation wird dazu der abgebildete Kalendereintag vorgenommen.

[[Datei:ssfcb3.PNG|left|thumb|200px|Kalendereintrag Vollsicherung]]



Ist eine Information über die bevorstehenden Start einer Sicherung gewünscht, kann im Punkt '''Warnung''' ein entsprechender Eintrag vorgenommen werden. Bei der Anlage des Kalendereintrags ist an dieser Stelle der Kalenderdefault hinterlegt, der im vorliegenden Beispiel komplett gelöscht wurde um keinerlei Hinweispopups oder dgl. zu erhalten.

[[Datei:ssfcb4.PNG|right|thumb|300px|Wiederholung Vollsicherung]]




Zur Einplanung der Wiederholung der Vollsicherung wird der Haken bei '''Ereignis wiederholen''' gesetzt und die entsprechende Einstellung zur wöchentlichen Wiederholung vorgenommen. 

[[Datei:ssfcb5.PNG|right|thumb|300px|Codedefinition Vollsicherung]]
Die im Ereignis auszuführenden Aktion wird im Feld Beschreibung eingetragen. Das SSCal Device erkennt ein auszuführendes FHEM-Kommando an in geschweifte Klammern '''{...}''' eingebetteten Text. 
Um eine Vollsicherung auszuführen, wird folgender Code in diesem Feld eingetragen

 { set SynFile Upload "./" dest=/FHEM-Prod/%Y_%m_%d_Full }

Die Quelle '''./''', also der gesamte root-Ordner der FHEM-Installation, wird gesichert (normalerweise /opt/fhem). Das Zielverzeichnis %Y_%m_%d_Full wird im freigegebenen Ordner FHEM-Prod automatisch angelegt wenn es nicht vorhanden ist. Dabei werden die POSIX Variablen %Y durch das Jahr, %m durch den aktuellen Monat und %d durch den aktuellen Tag ersetzt.



<br>
=== den Eintrag für inkrementelles Backup im Synology Kalender Haussteuerung vornehmen ===
 
Ein inkrementelles Backup wird an allen anderen Tagen (als Montag) um 02:15 ausgeführt. In der Synology Kalenderapplikation wird dazu der abgebildete Kalendereintag vorgenommen.

[[Datei:ssfcb6.PNG|left|thumb|200px|Kalendereintrag inkrementelle Sicherung]]



Die '''Warnung''' wird bei diesem Eintrag wieder entfernt um keinerlei Hinweispopups oder dgl. vor dem Start der Aktion zu erhalten.

[[Datei:ssfcb7.PNG|right|thumb|300px|Wiederholung inkrementelle Sicherung]]




Zur Einplanung der Wiederholung der inkremntellen Sicherung wird der Haken bei '''Ereignis wiederholen''' gesetzt und die entsprechende Einstellung zur wöchentlichen Wiederholung vorgenommen. 

[[Datei:ssfcb8.PNG|right|thumb|300px|Codedefinition Vollsicherung]]
Im Feld Beschreibung wird wieder die Codierung für die Ausführung der inkrementellen Sicherung eingetragen:

 { set SynFile Upload "./" dest=/FHEM-Prod/%Y_%m_%d mode=inc }

Die Codierung entspricht dem oben beschriebenen Vollbackup, außer dass der Zusatz '''mode=inc''' das inkrementelle Backup bewirkt.




<br>

=== den Eintrag zum Löschen alter Backups im Synology Kalender Haussteuerung vornehmen ===

[[Datei:ssfcb9.PNG|left|thumb|200px|Ablagestruktur Sicherungen]]



[[Datei:ssfcb10.PNG|right|thumb|200px|Eintrag Löschen Backups]]
Werden die in den vorangegangenen Punkten definierten Sicherungen ausgeführt, wird jedes Backup in einem separaten Verzeichnis im freigegebenen Ordner FHEM-Prod auf der Synology DS abgelegt wie z.B. im Bild gezeigt. 



Es sollen alte Backups des Vormonats gelöscht werden.

Dazu wird am 9. Tag jedes Monats ein Löschvorgang angelegt, der alle Backupverzeichnisse des Vormonats mit deren Inhalten löscht. Die Aktion wird erst einige Tage nach dem Start eines Monats ausgeführt, damit immer hinreichend aktuelle Backups online auf dem NAS zur Verfügung stehen.

Es wird der dargestellte Eintrag um 01:15 angelegt. Die Standardwarnungen werden wiederum gelöscht. Die Wiederholung wird monatlich mit dem Kriterium "Tag des Monats" ausgeführt. 

[[Datei:ssfcb11.PNG|left|thumb|200px|Wiederholung Löschen Backups]]



Wie bereits beschrieben, wird der Code des auszuführenden Kommandos im Feld Beschreibung eingetragen. Dieses Mal soll Perl-Code statt eines einfachen FHEM Kommandos ausgeführt werden. 



Dazu wird der Code in doppelte geschweifte Klammern eingefügt <nowiki>{{...}}</nowiki>. SSCal erkannt dadurch dass es sich hierbei um Perl-Code handelt und behandelt es entsprechend bei der Anlage des korrespondierenden at-Devices.


[[Datei:ssfcb12.PNG|right|thumb|200px|Code im Beschreibungs Feld]]
<pre>
{{
  my $dev        = "SynFile";
  my $folder     = "/FHEM-Prod/%Y_%m_";
  my $folderres  = strftime "$folder", localtime(time-1728000);  # heute - 20 Tage
  
  for my $d (1..31) {
      my $d     = sprintf "%02d", $d;
      my $fstr  = $folderres.$d;
      my $fstr1 = $folderres.$d."_Full";
      CommandSet (undef, qq{$dev deleteRemoteObject "$fstr"});
      CommandSet (undef, qq{$dev deleteRemoteObject "$fstr1"});
  }
}}
</pre>


<br>

=== Zusammenfassung ===

Wurden alle Aktionen wie beschrieben durchgeführt, enthält das Kalenderdevice SynControl nach jedem Update die auszuführenden Backup-Aktivitäten. Durch die Aktivierung von '''createATDevs''' werden bei jedem Kalenderupdate at-Devices angelegt welche die gewünschten Backup-Aktionen terminieren und ausführen. 

[[Datei:ssfcb13.PNG|right|thumb|200px|erzeugte at-Devices]]
[[Datei:ssfcb14.PNG|left|thumb|200px|erzeugtes at-Device]]
[[Datei:ssfcb15.PNG|right|thumb|200px|Backup Übersicht]]

Das Kalenderdevice enthält im Abschnitt '''Probably associated with''' eine Übersicht der automatisch erzeugten at-Devices.
Die Namen der Devices sind generisch und enthalten neben der EventId auch den geplanten Ausführungszeitpunkt.

Mit jedem Backup-Lauf wird ein Unterverzeichnis <Jahr>_<Monat>_<Tag> in FHEM-Prod angelegt in dem die gesicherten Dateien gespeichert werden. Die Sicherung ist strukturerhaltend, d.h. die FHEM-Verzeichnisse der gesicherten Daten werden ebenfalls mit angelegt.
Sicherungen die die älter sind als der aktuelle Monat werden am neunten Tag des aktuellen Monats entfernt.

Möchte man die Sicherungen längere Zeit versioniert speichern, bietet sich der zusätzliche Einsatz des Tools Hyper Backup an. 

Zur Anzeige der grafischen Backup-Übersicht auf einem Tablet kann zum Beispiel ein [[SSCal_-_Integration_des_Synology_Calendar_Servers#Termintabelle_als_Weblink_einf.C3.BCgen|Weblink-Device]] verwendet werden.



<br>

= Beschränkungen und Known Bugs =

* es werden bei '''Upload/prepareUpload''' nur Dateien/Verzeichnisse berücksichtigt deren Name '''kein @''' beinhaltet.