Beszel Monitor

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

Aktueller Release
0.17.1
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. Ein Administratorkonto ist nicht nötig.

Für Container-Daten braucht dieser Benutzer zusätzlich Leserecht auf die containers-Sammlung des Hubs. Ohne das funktionieren alle anderen Metriken weiter; der Adapter warnt einmal und behält die bereits angelegten Container-Datenpunkte.

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; bei http auf eine andere Maschine als den ioBroker-Host laufen Anmeldung und Sitzungsschlüssel unverschlüsselt über das Netz, und der Adapter sagt das einmal im Protokoll.
  3. Benutzername und Passwort eintragen. Der Benutzername ist die E-Mail-Adresse Ihrer Beszel-Anmeldung.
  4. Auf Test Connection drücken. Es wird eine echte Anmeldung am Hub durchgeführt; bei einem Problem erscheint der tatsächliche Fehler — falsches Passwort, 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.

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. Ein Aussetzer darf den Objektbaum nicht leeren; Geräte verschwinden nur, wenn der Hub tatsächlich eine kürzere Liste meldet.
  • Ein Sensor, Lüfter, eine GPU, ein Dateisystem oder Container verschwindet. Die zugehörigen Datenpunkte werden entfernt. Leert sich eine ganze Gruppe auf einmal, wartet der Adapter eine zweite Abfrage ab — ein einzelner Aussetzer räumt den Baum nicht ab.

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

WORK IN PROGRESS

  • New: every system carries a pictogram of its operating system (Linux, macOS, Windows, FreeBSD) in the object tree — the icons the Beszel web UI uses, drawn to read in the light and the dark theme
  • Fixed: network upload/download were always empty against a Beszel Hub 0.19.0 or newer — the adapter now reads the bandwidth field the Hub actually stores (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 — and a system that was pending gets them 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: the adapter no longer writes states after being stopped when the shutdown lands while the detail collections are being read, and no longer tries to arm its timer during shutdown
  • Fixed: after the Hub briefly reported an empty system list, the offline markers written on errors and on shutdown reached no system
  • Fixed: a Hub without the ZFS, SMART or systemd collections (older release) or without read rights for them is asked once, not on every poll
  • Changed: temperature, battery, swap and ZFS ARC datapoints exist only on hosts that report that hardware; existing empty ones are removed
  • 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

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

0.15.0 (2026-09-05)

  • New: ZFS pools with usage, throughput and health as an opt-in metric, the root disk's custom name and cumulative read/write totals for disks and filesystems on Beszel 0.19.0.

0.14.2 (2026-09-05)

  • Changed: Internal cleanup. No user-facing changes.

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