search

M-Welsch / backup-server

Backup Server (BaSe)
Apache License 2.0
3 stars 1 forks source link

BaSe Websocket-Protokoll / API (WIP) #3

Open MaximilianStaab opened 1 year ago

MaximilianStaab commented 1 year ago

0 Meta

0.1 Generelles Format der JSON-Nachrichten

{"topic": <String>, "data": {<String>: <Any>, ...}}

"data" ist optional.

0.2 Erläuterungen zu Zeitstempeln

Wann immer ein Zeitstempel mit Datentyp vorkommt, folgt dessen Format der erweiterten Version der ISO 8601, z.B.: 2023-07-18T13:04:00+01:00

Siehe auch:

0.3 Erläuterungen zur Auflistung

Typ
Acknowledgement

Ein Acknowledgement ist die erwartete Antwort auf einen Command und zeigt entweder Erfolg oder Fehler an. Das Schema ist immer das folgende:

{"topic": <str>, "success": <bool>, "error": <str>}

"topic" ist der selbe String wie beim vorausgegangenen Befehl und "error" ist optional und kann eine Fehlermeldung enthalten, z.B. Details dazu, dass eine Validierung fehlgeschlagen ist. Ist "success" False, wird der Command ignoriert.

1 Auflistung der Nachrichten

1.1 Shutdown-Kontrolle

1.1.1 Shutdown-Timer pausieren

Typ: Command

{"topic": "pause_shutdown_timer"}
1.1.2 Shutdown-Timer fortsetzen

Typ: Command

{"topic": "resume_shutdown_timer"}
1.1.3 Shutdown-Timer Ist-Wert

Typ: Push

{"topic": "shutdown_timer_state", "data": {"seconds": <int>}}
1.1.4 Shutdown-Befehl

Typ: Command

{"topic": "shutdown_now"}

1.2 Backup-Kontrolle

1.2.1 Backup-Timer pausieren

Typ: Command

{"topic": "pause_backup_timer"}
1.2.2 Backup-Timer abbrechen

Typ: Command

{"topic": "cancel_backup_timer"}
1.2.3 Backup-Timer fortsetzen

Typ: Command

{"topic": "resume_backup_timer"}
1.2.4 Nächster Backup-Zeitpunkt

Typ: Push

{"topic": "backup_due_time", "data": {"timestamp": <str>}}
1.2.5 Backup-Timer Ist-Wert

Typ: Push

{"topic": "backup_timer_state", "data": {"seconds": <int>}}
1.2.6 Backup-Befehl

Typ: Command

{"topic": "backup_now"}
1.2.7 Statistiken über das laufende Backup

Typ: Push

{"topic": "backup_progress", "data": {
    "estimated_duration_seconds": <int>,
    "elapsed_seconds": <int>,
    "total_backup_bytes": <int>,
    "copied_bytes": <int>
}}

0.0 ≤ percentage ≤ 1.0

1.2.8 Laufendes Backup vorzeitig beenden

Typ: Command

{"topic": "abort_running_backup"}

1.3 Zeitplan-Kontrolle

1.3.1 Zeitplan erfragen

Typ: Query

{"topic": "get_current_schedule"}
1.3.2 Zeitplan mitteilen

Typ: Response

{"topic": "current_schedule", "data": {
    "interval": <str>,
    "day_of_month": <int>,
    "day_of_week": <int>,
    "hour": <int>,
    "minute": <int>
}}

interval muss diese RegEx matchen: ^daily|weekly|monthly$ day_of_month ist nur relevant falls interval == "monthly". day_of_week ist nur relevant falls interval == "weekly". 1 ≤ day_of_month ≤ 31 1 (Montag) ≤ day_of_week ≤ 7 (Sonntag)

1.3.3 Zeitplan überschreiben

Typ: Command

{"topic": "set_current_schedule", "data": {
    "interval": <str>,
    "day_of_month": <int>,
    "day_of_week": <int>,
    "hour": <int>,
    "minute": <int>
}}

interval muss diese RegEx matchen: ^daily|weekly|monthly$ day_of_month ist nur relevant falls interval == "monthly". day_of_week ist nur relevant falls interval == "weekly". 1 ≤ day_of_month ≤ 31 1 (Montag) ≤ day_of_week ≤ 7 (Sonntag)

