Surveiller ses machines avec beszel

Je vous en ai brièvement parlé précédemment : j’utilise beszel pour surveiller les constantes vitales des différentes machines constituant mon réseau. Je mentionnais alors la simplicité de son installation. Pour autant, j’ai pensé qu’un article serait justifié, dans la mesure où mon réseau est assez hétérogène pour que je sois passé par plusieurs situations intéressantes.

Présentation

Beszel est une application de supervision légère, auto-hébergée, pensée pour suivre simplement l’état de serveurs et de conteneurs sans déployer une pile de monitoring lourde. Elle centralise dans une interface web claire les métriques essentielles des systèmes, l’historique d’usage des ressources, ainsi que les statistiques Docker ou Podman, ce qui en fait une solution intéressante pour quiconque cherche à superviser ses systèmes avec un outil propre, léger et rapide à déployer.

L’outil met également l’accent sur la simplicité de prise en main, sans pour autant priver l’utilisateur de fonctionnalités avancées. C’est assez mon genre d’application ! L’installation se fait via binaire ou conteneur, les agents sont reliés à un hub central, des alertes peuvent être configurées, gestion multi-utilisateur, authentification OAuth/OIDC, accès API, bref, il y a de quoi faire.

En pratique, je pense que beszel comble le fossé entre le vénérable phpSysInfo (toujours vivant !) et l’usine à gaz Nagios. Elle s’adresse donc au geek power-user.

Installation du hub

Si vous utilisez l’un des systèmes d’exploitation directement supportés par l’application, vous n’aurez aucun mal à installer le hub. Elle est aussi disponible dans les paquets nix, mais la version 0.15 fournie date un peu par rapport à la 0.18 actuellement disponible au moment où j’écris cet article.

Vous pouvez consulter la page listant les options du paquet. Vous pourriez, par exemple, vouloir changer le port.

  services.beszel.hub = {
    enable = true;
    # À éviter si votre serveur est directement accessible depuis Internet.
    # Remplacez par une IP accessible depuis le réseau local, sinon les
    # agents ne pourront pas se connecter.
    host = "0.0.0.0";
  };

Les différences entre les deux versions sont assez significatives pour justifier que, sous NixOS, on se fende d’un module d’import un peu plus compliqué :

{ pkgs, lib, ... }:

let
  version = "0.18.7";

  # Ça, c'est juste un petit bonus, au cas où on aimerait installer le hub sur de l'ARM64
  assetArch = {
    x86_64-linux = "amd64";
    aarch64-linux = "arm64";
  }.${pkgs.stdenv.hostPlatform.system} or (throw
    "Architecture non gérée pour Beszel hub: ${pkgs.stdenv.hostPlatform.system}");

  # Déclaration de la source du paquet binaire qu'on va installer
  hubSrc = pkgs.fetchurl {
    url =
      "https://github.com/henrygd/beszel/releases/download/v${version}/beszel_linux_${assetArch}.tar.gz";
    hash = lib.fakeHash;
  };

  # On crée notre petite dérivation
  beszelHubPackage = pkgs.stdenvNoCC.mkDerivation {
    pname = "beszel-hub-bin";
    inherit version;

    dontUnpack = true;

    installPhase = ''
      mkdir -p $out/bin
      tar -xzf ${hubSrc} beszel
      install -m755 beszel $out/bin/beszel-hub
    '';
  };
in {
  services.beszel.hub = {
    package = beszelHubPackage;
    enable = true;
    # À éviter si votre serveur est directement accessible depuis Internet.
    # Remplacez par une IP accessible depuis le réseau local, sinon les
    # agents ne pourront pas se connecter.
    host = "0.0.0.0";
  };
}

Si vous copiez/collez ce module tel quel dans votre configuration et que vous effectuez un nixos-rebuild switch, l’installation échouera immanquablement (et c’est voulu). Le message d’erreur contiendra une portion similaire à celle-ci :

error: hash mismatch in fixed-output derivation '/nix/store/18ch33m8xicz1x2inb2zbw3wrnv0jwsy-beszel_linux_amd64.tar.gz.drv':
         specified: sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=
            got:    sha256-t1xSqCr1yXIfCKepywwW3yfoGWejhVzvfHfbrZ+0NSQ=

