Beszel Monitor

Verbindet sich mit einem Beszel Hub und stellt Server-Metriken als ioBroker-Datenpunkte bereit

Aktueller Release
0.19.0
Entwickler
krobi
Lizenz
MIT

Dieser Adapter spiegelt einen Beszel-Hub nach ioBroker. Beszel ist ein schlanker Server-Monitor: auf den überwachten Maschinen laufen kleine Agenten, die an einen zentralen Hub melden; der Adapter liest diesen Hub über seine REST-Schnittstelle und legt pro überwachtem System ein Gerät an.

Alles ist rein lesend. Der Adapter schreibt nie zum Hub und legt keine beschreibbaren Datenpunkte an.

Voraussetzungen

Sie brauchen einen laufenden Beszel-Hub mit mindestens einem verbundenen Agenten und eine Anmeldung für diesen Hub. Der Adapter meldet sich als normaler Beszel-Benutzer an — mit derselben E-Mail-Adresse und demselben Passwort wie in der Beszel-Weboberfläche; einen Benutzernamen nimmt Beszel dort nicht an. Ein Administratorkonto ist nicht nötig, die Mehr-Faktor-Anmeldung muss für diesen Benutzer aber aus sein: den Einmal-Code kann der Adapter nicht beantworten.

Der Benutzer sieht nur die Systeme, denen er zugeordnet ist: die er selbst angelegt hat, die ein Hub-Administrator ihm zugeordnet hat (PocketBase-Verwaltung unter /_/, Sammlung systems, Feld users), oder alle, wenn der Hub mit SHARE_ALL_SYSTEMS=true läuft. Ein Benutzer ohne Zuordnung meldet sich problemlos an und sieht eine leere Liste — der Verbindungstest sagt das.

Einrichtung

  1. Installieren und Instanz anlegen. In ioBroker beszel installieren und die Instanz-Einstellungen öffnen.
  2. Hub-Adresse eintragen unter Beszel Hub URL — dieselbe Adresse, mit der Sie die Beszel-Weboberfläche öffnen, zum Beispiel http://192.168.1.100:8090. Eine IPv6-Adresse steht in eckigen Klammern: http://[fd00::1]:8090. http und https funktionieren beide; ein https-Hub braucht ein Zertifikat, dem der ioBroker-Rechner vertraut. Ein Hub hinter einem Reverse-Proxy behält seinen Pfad (https://example.org/beszel). Leerzeichen und ein abschließender Schrägstrich werden entfernt; eine Adresse mit ?, # oder Benutzername und Passwort darin wird abgelehnt.
  3. E-Mail und Passwort Ihrer Beszel-Anmeldung eintragen.
  4. Auf Test Connection drücken. Es wird eine echte Anmeldung am Hub durchgeführt; die Antwort nennt, wie viele Systeme Ihr Benutzer sieht — oder bei einem Problem den tatsächlichen Fehler: abgelehnte Anmeldung, nicht erreichbarer Host, Tippfehler in der Adresse.
  5. Metriken auswählen im Reiter Metrics (siehe Datenpunkte und Metrik-Schalter). Voreingestellt sind Laufzeit, CPU, Lastmittel, Arbeitsspeicher, Festplatte, Festplattendurchsatz, Netzwerk und Temperatur. Alles andere ist aus, bis Sie es einschalten.
  6. Speichern. Die Instanz startet, liest den Hub einmal und legt den Objektbaum an.

Abfrageintervall und Zeitlimit

Poll Interval nimmt 10 bis 300 Sekunden, voreingestellt 60. Die Beszel-Agenten zeichnen einen Messwert pro Minute auf; ein Wert unter 60 Sekunden erzeugt also zusätzliche Anfragen ohne neuere Daten. Ein Wert außerhalb dieses Bereichs — etwa von einem Skript direkt in die Konfiguration geschrieben — wird begrenzt statt übernommen.

Request timeout (5 bis 120 Sekunden, voreingestellt 15) ist die Zeit, die eine einzelne Anfrage dauern darf. Bei langsamer Verbindung oder einem Hub mit sehr vielen Containern erhöhen.

Was der Adapter anlegt

beszel.0.
├── info.connection      ist der Hub erreichbar
├── info.systemsTotal    am Hub registrierte Systeme
├── info.systemsOnline   davon auf „up"
├── info.systemsAllUp    wahr, solange alle auf „up" stehen
└── systems.<name>.      ein Gerät je überwachtem System

Der Gerätename ist der Systemname vom Hub, kleingeschrieben und mit _ für alles, was kein Buchstabe und keine Ziffer ist. Zwei Systeme, deren Namen auf dieselbe Kennung zusammenfallen, bekommen ein kurzes Hash-Anhängsel, damit sie sich nicht gegenseitig überschreiben — der Adapter weist einmal im Protokoll darauf hin. Ein Name ohne lateinischen Buchstaben und ohne Ziffer (Kyrillisch, Chinesisch, …) wird zu sys_ plus einem kurzen Hash der System-Id des Hubs und bleibt so über Neustarts gleich.

