Supervision Beszel

Mise à jour : 2026-10-19 | Non relu

Beszel est un outil léger de supervision des ressources système : processeur, mémoire, disque, réseau, et statistiques des conteneurs Docker. Il affiche l'historique et envoie des alertes quand un seuil est franchi.

Il complète un outil de disponibilité comme Uptime Kuma : Uptime Kuma répond à "le service répond-il ?", Beszel à "la machine est-elle en bonne santé ?" (disque plein, mémoire saturée, charge anormale).

L'architecture hub / agent

Beszel se compose de deux éléments :

• le hub : l'interface web centrale, qui collecte et affiche les données. On l'installe une fois.
• l'agent : un petit programme installé sur chaque machine à superviser. Il mesure les ressources locales et les transmet au hub.

Analogie : le hub est la tour de contrôle, les agents sont les capteurs disséminés sur chaque machine, qui lui remontent en continu leur état.

L'agent est un binaire léger, sans dépendance : il n'a pas besoin de Docker sur les machines supervisées. C'est pratique pour surveiller un serveur, un NAS ou une VM sans y installer toute une pile logicielle.

Installer le hub

Le hub s'installe facilement avec Docker. Créez un dossier (ex. /opt/beszel) et un compose.yml.

services:
  beszel:
    image: henrygd/beszel:0.19.0
    container_name: beszel
    restart: unless-stopped
    volumes:
      - ./beszel_data:/beszel_data
    environment:
      APP_URL: https://supervision.domaine.fr   # l'URL par laquelle vous accédez au hub
    ports:
      - "127.0.0.1:8090:8090"

cd /opt/beszel
docker compose up -d
docker compose logs -f beszel

Le hub écoute sur le port 8090. Dans l'exemple, il n'est publié que sur 127.0.0.1 : on l'atteint via un reverse proxy (pour le HTTPS) ou un tunnel/VPN d'administration, jamais directement sur Internet.

Ouvrez l'interface (via votre proxy ou un tunnel SSH ssh -L 8090:127.0.0.1:8090 user@serveur) et créez le compte administrateur.

Ajouter une machine à superviser

Tout se pilote depuis le hub.

1) Dans l'interface, cliquez sur Add System (Ajouter un système). 2) Renseignez un nom et, selon le mode de connexion choisi (voir Qui contacte qui ?), l'adresse (Hôte/IP) et le port (par défaut 45876) auxquels le hub joindra l'agent. 3) Le hub génère une clé publique et un jeton propres à ce système, ainsi qu'une commande d'installation prête à copier.

Installer l'agent (binaire, recommandé)

Sur la machine à superviser, collez la commande d'installation fournie par le hub. Elle ressemble à :

curl -sL https://get.beszel.dev -o /tmp/install-agent.sh
less /tmp/install-agent.sh      # auditer le script avant de l'exécuter
chmod +x /tmp/install-agent.sh
sudo /tmp/install-agent.sh -k "CLÉ_PUBLIQUE" -t "JETON" -url "https://supervision.domaine.fr"

Le script télécharge le bon binaire, crée un utilisateur système beszel, et installe l'agent comme service (il démarre au boot). De retour dans le hub, le système passe en ligne dès que l'agent se connecte.

• La clé et le jeton sont propres à chaque machine : ne réutilisez pas la même commande pour plusieurs systèmes.
• Lisez le script avant de l'exécuter en root, comme pour toute installation par curl.

Qui contacte qui ?

Point important pour le pare-feu : Beszel sait fonctionner dans les deux sens, et c'est le mode choisi qui décide de ce qu'il faut ouvrir.

Analogie : en mode WebSocket, chaque capteur téléphone lui-même à la tour de contrôle ; en mode SSH, c'est la tour qui appelle chaque capteur à tour de rôle.

Le mode WebSocket est le plus simple quand les machines sont derrière un NAT ou dispersées : aucun port entrant à ouvrir sur les agents, seul le hub est exposé (via votre reverse proxy). Deux points de vigilance :