Revenons au module, et en particulier au bloc suivant :

  # Déclaration de la source du paquet binaire qu'on va installer
  hubSrc = pkgs.fetchurl {
    url =
      "https://github.com/henrygd/beszel/releases/download/v${version}/beszel_linux_${assetArch}.tar.gz";
    hash = lib.fakeHash;
  };

On utilise lib.fakeHash pour générer un faux hash, afin que NixOS re-télécharge le binaire (ou la source) et nous donne le bon hash. C’est un peu spécial quand on a l’habitude des gestionnaires de paquets traditionnels, ou qu’on n’a pas l’habitude d’installer des paquets non-nix, mais quand on y réfléchit, c’est un bon moyen de s’assurer de la reproductibilité du build (ce qui fait tout l’intérêt d’un système comme NixOS).

Du coup, dans le message d’erreur, on récupère le bon hash, qu’on peut mettre dans la configuration :

    hash = "sha256-t1xSqCr1yXIfCKepywwW3yfoGWejhVzvfHfbrZ+0NSQ=";

Je vous explique tout ça parce que le jour où vous voudrez changer la version du paquet, nixos-rebuild switch va de nouveau s’arrêter avec une erreur concernant ce hash. Ainsi, vous ne tomberez pas des nues.

À noter que si vous changez la version ou l’URL de récupération du paquet, il est préférable, dans la foulée, de remettre hash = lib.fakeHash; avant le nixos-rebuild switch, parce que Nix peut réutiliser un ancien objet du store correspondant à ce hash au lieu d’aller chercher le nouveau contenu.

À ce stade, beszel devrait avoir lancé un serveur sur le port 8090, et il devrait vous demander de créer un utilisateur administrateur.

Vous pouvez ensuite cliquer sur le bouton « Ajouter système » en haut à droite, qui vous présente un formulaire simple où il suffit de renseigner un nom pour la machine à surveiller, ainsi que son adresse IP. Ce formulaire tout simple est bien pensé, puisqu’il fournit même les commandes à lancer sur les clients (y compris les docker-compose pour ceux qui utilisent des conteneurs).

Si vous cliquez directement sur le bouton de confirmation, la machine sera ajoutée dans l’interface, mais beszel considèrera qu’elle est hors ligne. Logique : on n’a pas encore installé d’agent.

À tout moment, on peut cliquer sur le bouton « … » sur la ligne de chaque machine pour obtenir la clé et le token correspondant dont on aura besoin pour installer l’agent. On peut donc ajouter plusieurs machines d’un seul coup, et installer les agents plus tard.

Installation des agents

Sur la machine du hub

On reste sur NixOS et on installe l’agent. C’est très similaire à l’installation du hub :

{ pkgs, ... }:

let
  version = "0.18.7";

  assetArch = {
    x86_64-linux = "amd64";
    aarch64-linux = "arm64";
  }.${pkgs.stdenv.hostPlatform.system} or (throw
    "Architecture non gérée pour Beszel agent: ${pkgs.stdenv.hostPlatform.system}");

  agentSrc = pkgs.fetchurl {
    url =
      "https://github.com/henrygd/beszel/releases/download/v${version}/beszel-agent_linux_${assetArch}.tar.gz";
    hash = "sha256-SuMnqsWtWiMYRbDvYTBm1VW75S9+yy8opT0HwE5omv8=";
  };

  beszelAgentPackage = pkgs.stdenvNoCC.mkDerivation {
    pname = "beszel-agent-bin";
    inherit version;

    dontUnpack = true;

    installPhase = ''
      mkdir -p $out/bin
      tar -xzf ${agentSrc} beszel-agent
      install -m755 beszel-agent $out/bin/beszel-agent
    '';
  };
in {
  services.beszel.agent = {
    enable = true;
    package = beszelAgentPackage;
    environmentFile = "./agent.env";
    smartmon.enable = true;
  };
}

Là encore, on peut explorer les options fournies par le paquet nix. Deux choses diffèrent ici : on spécifie un fichier d’environnement (qui est responsable du stockage de la clé et du token fournis par le hub) et on active smartmon (du paquet smartmontools, pour surveiller l’état S.M.A.R.T. des disques).