Wird ein System am Hub umbenannt, wandert es auf eine neue Geräte-Kennung: der Adapter meldet System renamed on the Hub: systems.a → systems.b, und der alte Baum geht — mit Historie und anderen Einstellungen an seinen Datenpunkten. Ein am Hub entferntes System wird ebenso gemeldet.

Wie sich der Adapter verhält, wenn etwas fehlt

  • Ein System geht aus oder ist pausiert. info.online wird falsch und info.status zeigt, was der Hub meldet. Die Messwerte bleiben auf dem letzten Stand stehen, statt auf null zu springen — der Adapter berichtet, was er weiß, und er weiß gerade nichts Neues.
  • Der Hub ist nicht erreichbar. info.connection wird falsch, jedes System geht auf info.online: false und info.status: unknown, die Flottenzähler fallen auf null. Dasselbe passiert beim Stoppen der Instanz — nichts behauptet weiter „online", während niemand liest.
  • Der Hub antwortet mit einer leeren Liste. Es wird nichts gelöscht. PocketBase beantwortet eine Anmeldung, die es nicht mehr annimmt (geändertes Passwort, gelöschter Benutzer, zurückgespielte Hub-Datenbank), mit einer leeren Liste statt mit einem Fehler — deshalb meldet sich der Adapter zuerst neu an und fragt noch einmal. Bleibt die Liste leer, bleibt der Baum, wie er ist, und das Protokoll sagt einmal, dass der Benutzer keine Systeme sieht.
  • Die Anmeldung wird abgelehnt. Das Protokoll nennt den Grund — falsche E-Mail oder falsches Passwort, Mehr-Faktor-Anmeldung, oder Passwort-Anmeldung am Hub abgeschaltet. Nach drei Fehlversuchen versucht es der Adapter in wachsenden Abständen, höchstens alle 15 Minuten, statt bei jeder Abfrage das Passwort zu schicken.
  • Ein Sensor, Lüfter, eine GPU, ein Dateisystem, Container oder ein anderes Gruppenmitglied verschwindet. Die zugehörigen Datenpunkte werden entfernt, sobald es in zwei aufeinander folgenden Abfragen fehlt — ein einzelner Aussetzer räumt nichts ab.
  • Eine Liste ist länger, als der Adapter liest. Der Adapter liest höchstens 50 Seiten je Liste (bei den Listen der Systeme, Container, Units und Geräte je 1000 Einträge). Auf einem Hub, der groß genug ist, das zu überschreiten, wird die abgeschnittene Liste einmal gemeldet und lässt den Baum, wie er ist, statt die Systeme an ihrem Ende zu löschen.

Beim Update

Ein Update legt Namen und Beschreibungen erneut auf die bereits vorhandenen Datenpunkte, damit korrigierte Formulierungen und neue Übersetzungen auch bestehende Anlagen erreichen und nicht nur Neuinstallationen. Die Kehrseite: ein Datenpunkt, den Sie selbst in der Admin umbenannt haben, trägt beim nächsten Start wieder den Namen des Adapters.

Changelog

0.19.0 (2026-09-25) — stable

  • New: network monitors (Beszel 0.20.0) as an opt-in metric — response time, hourly average/fastest/slowest and loss for every ping, TCP, HTTP and DNS monitor set up on the Hub
  • New: containers show whether an image update is available (Beszel 0.20.0)
  • New: btrfs filesystems appear next to the ZFS pools (Beszel 0.20.0), with their own name, the pool type and a flag for raw physical sizes
  • New: the connection test tells how many systems your user can see, and says so when it is none
  • Fixed: after a password change, a deleted user or a restored Hub database the adapter kept every system green without new values for up to a day — it now logs in again right away
  • Fixed: a refused login says why — wrong e-mail or password, multi-factor authentication, or password login switched off on the Hub — and the adapter stops retrying every poll
  • Fixed: a paused or never-connected system no longer shows uptime 0 or empty system details; its last values stay
  • Fixed: on current Hubs, swap, ZFS cache, GPU memory and GPU package power appeared on hosts that do not have them — they are removed
  • Fixed: drives without a temperature or capacity reading showed 0; they now get no such datapoint
  • Fixed: a storage pool that was removed came back with the next detail refresh and stayed until the next restart
  • Fixed: a system whose name has no Latin letters or digits (e.g. Cyrillic or Chinese) got no object tree; it now gets a stable fallback id
  • Fixed: two containers or group members whose names turn into the same id could swap their datapoints after a restart, and a container's id suffix changed with every re-create
  • Fixed: a member of a group (sensor, container, unit, …) that was missing from a single poll was deleted at once; it now has to be missing twice
  • Fixed: spaces and a trailing slash around the Hub URL are removed; a URL with ?, # or a user name and password in it is rejected with a clear message, also in the connection test
  • Fixed: on a very large Hub, the systems at the end of a long list lost their datapoints — a cut-off list now leaves the tree as it is and is reported once
  • Fixed: a request that trickled in slowly could run far past the configured timeout
  • Changed: a Hub URL that does not lead to the Beszel API (e.g. a missing reverse-proxy path) is named as such in the log and in the connection test
  • Changed: a renamed or removed system on the Hub is reported in the log
  • Changed: the login field is called E-mail — Beszel does not accept a username
  • Changed: the SMART verdict also knows WARNING and UNKNOWN, the pool health UNKNOWN and the vdev state MISSING
  • Changed: help texts, descriptions and translations corrected; drive model, serial number, firmware and host name carry more specific roles