• le reverse proxy doit laisser passer les WebSockets vers /api/beszel/agent-connect (Traefik, Caddy et Nginx le font, Nginx avec les en-têtes Upgrade et Connection) ;
• depuis la version 0.19.0, l'agent vérifie le certificat HTTPS du hub. Avec Let's Encrypt, rien à faire. Avec un certificat auto-signé, donnez à l'agent le certificat de l'autorité via la variable CA_CERT_FILE, sinon la connexion est refusée.

Le mode SSH reste utile sur un réseau privé où le hub joint directement les machines. Il faut alors ouvrir le port de l'agent, et seulement depuis le hub :

# Sur la machine agent (mode SSH uniquement) : n'autoriser le port 45876 QUE depuis l'adresse du hub
sudo ufw allow from ADRESSE_DU_HUB to any port 45876 proto tcp

Superviser aussi les conteneurs Docker (optionnel)

Pour que l'agent remonte les statistiques des conteneurs d'une machine, donnez-lui accès au socket Docker en lecture seule. C'est le seul cas où l'agent a besoin de Docker. Avec l'agent en binaire, ajoutez l'utilisateur beszel au groupe docker ; avec l'agent en conteneur, montez /var/run/docker.sock:/var/run/docker.sock:ro. Gardez en tête que l'accès au socket Docker est sensible.

Les alertes

Beszel peut prévenir quand une ressource franchit un seuil (CPU élevé, disque presque plein, machine hors ligne...).

1) Configurez un canal de notification dans les Paramètres (mail SMTP, ou autre). 2) Définissez les seuils d'alerte par système ou globalement (dans Alertes). 3) Testez en provoquant une condition (ou avec le bouton de test), pour vérifier que le mail arrive.

L'alerte "machine hors ligne" est particulièrement utile : elle prévient quand un agent ne répond plus, signe possible d'une panne du serveur.

Sauvegarder

Tout l'état du hub (configuration, systèmes, historique) tient dans le dossier beszel_data/. Sauvegardez-le, idéalement hub arrêté :

cd /opt/beszel
docker compose stop
tar -czf beszel-$(date +%F).tar.gz beszel_data/
docker compose start

Si la VM du hub est déjà sauvegardée (snapshot PBS, par exemple), ce dossier est couvert. Les agents, eux, ne stockent rien d'important : une réinstallation suffit.

Mettre à jour

Le hub (via Docker) :

cd /opt/beszel
# Modifier le tag de version dans compose.yml (ex. 0.19.0 vers 0.19.1)
docker compose pull
docker compose up -d

Les agents (en binaire) se mettent à jour avec leur commande intégrée :

sudo beszel-agent update
sudo systemctl restart beszel-agent

Diagnostic

docker compose logs -f beszel          # journaux du hub
journalctl -u beszel-agent -n 50       # journaux de l'agent (installé en binaire)
systemctl status beszel-agent          # état de l'agent
nc -zv ADRESSE_AGENT 45876             # mode SSH : tester la connexion hub vers agent
curl -sI https://supervision.domaine.fr | head -1   # mode WebSocket : le hub répond-il en HTTPS ?

Problèmes fréquents :

• Un système reste hors ligne (mode WebSocket) : regardez les journaux de l'agent. Les causes habituelles sont une URL de hub fausse, un reverse proxy qui bloque les WebSockets, ou un certificat non reconnu (voir CA_CERT_FILE).
• Un système reste hors ligne (mode SSH) : le hub n'atteint pas l'agent sur le port 45876. Vérifiez le pare-feu de la machine agent (autorisé depuis le hub ?), l'adresse renseignée, et que l'agent tourne.
• Les conteneurs Docker n'apparaissent pas : l'agent n'a pas accès au socket Docker (voir la section dédiée).
• Hub et agent ne se parlent plus après une mise à jour : versions incompatibles, réalignez-les.

Références

• Site officiel de Beszel
• Dépôt GitHub
• Installation du hub
• Installation de l'agent
• Notes de version