Le fichier d’environnement est très simple lui-aussi :

HUB_URL=http://127.0.0.1:8090
KEY=
TOKEN=

Il suffit d’ajouter l’URL du hub (celle par laquelle vous accédez à l’interface web du hub), ajouter la clé et le token, nixos-rebuild switch, et paf, ça fait des chocapic. Et c’est réutilisable sur toute machine sous NixOS, à condition de changer l’URL du hub, et de mettre la clé et le token correspondant à la machine créée via l’interface web du hub.

Sur un autre GNU/Linux

Là, ça dépend de la distro, mais le script d’installation fonctionne bien sur debian et dérivées. La documentation explique même, en quelques commandes, comment se débrouiller sans le pipe. Et même sans la documentation, le formulaire de création de machine vous donne directement la commande à coller dans votre émulateur de terminal.

Par exemple :

curl -sL https://get.beszel.dev -o /tmp/install-agent.sh && chmod +x /tmp/install-agent.sh && /tmp/install-agent.sh -p 45876 -k "ssh-ed25519 AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" -t "xxxx-xxxxxxxxx-xxxx-xxxxxxxxx" -url "http://server-monitor.home.arpa:8090"

(Évidemment, la clé et le token seront ceux fournis par beszel).

C’est ce que j’appelle une application bien foutue.

Notez que le paquet smartmontools doit être installé pour retourner les données S.M.A.R.T. des disques.

Sur Home Assistant

Il faut ajouter un dépôt tiers au magasin d’applications :

https://github.com/vineetchoudhary/home-assistant-beszel-agent.

Ensuite, on installe le paquet Beszel Agent (S.M.A.R.T.) qui apparait, et on le configure avec la clé, le token et l’URL du hub. A priori, il ne devrait pas être nécessaire de changer des variables d’environnement.

En revanche, il faut désactiver le mode protégé pour que S.M.A.R.T. puisse fonctionner.

Après ça, on a accès à tout, y compris les conteneurs et les services.

Sur OPNsense

Contrairement à ce que disait mon collègue LeGeekHeureux en novembre 2025 (mais, pour sa défense, l’application est jeune et son développement est soutenu), aujourd’hui, ça fonctionne même directement sur OPNsense (en copiant la configuration pour FreeBSD donnée par le hub), mais attention : le paquet et ses données ne sont pas gérés par l’interface utilisateur d’OPNsense. Par conséquent, il n’y a aucune intégration réelle au niveau du système (sauvegarde, accès depuis l’interface web, ce genre de choses).

Pour les données S.M.A.R.T., l’agent galère un peu tout de même en raison de problèmes de permissions, mais rien qui résiste à quelques commandes :

echo 'own nvme0 root:operator' >> /etc/devfs.conf
echo 'perm nvme0 0660' >> /etc/devfs.conf
echo 'own xpt0 root:operator' >> /etc/devfs.conf
echo 'perm xpt0 0660' >> /etc/devfs.conf
service devfs restart

L’agent ne remonte pas non plus les données des températures. Un ticket a été ouvert, il y a juste à rester un peu patient.

Enfin, l’agent ne sait pas encore lire la liste des services d’OPNsense, donc il faudra s’en passer.

Sur un vieux NAS Synology

En revanche, mon NAS Synology DS216 Play a réclamé un petit effort de ma part, étant donné que l’agent beszel ne s’installera pas via le pipe : il faut procéder à une installation manuelle. Il faut donc télécharger manuellement le client, créer le service systemd, l’activer et le lancer.

Une fois cela effectué, on se rend compte alors que les données S.M.A.R.T. sont fausses : l’agent essaye de remonter ces données depuis le RAID au lieu de les remonter par disque. En outre, la surveillance de l’espace disque ne concerne que la partition système de 8G, pas le disque de données.

Bidouiller les variables d’environnement ne suffit pas. Après investigation dont je vous épargne les détails, le problème vient du paquet smartmontools fournit par Synology, bloqué dans sa version 6.5. Or, l’agent beszel veut utiliser l’option -j de smartctl, apparue dans la version 7.