0.18.0 (2026-09-15) — stable

  • New: every system carries a pictogram of its operating system in the object tree — the same icons the Beszel web UI uses, readable in the light and the dark theme
  • Fixed: network upload/download were always empty against a Beszel Hub 0.19.0 or newer; they carry values again, and older Hubs keep working
  • Fixed: disk read/write, network upload/download and swap used show 0 while idle instead of an empty value
  • Fixed: containers and systemd units of a system that is down or paused were deleted after a few minutes — they now keep their last values like every other datapoint
  • Fixed: the last SMART device, ZFS pool detail or systemd unit of a system was never removed once it disappeared on the Hub
  • Fixed: hardware and OS details are refreshed when a system reconnects — a new kernel shows after the reboot, not after the next adapter restart
  • Fixed: a system that was still pending gets its hardware and OS details on its first contact
  • Fixed: a Hub that is slow at adapter start no longer blanks the hardware/OS datapoints of all systems for one poll
  • Fixed: renaming a system on the Hub in a way that keeps its object id (e.g. only the case) now reaches the object tree
  • Fixed: a system added later with the same name as an existing one no longer takes over the existing system's object tree; the newcomer gets the suffix
  • Fixed: a container, dataset or unit whose name equals a group name (e.g. gpu, network, containers) kept being renamed while its system was down
  • Fixed: stopping the adapter in the middle of a poll no longer leaves late value changes behind
  • Fixed: after the Hub briefly reported an empty system list, the offline markers written on errors and on shutdown reached no system
  • Changed: temperature, battery, swap and ZFS ARC datapoints exist only on hosts that report that hardware; existing empty ones are removed
  • Changed: uptime, load average and agent version appear only once a system has connected; existing empty ones are removed
  • Changed: the ZFS error counters and the SMART power-cycle counter no longer show an empty unit in the object tree
  • Changed: the four "Peak values" options are gone — a Hub never delivers peak values in the minute records the adapter reads, so they never produced a datapoint
  • Changed: the messages of the connection test follow the system language, and the test runs with the configured request timeout
  • Changed: SMART and dataset text columns the Hub does not carry read as empty (null) instead of an empty string
  • Changed: the warning about a plain-http Hub URL is gone — http on the local network is how Beszel is normally deployed
  • Changed: info.uptime_text is gone — it was info.uptime a second time as text; existing installations lose it on the first start

0.17.1 (2026-09-07)

  • Improved: sixteen datapoints now carry an explanation in the object tree — online state, OS name, load average, container and service CPU, ZFS scrub errors and drive power cycles
  • Fixed: the datapoint carrying the distribution name was labelled "OS Version" — it now reads "OS Name" in all eleven languages, matching what it actually shows

0.17.0 (2026-09-06)

  • New: SMART data per drive as an opt-in metric — the drive's own overall verdict plus temperature, capacity, power-on hours and power cycles
  • New: ZFS pool details as an opt-in metric — scrub status, per-vdev error counters and the datasets of each pool
  • New: systemd service details as an opt-in metric — state, sub-state, CPU and memory for every unit the agent reports
  • Improved: the two slow detail sources are read every 15 minutes instead of every poll, so switching them on costs your Hub almost nothing

0.16.0 (2026-09-06)

  • Fixed: switching a metric group off now really empties it — a system that was offline at the time kept the empty channel and got it back after every restart
  • Fixed: a stumble while starting no longer leaves the adapter alive but silent — it keeps going and updates your values as usual
  • Changed: the status words of a system, of a ZFS pool and of a container are shown in your ioBroker language instead of English
  • Changed: a container's health is now a proper status datapoint with its list of possible values, like the system status next to it
  • Improved: starting up puts far less load on the ioBroker database, which shows most with many systems or many metrics switched off
  • Changed: user documentation now covers the ZFS pools, the root disk name and the read/write totals

License

MIT License

Copyright (c) 2026 krobi krobi@power-dreams.com

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Developed with assistance from Claude.ai