From 5cb9c6060d0091e2b752a98bfe35abdd32410743 Mon Sep 17 00:00:00 2001 From: Thomas Trautwein Date: Fri, 24 Jan 2025 07:38:49 +0100 Subject: [PATCH] Updated zabify container documentation --- README.md | 156 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 155 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index ad11ea6..d0946ba 100644 --- a/README.md +++ b/README.md @@ -1 +1,155 @@ -# zabify-container +# Zabify Server + +## Was ist Zabify Server? +Zabify Server ist eine benötigte Komponente für die App "Zabify Pro" (Apple Store, Google Play), um verschlüsselte Push-Nachrichten sicher von Ihrem Zabbix-Server auf Ihr Endgerät schicken zu können. + +Weitere Informationen finden Sie unter https://www.zabify.de. + +## Image herunterladen +Unter [git.zabify.de/Zabify/-/packages/container/zabify](https://git.zabify.de/Zabify/-/packages/container/zabify) finden Sie die Container und den dazugehörigen Versionsverlauf. Suchen Sie sich Ihre gewünschte Version aus und ersetzen Sie diese im kommenden Befehl mit ``. + +Laden Sie das Zabify Server Image mit folgendem Befehl herunter: +```sh +$ docker pull git.zabify.de/zabify/zabify: +``` + +## Wie man das Image verwendet + +### `zabify-server` Starten +Starten Sie einen Zabify Server Container mit minimaler Konfiguration wie folgt: +```sh +$ docker run --name your-zabify-server-name \ + -p 80:80 \ + -e PORT=80 \ + -e USE_HTTPS=false \ + -e ZABBIX_SERVER_URL="https://your-zabbix-server.com" \ + -d \ + git.zabify.de/zabify/zabify +``` +Der gestartet Zabify Server Container läuft unter den gewählten Namen `your-zabify-server-name`, verwendet im Container den Port 80, der per `PORT` definiert wurde und ist für den in `ZABBIX_SERVER_URL` hinterlegten Zabbix-Server zuständig. + +### HTTPS-Zertifikat verwenden +Starten Sie den Zabify Server Container im HTTPS-Modus wie folgt: +```sh +$ docker run --name your-zabify-server-name \ + -p 80:80 \ + -v /your/path/to/https_data-directory:/home/zabify/https_data + -e PORT=80 \ + -e ZABBIX_SERVER_URL="https://your-zabbix-server.com" \ + -e USE_HTTPS=true \ + -e HTTPS_CERT_FILE="/home/zabify/https_data/cert.pem" \ + -e HTTPS_KEY_FILE="/home/zabify/https_data/key.pem" \ + -d \ + git.zabify.de/zabify/zabify +``` +Mit Hilfe der angegebenen Umgebungsvariablen `USE_HTTPS`, `HTTPS_CERT_FILE` und `HTTPS_KEY_FILE` aktivieren Sie den HTTPS-Modus und geben den Pfad zu den benötigten HTTPS-Dateien an. `-v /your/path/to/https_data-directory` ist dabei der Pfad zu Ihrem Ordner, in dem die HTTPS benötigten Dateien hinterlegt sind. + +### Zugang zur Shell +Der `docker exec`-Befehl erlaubt es Ihnen Befehle im Container auszuführen. Der folgende Befehl gibt Ihnen Zugang zur Shell Ihres `zabify-server` Containers: +```sh +$ docker exec -ti your-zabify-server-name /bin/sh +``` + +### Konfiguration des Zabify Servers und dessen Funktionalität testen +Testen Sie ihre vollständige Konfiguration wie nachfolgend beschreiben. Stellen Sie sicher, dass Ihr `zabify-server` Container im Hintergrund läuft und der Server erfolgreich gestartet wurde. Öffnen Sie zum Testen der Konfiguration zu erst die Shell ihres `zabify-server` Containers, wie im Abschnitt zuvor beschrieben. +```sh +# Normal +$ ./server start test \ + --config-file=/home/zabify/configuration/zabify.conf \ + --hostID=1234 \ + --eventID=1234 \ + --severity=1 \ + --sendTo=your-zabify-token + +# Server im HTTPS-Modus +$ ./server start test \ + --config-file=/home/zabify/configuration/zabify.conf \ + --hostID=1234 \ + --eventID=1234 \ + --severity=1 \ + --sendTo=your-zabify-token \ + --server-ca-file="/home/zabify/https_data/ca-file" +``` +Per `hostID` können Sie den Host angeben, für welchen die Push-Nachricht verschickt werden soll. Per `eventID` können Sie das Event angeben, für welchen die Push-Nachricht verschickt werden soll. Stellen Sie sicher, dass es sich bei der angebenen `hostID` und `eventID` um reale Werte handelt. Andernfalls können Sie die erhaltene Push-Nachricht am Gerät nicht öffnen. Per `severity` können Sie die Serverity angeben, welche die Push-Nachricht haben soll. Abhängig des Wertes wird ein anderen Benachrichtigungssound gespielt. Per `sendTo` geben Sie Ihren Zabify Push-Nachrichten Token an, welchen Sie aus der App erhalten haben, der definiert, an welches Gerät die Push-Nachricht versendet werden soll. Wenn der Server richtig konfiguriert ist und Zugriff aufs Internet hat, sollten Sie innerhalb kurzer Zeit eine Push-Nachricht auf Ihrem Endgerät erhalten. Andernfalls erhalten Sie eine Fehlermeldung mit entsprechenden Hinweisen bezüglich des Fehlers. Wenn Ihr `zabify server` im HTTPS-Modus aktiv ist, dann müssen Sie den Pfad zu Ihrer CA-Datei mittels `server-ca-file` mit angeben. + +### Umgebungsvariablen + +#### Logging-spezifisch + +##### `SHOW_VERSION_INFORMATION` +Zeigt die Versionsinformationen von `zabify server` beim Start des Containers. Default: `true`. + +##### `NO_BANNER` +Zeigt den Banner von `zabify server` beim Start des Containers. Default: `false`. + +##### `NO_CONSOLE_LOG` +Gibt keine Logging-Informationen in der Konsole aus. Default: `false`. Mögliche Werte: `true`, `false`. + +##### `NO_FILE_LOG` +Speichert keine Logging-Informationen in einer Datei. Default: `false`. Mögliche Werte: `true`, `false`. + +##### `LOG_LEVEL` +Definiert das mindest Log-Level, welches eine Logging-Nachricht besitzen muss, um ausgegeben zu werden. Default: `info`. Mögliche Werte: `debug`, `info`, `error`. + +##### `NO_LOG_ROTATION` +Es wird keine Rotation der Log-Datei ausgeführt, um ab einer bestimmten Dateigröße (`MAX_LOG_FILE_SIZE_MB`) eine neue Log-Datei anzufangen. Default: `false`. Mögliche Werte: `true`, `false`. + +##### `MAX_LOG_FILE_SIZE_MB` +Gibt die maximale Dateigröße in MB an, die die Logging-Datei haben darf, bevor eine neue Logging-Datei erstellt und verwendet wird. Default: `100`. Mögliche Werte: jeder numerische Wert > 0. + +##### `MAX_LOG_FILE_BACKUPS` +Gibt die maximale Anzahl an Logging-Dateien, die gespeichert werden. Wenn die Anzahl den angegebenen Wert überschreitet wird die älteste Log-Datei gelöscht. Default: `10`. Mögliche Werte: jeder numerische Wert > 0. + +##### `MAX_LOG_FILE_AGE` +Gibt das maximale Alter in Tagen einer Logging-Datei an, bevor dieses gelöscht wird. `0` bedeutet keine Anwendung dieser Regel. Default: `0`. Mögliche Werte: jeder numerische Wert >= 0. + +##### `COMPRESS_LOG_BACKUPS` +Gibt an, ob die Log-Datei komprimiert werden soll, um den Speicherverbrauch zu reduzieren. Default: `false`. Mögliche Werte: `true`, `false`. + +#### Serverumgebung-spezifisch + +##### `SERVER_MEMORY_LIMIT` +Soft-Memory-Limit in Bytes, die der Server verwenden darf. `0` bedeutet eine automatische Berechnung des Wertes. Default: `0`. Mögliche Werte: jeder numerische Wert >= 0. + +##### `SERVER_GARBAGE_COLLECTION_RATE` +Intervall in Sekunden, in dem die Garbage Collection für den Server zwangsweise ausgeführt wird. `0` bedeutet eine Ausführung nach Bedarf ohne die zwangsweise Ausführung im Intervall. Default: `0`. Mögliche Werte: jeder numerische Wert >= 0. + +##### `ZABBIX_SERVER_URL` +Die URL des Zabbix-Servers, von dem die Push-Benachrichtigungen kommen. Default: ``. Mögliche Werte: Zabbix-Server URL. + +##### `PORT` +Port, auf dem der Server lauschen soll. Wenn `0`, dann wird ein nicht verwendeter Port zufällig ausgewählt. Default: `4338`. Mögliche Werte: jeder numerische Wert >= 0. + +##### `USE_HTTPS` +Gibt an, dass der Server im HTTPS-Modus aktiv sein soll. Default: `false`. Mögliche Werte: `true`, `false`. + +##### `HTTPS_CERT_FILE` +Gibt den Pfad zur HTTPS Cert-Datei an. Default: ``. Mögliche Werte: Pfad zur HTTPS Cert-Datei. + +##### `HTTPS_KEY_FILE` +Gibt den Pfad zur HTTPS Key-Datei an. Default: ``. Mögliche Werte: Pfad zur HTTPS Key-Datei. + +#### Client handling-spezifisch + +##### `SERVER_TIMEOUT` +Maximal erlaubte Sekunden für eine aktive Verbindung, bevor die Zeit abgelaufen ist. Default: `60`. Mögliche Werte: jeder numerische Wert >= 0. + +##### `CONNECTION_LIMIT` +Maximale Anzahl aktiver Verbindungen zum Server, bevor dieser gedrosselt wird und neue Verbindungen in den Backlog geschickt werden. Default: `10`. Mögliche Werte: jeder numerische Wert > 0. + +##### `CONNECTION_BACKLOG_LIMIT` +Maximale Anzahl der ausstehenden aktiven Verbindungen zum Server im Backlog. Default: `10`. Mögliche Werte: jeder numerische Wert > 0. + +##### `CONNECTION_BACKLOG_TIMEOUT` +Maximale Anzahl an erlaubten Sekunden, in denen eine ausstehende aktive Verbindung zum Server im Backlog gehalten werden kann. Default: `60`. Mögliche Werte: jeder numerische Wert > 0. + +##### `MAX_BACKOFF` +Maximale Zeit, die als Backoff-Zeit zwischen den Wiederholungsversuchen zum Senden der Push-Benachrichtigung an das Gerät verwendet werden soll. Default: `32`. Mögliche Werte: jeder numerische Wert > 0. + +##### `MAX_RETRY_AMOUNT` +Maximale Anzahl von Wiederholungsversuchen für das Senden von Push-Benachrichtigungen an das Gerät. Default: `5`. Mögliche Werte: jeder numerische Wert > 0. + +#### Kryptografisch-spezifisch + +##### `KEY_ITERATION_COUNT` +Anzahl der Schlüsselgenerierungen vor Verwendung des generierten Schlüssels. Default: `10000`. Mögliche Werte: jeder numerische Wert > 0. \ No newline at end of file