On peut contourner ça en configurant le dépôt :

http://packages.synocommunity.com/

dans le gestionnaire de paquets. On installe ensuite le paquet SynoCli Disk tools qui va notamment installer smartmontools dans sa version 7.5. On peut aussi installer SynoCli File Tools, qui installe nano, si vous n’êtes pas à l’aise avec vi.

Il faut encore adapter le service systemd dont je vous livre ici ma version :

[Unit]
Description=Beszel Agent Service
After=network-online.target
Wants=network-online.target

[Service]
ExecStart=/usr/bin/beszel-agent
Environment="LISTEN=45876"
Environment="KEY=<clé fournie par le hub>"
Environment="TOKEN=<token fourni par le hub>"
Environment="HUB_URL=<url du hub>"
Environment="EXTRA_FILESYSTEMS=/volume1"
Environment="EXCLUDE_SMART=/dev/md0,/dev/md1,/dev/md2"
Environment="SMART_DEVICES=/dev/sda:sat,/dev/sdb:sat"
Environment="PATH=/volume1/@appstore/synocli-disk/sbin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
AmbientCapabilities=CAP_SYS_RAWIO CAP_SYS_ADMIN
CapabilityBoundingSet=CAP_SYS_RAWIO CAP_SYS_ADMIN
Restart=on-failure
RestartSec=5
StateDirectory=beszel-agent

# Security/sandboxing settings
KeyringMode=private
LockPersonality=yes
NoNewPrivileges=yes
ProtectClock=yes
ProtectHome=read-only
ProtectHostname=yes
ProtectKernelLogs=yes
ProtectSystem=strict
RemoveIPC=yes
RestrictSUIDSGID=true

[Install]
WantedBy=multi-user.target

Les lignes importantes concernent les variables d’environnement :

• EXTRA_FILESYSTEMS permet à l’agent de remonter l’utilisation du RAID (espace disque, notamment)
• EXCLUDE_SMART permet d’éviter que l’agent remonte les données S.M.A.R.T. du RAID
• SMART_DEVICES permet à l’agent de reconnaitre correctement les disques que l’on souhaite surveiller
• PATH permet d’ajouter le chemin vers le binaire fournit par SynoCommunity ; sans cela, beszel utilisera encore le binaire fournit par Synology

On ne peut pas juste remplacer le binaire Synology par celui de SynoCommunity sans casser l’UI du NAS. J’ai testé pour vous…

Si, après redémarrage du hub et de l’agent, des lignes persistent dans le hub concernant les périphériques /dev/md*, il suffit de les supprimer sans remord.

Il reste toutefois une incompatibilité insoluble qui empêche l’agent de lister les services systemd : il réclame au minimum la version 243 de systemctl quand celle fournie par Synology est la 219. Il est donc impossible d’obtenir cette liste dans le hub.

Alertes

Pour chaque hôte (ou pour tous les hôtes, en lot), on peut configurer des alertes en fonction de conditions plus ou moins basiques : charge CPU trop élevée, hôte hors-ligne, capacité disque réduite, etc. Ces conditions sont simples, et c’est précisément ce que je voulais. Là encore, l’UI/UX se démarque par sa simplicité et son utilisabilité.

En cliquant sur le lien en haut du panneau, on va pouvoir régler comment les notifications sont délivrées : par adresse email, ou par Shoutrrr. Pratique pour s’envoyer des SMS via le service de free…

Pour les emails, il va falloir cliquer sur le lien configurer un serveur SMTP juste au-dessus de l’adresse email pré-remplie, qui va ouvrir une nouvelle fenêtre vers PocketBase, qui stocke toutes les informations de beszel. Là, vous pourrez régler vos paramètres SMTP et tester ces paramètres.

Ça fonctionne parfaitement bien.

Conclusion

Beszel répond exactement à mon besoin. C’est léger, ça remonte les données que je veux depuis n’importe quelle machine (et pas des milliers d’autres que je ne regarderai jamais), le monitoring fonctionne bien, j’ai de la versatilité là où j’en ai besoin. Bref, c’est un excellent outil que je suis très content d’avoir découvert, d’abord en novembre chez LeGeekHeureux, puis dernièrement par ChatGPT.