Falls day_of_month, day_of_week, hour oder minute out of range: Command wird zurückgewiesen.

1.4 Kontrolle über das Backup-Verhalten

1.4.1 Backup-Verhalten erfragen

Typ: Query

{"topic": "get_current_backup_behaviour"}
1.4.2 Backup-Verhalten mitteilen

Typ: Response

{"topic": "current_backup_behaviour", "data": {
    "shutdown_between_backups": <bool>,
    "use_pre_backup_hook": <bool>,
    "use_post_backup_hook": <bool>,
    "pre-backup_hook_script": <str>,
    "post-backup_hook_script": <str>
    "low_disk_space_threshold_bytes": <int>,
    "enough_disk_space_threshold_bytes": <int>,
}}

pre-backup_hook_script und post-backup_hook_script müssen unixoide Pfade zu jeweils einem Shell-Skript sein, z.B.: /home/user/hooks/pre-backup.sh @jackyscript: Einverstanden mit allem?

1.4.3 Backup-Verhalten überschreiben

Typ: Command

{"topic": "set_current_backup_behaviour", "data": {
    "shutdown_between_backups": <bool>,
    "use_pre_backup_hook": <bool>,
    "use_post_backup_hook": <bool>,
    "pre-backup_hook_script": <str>,
    "post-backup_hook_script": <str>
    "low_disk_space_threshold_bytes": <int>,
    "enough_disk_space_threshold_bytes": <int>,
}}

pre-backup_hook_script und post-backup_hook_script müssen unixoide Pfade zu jeweils einem Shell-Skript sein, z.B.: /home/user/hooks/pre-backup.sh @jackyscript: Einverstanden mit allem?

1.5 Kontrolle über Mitteilungen

1.5.1 Mitteilungseinstellungen erfragen

Typ: Query

{"topic": "get_current_notification_settings"}
1.5.2 Mitteilungseinstellungen mitteilen

Typ: Response

{"topic": "current_notification_settings", "data": {
    "email": {
        "receivers": [<str>],
        "smtp_port": <int>,
        "smtp_server": <str>
    }
}}

Elemente in receivers müssen dieses RegEx matchen: ^[a-zA-Z0-9]+(?:\.[a-zA-Z0-9]+)*@[a-zA-Z0-9]+(?:\.[a-zA-Z0-9]+)*$ → Regex101 @jackyscript: Einverstanden mit allem?

1.5.3 Mitteilungseinstellungen überschreiben

Typ: Command

{"topic": "set_current_notification_settings", "data": {
    "email": {
        "receivers": [<str>],
        "smtp_port": <int>,
        "smtp_server": <str>
    }
}}

Elemente in receivers müssen dieses RegEx matchen: ^[a-zA-Z0-9]+(?:\.[a-zA-Z0-9]+)*@[a-zA-Z0-9]+(?:\.[a-zA-Z0-9]+)*$ → Regex101 @jackyscript: Einverstanden mit allem?

1.6 Kontrolle über HMI-Helligkeit

1.6.1 Display-Helligkeit erfragen

Typ: Query

{"topic": "get_current_display_brightness"}
1.6.2 Display-Helligkeit mitteilen

Typ: Response

{"topic": "current_display_brightness", "data": {"value": <float>}}

0 ≤ value ≤ 1

1.6.3 Display-Helligkeit überschreiben

Typ: Command

{"topic": "set_current_display_brightness", "data": {"value": <float>}}

0 ≤ value ≤ 1

Falls value out of range: Clamping auf min/max.

1.6.4 LED-Helligkeit erfragen

Typ: Query

{"topic": "get_current_led_brightness"}
1.6.5 LED-Helligkeit mitteilen

Typ: Response

{"topic": "current_led_brightness", "data": {"value": <float>}}

0 ≤ value ≤ 1

1.6.6 LED-Helligkeit überschreiben

Typ: Command

{"topic": "set_current_led_brightness", "data": {"value": <float>}}

0 ≤ value ≤ 1

Falls value out of range: Clamping auf min/max.

1.7 Festplattenzustand

1.7.1 Zustand des Festplattenbetriebszustands

Typ: Push

{"topic": "drive_state", "data": {
    "docked": <bool>,
    "powered": <bool>,
    "mounted": <bool>
}}
1.7.2 Zustand der Festplattenbelegung

Typ: Push

{"topic": "drive_usage", "data": {
    "capacity_bytes": <int>,
    "usage_bytes": <int>,
    "usage_percent": <int>
}}

1.8 Log-Steuerung

1.8.1 Aktuelle Warnungen → Anzeige in Banner

Typ: Push

{"topic": "recent_warnings", "data": {"count": <int>}}

Im Banner wird nur die Anzahl der ungesehenen Warnungen und Fehler angezeigt und auf den Log verlinkt, in dem die erste Warnung steht. @jackyscript: fändest Du es besser, wenn das Banner nur auf das Logfile mit den Warnings verlinkt oder wenn die Warnings im ausgeklappten Banner direkt angezeigt werden?

1.8.2 Log-Tail

Typ: Push

{"topic": "log_tail", "data": {"lines": [<str>, <str>, <str>, <str>, <str>]}
1.8.3 Log-Dateiliste erfragen

Typ: Query

{"topic": "get_log_file_list"}
1.8.4 Log-Dateiliste mitteilen

Typ: Response

{"topic": "log_file_list", "data": {"file_names": [<str>, ...]}
1.8.5 Log-Dateiinhalt erfragen

Typ: Query

{"topic": "get_log_file_content", "data": {"file_name": <str>}}
1.8.6 Log-Dateiinhalt mitteilen

Typ: Response

{"topic": "log_file_content", "data": {"file_name": <str>, "content": <str>}}

1.9 Backup-Listensteuerung

1.9.1 Backup-Liste erfragen

Typ: Query

{"topic": "get_backup_list"}
1.9.2 Backup-Liste mitteilen

Typ: Response

{"topic": "backup_list", "data": {"directory_names": [<str>, ...]}

… to be discussed.

M-Welsch commented 1 year ago

@MaximilianStaab schau bitte, welche Config-Werte noch fehlen: https://github.com/M-Welsch/base-bcu/tree/master/base/config

jackyscript commented 1 year ago
Acknowledgement

Ein Acknowledgement ist die erwartete Antwort auf einen Command und zeigt entweder Erfolg oder Fehler an. Das Schema ist immer das folgende:

{"topic": <str>, "success": <bool>, "error": <str>}

Wir sollten überlegen, ob wir zukünftig für jede Person die Logs aus dem Server im Client anzeigen. Stattdessen den Log-Viewer nur für "authorisierte" Benutzer bereitstellen und leserliche Fehlermeldungen an den Client übergeben. Somit ein Mapping haben zwischen Exceptions und Fehlermeldungen im Client. Fehler und Exceptions werden immer auf Serverseite geloggt, aber möglichst nicht an den Client gegeben werden. "Normale Benutzer" können fast immer mit technischen Exceptions/Fehlermeldungen etwas anfangen, "unauthorisierte" wiederum sollen möglichst nichts über das zugrundeliegende System erfahren bspw. Betriebssystem, existierende Pfade und Benutzer etc.

Weitere Überlegungen: Schalter in der Web-Oberfläche, "Opt-In", zum Anzeigen der erweiteren Menüs oder Einstellungen / Log-Viewer

Typ: Query

{"topic": "get_current_backup_behaviour"}
1.4.2 Backup-Verhalten mitteilen

Typ: Response

{"topic": "current_backup_behaviour", "data": {
    "shutdown_between_backups": <bool>,
    "use_pre_backup_hook": <bool>,
    "use_post_backup_hook": <bool>,
    "pre-backup_hook_script": <str>,
    "post-backup_hook_script": <str>
    "low_disk_space_threshold_bytes": <int>,
    "enough_disk_space_threshold_bytes": <int>,
}}

pre-backup_hook_script und post-backup_hook_script müssen unixoide Pfade zu jeweils einem Shell-Skript sein, z.B.: /home/user/hooks/pre-backup.sh @jackyscript: Einverstanden mit allem?

Auf Serverseite können Skripts angelegt werden. Über die Schnittstelle soll nur die Auswahl bereitgestellt werden also z. B. Pre-Backup-Hook-Scripts 1 bis 10 mit Bezeichnungen/Titel. Das Gleiche für Post-Backup-Hook-Scripts.

M-Welsch commented 1 year ago

Wir sollten überlegen, ob wir zukünftig für jede Person die Logs aus dem Server im Client anzeigen. Stattdessen den Log-Viewer nur für "authorisierte" Benutzer bereitstellen und leserliche Fehlermeldungen an den Client übergeben. Somit ein Mapping haben zwischen Exceptions und Fehlermeldungen im Client. Fehler und Exceptions werden immer auf Serverseite geloggt, aber möglichst nicht an den Client gegeben werden. "Normale Benutzer" können fast immer mit technischen Exceptions/Fehlermeldungen etwas anfangen, "unauthorisierte" wiederum sollen möglichst nichts über das zugrundeliegende System erfahren bspw. Betriebssystem, existierende Pfade und Benutzer etc.

ich hab die Diskussion gestern noch zT mitgehört und finde, es ist ein interessanter Aspekt. Generell könnte man ja große Teile der Webapp hinter einem Login verbergen. Bei dem EMS unserer PV-Anlage wird das übrigens so ähnlich gelöst: da bekommt man nicht-eingeloggt nur oberflächlich den Status zu sehen. Eingeloggt kann man dann alles sehen und steuern.

was haltet ihr von der Idee @MaximilianStaab, @jackyscript?

Auf Serverseite können Skripts angelegt werden. Über die Schnittstelle soll nur die Auswahl bereitgestellt werden also z. B. Pre-Backup-Hook-Scripts 1 bis 10 mit Bezeichnungen/Titel. Das Gleiche für Post-Backup-Hook-Scripts.

versteh ich nicht :D, kannst Du das bitte genauer beschreiben?

Ein Gedanke zu den hooks: ich wäre mittlerweile eher dafür, dass wir die skripte pre_backup_hook.sh und post_backup_hook.sh irgendwo anlegen, aber leer lassen. Dann könnten wir uns die Angabe des Pfades sparen und nur noch enablen oder disablen. Was meint ihr?

jackyscript commented 1 year ago

ich hab die Diskussion gestern noch zT mitgehört und finde, es ist ein interessanter Aspekt. Generell könnte man ja große Teile der Webapp hinter einem Login verbergen. Bei dem EMS unserer PV-Anlage wird das übrigens so ähnlich gelöst: da bekommt man nicht-eingeloggt nur oberflächlich den Status zu sehen. Eingeloggt kann man dann alles sehen und steuern.

was haltet ihr von der Idee @MaximilianStaab, @jackyscript?

Find ich auch gut, unsere letzte Idee hierzu war eine niedrigschwellige Variante. Man bekommt nur oberflächliche Dinge zu sehen, erweiterte Inhalte muss man explizit aktivieren (Expertenmodus). Eine Login-Komponente wäre eben dann sinnvoll, wenn man die erweiterten Inhalte verwehren will/nur nach Authorisierung/Authentifizierung bereitstellen möchte.

Auf Serverseite können Skripts angelegt werden. Über die Schnittstelle soll nur die Auswahl bereitgestellt werden also z. B. Pre-Backup-Hook-Scripts 1 bis 10 mit Bezeichnungen/Titel. Das Gleiche für Post-Backup-Hook-Scripts.

versteh ich nicht :D, kannst Du das bitte genauer beschreiben?

Ein Gedanke zu den hooks: ich wäre mittlerweile eher dafür, dass wir die skripte pre_backup_hook.sh und post_backup_hook.sh irgendwo anlegen, aber leer lassen. Dann könnten wir uns die Angabe des Pfades sparen und nur noch enablen oder disablen. Was meint ihr?

Du hast Deine Frage fast selbst beantwortet. Anstatt die Angabe des Pfades direkt anzugeben, was ein Sicherheitsproblem darstellen könnte, sollte nur ein "Mapping" angegeben werden können, um eine "Injection" zu verhindern. Ein Vorschlag war daher die Idee das Skript nur auszuwählen, der Server stellt die verfügbaren Skripte bereit. In Deinem Vorschlag steckt ja schon die Info mit drin, dass es sich nur um ein Skript jeweils handelt, was man aktivieren bzw. deaktivieren kann. Das wäre auch eine bessere Variante als die bisher angedachte.