Installer et configurer Saga#

Ce document couvre l'installation de Saga et tout ce qui se configure : options du serveur, HTTPS, reverse proxy, pare-feu, comptes, ligne de commande, agent du module « Machines », maintenance et désinstallation. L'utilisation au quotidien est décrite dans le guide d'utilisation.

Les exemples utilisent un serveur Saga en 192.168.10.6 et le domaine exemple.lan. Remplacez-les par vos valeurs.

1. Prérequis#

Saga est un seul programme qui embarque sa base de données (SQLite), son interface web et son serveur HTTPS : pas de serveur web, de base de données, de Node.js ni de conteneur à installer.

Placez-le en dehors de ce qu'il surveille quand c'est possible (une petite VM sur un autre hôte, un Raspberry Pi…) : un superviseur qui tombe avec le reste ne prévient personne.

2. Installer#

2.1 Avec le paquet Debian (recommandé)#

sudo apt install ./saga-server_0.3.0_amd64.deb

Le paquet installe :

2.2 Depuis les sources#

Prérequis : Go 1.24.

./scripts/build.sh                 # tests, puis dist/linux/saga-server et saga-agent
./packaging/deb/build-deb.sh       # installateurs/saga-server_*.deb et saga-agent_*.deb

Aucune étape front-end : l'interface (HTML, CSS, JavaScript) est intégrée telle quelle au binaire.

2.3 Pour essayer, sans rien installer#

SAGA_DB=/tmp/saga-essai.db SAGA_SETUP_TOKEN=essai ./saga-server

Ouvrez http://localhost:8090 et créez le compte avec le jeton essai. Supprimez /tmp/saga-essai.db pour repartir de zéro.

3. Premier lancement#

Au premier démarrage, sans compte, Saga génère un jeton d'installation :

sudo journalctl -u saga | grep jeton

Il est aussi dans /var/lib/private/saga/setup-token. Ouvrez l'interface (voir la section 5), saisissez le jeton, choisissez l'identifiant (admin par défaut) et le mot de passe (10 caractères minimum) du premier administrateur. Le jeton est ensuite supprimé.

Activez tout de suite la double authentification : Paramètres › Compte.

4. Le fichier de configuration#

Toute la configuration du serveur est dans /etc/saga/saga.env, relu au redémarrage :

sudo nano /etc/saga/saga.env
sudo systemctl restart saga

Le reste (sondes, canaux, pages de statut, comptes) se règle dans l'interface. La liste complète des variables est en section 14.

5. Accès à l'interface et HTTPS#

Par défaut, Saga n'écoute que sur 127.0.0.1:8090 : l'interface n'est joignable que depuis le serveur lui-même. Pour l'ouvrir depuis votre poste sans rien changer, un tunnel SSH suffit :

ssh -L 8090:127.0.0.1:8090 utilisateur@192.168.10.6

puis http://localhost:8090 tant que la session est ouverte. Pour un accès permanent, trois possibilités.

5.1 HTTPS intégré avec autorité locale (auto) — recommandé sur un réseau privé#

SAGA_ADDR=192.168.10.6:8443
SAGA_TLS=auto
SAGA_TLS_HOSTS=192.168.10.6,saga.exemple.lan
SAGA_PUBLIC_URL=https://saga.exemple.lan:8443

Saga crée une autorité de certification locale et signe lui-même son certificat, renouvelé automatiquement. L'autorité est bridée : elle ne peut signer que des adresses privées et les noms déclarés dans SAGA_TLS_HOSTS ; installée sur vos appareils, elle ne permettrait pas d'usurper un site public.

Pour supprimer l'avertissement du navigateur, installez l'autorité sur vos appareils : téléchargez https://192.168.10.6:8443/saga-ca.crt et comparez son empreinte avec celle du journal (journalctl -u saga | grep autorité).

SAGA_PUBLIC_URL sert aux liens des notifications et aux commandes affichées dans l'interface.

5.2 Vos propres certificats (files)#

SAGA_ADDR=0.0.0.0:8443
SAGA_TLS=files
SAGA_TLS_CERT=/etc/saga/cert.pem
SAGA_TLS_KEY=/etc/saga/key.pem

Le service lit les fichiers au démarrage : redémarrez-le après un renouvellement.

5.3 Derrière un reverse proxy (off)#

Gardez l'écoute locale et confiez le HTTPS au proxy :

SAGA_ADDR=127.0.0.1:8090
SAGA_TLS=off
SAGA_TRUST_PROXY=1
SAGA_PUBLIC_URL=https://saga.exemple.fr

SAGA_TRUST_PROXY=1 fait lire l'adresse du visiteur dans X-Forwarded-For (blocage après plusieurs échecs de connexion) et le protocole dans X-Forwarded-Proto (cookie de session Secure). Ne l'activez que si seul le proxy peut joindre Saga.

L'interface reçoit les mises à jour en direct par /api/live (Server-Sent Events), une connexion qui reste ouverte :

• Caddy : rien à faire (reverse_proxy 127.0.0.1:8090).
• Nginx : Saga désactive lui-même la mise en tampon (X-Accel-Buffering: no) ; gardez un proxy_read_timeout d'au moins 60 s.
• Nginx Proxy Manager : réglages par défaut.

Si les pages de statut doivent être publiques mais pas l'interface, publiez seulement /status/, /api/public/, /api/push/ et les fichiers statiques (/style.css, /status.js, /common.js, /theme-init.js, /favicon.*), et réservez le reste à votre réseau.

5.4 Interface en HTTP sur le réseau (déconseillé)#

SAGA_ADDR=0.0.0.0:8090 avec SAGA_TLS=off fonctionne, mais mots de passe et cookies circulent en clair. À réserver à un réseau de confiance, le temps d'un essai.

6. Réseau et pare-feu#

Ping sans root. Les sondes ping utilisent la socket « datagramme ICMP » de Linux, autorisée pour les groupes listés dans net.ipv4.ping_group_range. systemd l'ouvre à tous par défaut ; sinon :

echo 'net.ipv4.ping_group_range = 0 2147483647' | sudo tee /etc/sysctl.d/60-saga-ping.conf
sudo sysctl --system

Avec ufw, par exemple, pour une interface en 8443 réservée au réseau local :

sudo ufw allow from 192.168.10.0/24 to any port 8443 proto tcp

7. Comptes, rôles et double authentification#

Les comptes se gèrent dans Paramètres › Utilisateurs. Il reste toujours au moins un administrateur. Un administrateur peut redéfinir le mot de passe d'un autre utilisateur et couper sa double authentification (téléphone perdu).

Double authentification (TOTP) : Paramètres › Compte › Activer. Saga affiche un QR code à scanner (Aegis, 2FAS, Google Authenticator, Andvari…) puis dix codes de secours à usage unique, à conserver hors du téléphone. Un code déjà utilisé est refusé.

Connexion : 5 essais libres par adresse, puis un blocage qui double à chaque nouvel échec (jusqu'à une heure). Les sessions durent 30 jours ; changer son mot de passe ferme les autres.

8. Service systemd#

sudo systemctl status saga
sudo systemctl restart saga
sudo journalctl -u saga -f

Le service tourne avec un utilisateur éphémère (DynamicUser), un système de fichiers en lecture seule sauf son dossier de données, sans accès aux dossiers personnels, avec des appels système filtrés et aucun privilège.

Pour ajuster sans modifier le fichier du paquet :

sudo systemctl edit saga

par exemple pour limiter la mémoire :

[Service]
MemoryMax=256M

9. Ligne de commande#

Les commandes accèdent à la base : arrêtez le service avant, et lancez-les avec le même utilisateur éphémère :

sudo systemctl stop saga
sudo systemd-run --pty --wait -p DynamicUser=yes -p User=saga -p StateDirectory=saga \
     -E SAGA_DB=/var/lib/saga/saga.db /usr/bin/saga-server <commande>
sudo systemctl start saga

10. Module « Machines » : l'agent#

Facultatif, à activer dans Paramètres › Machines. Un agent installé sur chaque serveur envoie toutes les 30 s le CPU, la mémoire, le swap, la charge, le réseau et l'occupation des disques.

Machines › Ajouter une machine affiche une commande d'installation avec le jeton de la machine, montré une seule fois :

curl -fsSL https://saga.exemple.lan:8443/install.sh | sudo sh -s -- <jeton>

Avec l'autorité locale (SAGA_TLS=auto), la commande affichée contient -k pour ce premier téléchargement ; le script installe ensuite l'autorité sur la machine et tout le reste est vérifié. Le script installe /usr/local/bin/saga-agent, sa configuration /etc/saga-agent/saga-agent.env et le service saga-agent (utilisateur éphémère, système en lecture seule).

Sans le script, avec le paquet saga-agent :

sudo apt install ./saga-agent_0.3.0_amd64.deb
sudo nano /etc/saga-agent/saga-agent.env     # SAGA_SERVER, SAGA_TOKEN, SAGA_CA
sudo systemctl enable --now saga-agent

Vérifier sans envoyer : saga-agent -print. Désinstaller : sudo systemctl disable --now saga-agent, puis supprimer ces fichiers.

11. Völund#

Völund (la forge des machines, de la même famille) peut prévenir Saga à la fin de chaque installation de Debian :

1. Dans Saga : nouvelle sonde de type Push, copiez son URL (…/api/push/<jeton>).
2. Dans Völund : Paramètres › Saga › URL push de la sonde.
3. Si Saga utilise son HTTPS intégré, collez aussi son autorité (contenu de /saga-ca.crt).

12. Mise à jour, sauvegarde, restauration#

Mettre à jour : installez le nouveau paquet, le service redémarre seul. La configuration, les comptes et l'historique sont conservés ; la base est mise à niveau au démarrage.

sudo apt install ./saga-server_0.3.0_amd64.deb

Depuis la 0.2, le compte unique devient l'utilisateur admin, avec le même mot de passe.

Sauvegarder la configuration : Paramètres › Sauvegarde › Exporter (JSON des sondes, canaux, pages de statut et maintenances, avec ou sans les secrets).

Sauvegarder tout (comptes et historique compris), service en marche :

sudo sqlite3 /var/lib/private/saga/saga.db ".backup /root/saga-$(date +%F).db"

Restaurer : arrêtez le service, remettez le fichier à sa place, redémarrez.

sudo systemctl stop saga
sudo install -m 600 /root/saga-2026-10-15.db /var/lib/private/saga/saga.db
sudo systemctl start saga

13. Désinstaller#

sudo apt remove saga-server      # garde la configuration et les données
sudo apt purge saga-server       # supprime aussi /etc/saga et /var/lib/private/saga

14. Référence des variables#

Guide d'utilisation de Saga#

Ce guide décrit l'utilisation de Saga au quotidien : tableau de bord, sondes, alertes, pages de statut, maintenances et paramètres. L'installation et la configuration du serveur sont dans Installer et configurer Saga.

1. Le tableau de bord#

À gauche, la liste des sondes, rangées par groupe, avec une recherche et un filtre par état. Chaque ligne montre la disponibilité sur 24 heures et les dernières pulsations (une barre par vérification) :

À droite, la vue rapide (nombre de sondes par état) et le journal des évènements importants : chaque passage d'un état à un autre, avec la date et le message.

Tout se met à jour en direct : une vérification apparaît au moment où elle se termine, sans recharger la page. L'indicateur « EN DIRECT » passe à « HORS LIGNE » si la connexion au serveur est coupée ; elle se rétablit seule.

La fiche d'une sonde#

Un clic sur une sonde ouvre sa fiche :

• les 100 dernières pulsations et le dernier message (code HTTP, mot-clé trouvé, adresse résolue…) ;
• le temps de réponse actuel et moyen sur 24 h, la disponibilité sur 24 h, 30 et 90 jours, la date d'expiration du certificat ;
• l'historique sur 90 jours : une barre par jour, verte, ambre ou rouge selon la disponibilité du jour (détail au survol) ;
• le graphique du temps de réponse, de 1 heure à 7 jours ;
• le journal de ses évènements.

Les boutons permettent de la mettre en pause (plus de vérification ni d'alerte), de la vérifier tout de suite, de la modifier, de la cloner ou de la supprimer.

2. Les sondes#

Bouton Nouvelle sonde. Six types :

Fréquence et tentatives#

• Intervalle : temps entre deux vérifications (20 s minimum). Pour une sonde push : délai maximal entre deux signaux.
• Tentatives avant alerte : après un succès, un échec met la sonde « en attente » et la revérifie après l'intervalle entre tentatives ; elle n'est déclarée hors service qu'après ce nombre d'échecs supplémentaires. Évite les alertes pour un hoquet du réseau.
• Délai max. : au-delà, la vérification échoue (« délai dépassé »).
• Rappel pendant une panne : renvoie l'alerte toutes les N minutes tant que la sonde reste hors service (« 🔁 Toujours hors service »). 0 : une seule alerte.

Options avancées#

• Alerte d'expiration du certificat (HTTP et TLS) : une alerte quand il reste moins de N jours, une autre quand il est renouvelé.
• Ignorer les erreurs de certificat : pour un service en certificat auto-signé, comme l'interface de Proxmox sur le port 8006.
• Mode inversé : la sonde est en ligne quand le service ne répond pas (vérifier qu'un port reste fermé, qu'une ancienne adresse ne répond plus…).
• HTTP : méthode (GET, POST…), corps de requête, en-têtes en JSON (par exemple {"Authorization": "Bearer …"}), codes acceptés (200-299, 301), nombre maximal de redirections suivies.

Organisation#

Le groupe range la sonde dans la liste (Sites web, Proxmox, Tâches…) ; la description s'affiche dans sa fiche.

Sondes push#

Pour ce qui ne s'interroge pas de l'extérieur : sauvegardes, tâches cron, scripts. Saga donne une URL à appeler à chaque exécution réussie :

curl -fsS "https://saga.exemple.lan/api/push/<jeton>?status=up&msg=OK" >/dev/null

Paramètres facultatifs : status=down pour signaler un échec, msg (le message affiché), ping (une durée en millisecondes). Sans signal pendant l'intervalle, la sonde passe hors service.

Par exemple, en fin de script de sauvegarde :

if restic backup /srv; then
  curl -fsS "https://saga.exemple.lan/api/push/<jeton>?msg=sauvegarde+OK" >/dev/null
else
  curl -fsS "https://saga.exemple.lan/api/push/<jeton>?status=down&msg=sauvegarde+en+échec" >/dev/null
fi

3. Les notifications#

Les canaux se déclarent dans Paramètres › Notifications (administrateurs), puis se cochent dans chaque sonde.

Le bouton Tester envoie une notification d'essai. Un canal par défaut est coché d'office sur les nouvelles sondes et reçoit les alertes du module « Machines ».

Une sonde envoie :

• 🔴 Hors service quand elle passe hors service (après les tentatives) ;
• 🔁 Toujours hors service à chaque rappel, si un rappel est réglé ;
• ✅ Rétabli à son retour, avec la durée de la coupure ;
• 🟠 quand son certificat approche de l'expiration.

Une seule alerte part par panne, même si le serveur redémarre entre-temps.

4. Pages de statut et maintenances#

Pages de statut#

Pages de statut › Nouvelle page : un titre et une adresse (/status/services). Puis :

• Services affichés : des groupes (« Sites web », « Messagerie »…) et les sondes de chacun, dans l'ordre voulu ;
• Réglages : description, pied de page, publication, affichage de l'expiration des certificats ;
• Annonce : un message en haut de la page (information, avertissement, incident, résolu).

La page montre l'état général (« Tous les services fonctionnent normalement », « Certains services rencontrent des problèmes », « Panne majeure », « Maintenance en cours »), les maintenances en cours et, pour chaque service, la disponibilité des 90 derniers jours. Elle se met à jour toutes les 30 secondes.

Elle ne montre que les noms et les états : jamais l'adresse d'un service, un message d'erreur ou un jeton. Une page non publiée n'est visible qu'une fois connecté.

Maintenances#

Maintenance › Planifier une maintenance : un titre, une description, un début et une fin, et les sondes concernées (ou toutes). Pendant la fenêtre, ces sondes ne sont plus vérifiées, leurs pulsations sont bleues, aucune alerte ne part, et les pages de statut affichent la maintenance. Le bouton Terminer l'arrête avant l'heure.

5. Paramètres#

Compte#

Votre mot de passe et la double authentification : Activer, scanner le QR code, saisir le code affiché, puis conserver les dix codes de secours (dans Andvari, par exemple). Chacun ne sert qu'une fois et remplace le téléphone en cas de perte.

Utilisateurs (administrateurs)#

Ajouter un compte : identifiant, rôle (lecteur, éditeur ou administrateur) et mot de passe à transmettre à la personne. Un administrateur peut changer le rôle, redéfinir le mot de passe ou couper la double authentification d'un autre utilisateur.

Sauvegarde (administrateurs)#

• Exporter sans les secrets : sondes, canaux, pages de statut et maintenances, partageable.
• Exporter avec les secrets : en plus, mots de passe SMTP, jetons et URL de push, pour une restauration complète. À garder en lieu sûr.
• Importer : un export Saga, ou une sauvegarde Uptime Kuma (Kuma : Paramètres › Sauvegarde › Exporter). Les sondes HTTP, mot-clé, port, ping, DNS et push sont reprises, les groupes Kuma deviennent des groupes, les jetons push sont conservés : vos scripts n'ont qu'à changer d'adresse. Canaux repris : ntfy, Telegram, Gotify, Discord, Slack, Mattermost, Rocket.Chat, webhook et SMTP. Ce qui ne peut pas l'être est listé à la fin.

Deux modes : ajouter (une sonde de même nom, type et cible est ignorée) ou remplacer toute la configuration.

Apparence#

Saga (sombre) et Vélin (clair), plus les thèmes de la famille : Fjord (Gná), Nuit et Parchemin (Andvari), Braise et Givre. Le choix est propre à chaque appareil.

Machines#

Le module facultatif de métriques système : voir l'agent.

6. Bonnes pratiques de sécurité#

• Activez la double authentification, au moins pour les administrateurs, et rangez les codes de secours hors du téléphone.
• Un compte par personne, avec le rôle le plus faible qui suffit : lecteur pour qui consulte, éditeur pour qui gère les sondes.
• N'exposez pas l'interface sur Internet si ce n'est pas nécessaire : accès par le réseau local, un VPN (WireGuard) ou un tunnel SSH. Pour des pages de statut publiques, ne publiez que /status/, /api/public/ et /api/push/ (voir le reverse proxy).
• Traitez les URL de push comme des secrets : qui connaît l'URL peut envoyer des signaux. Une URL divulguée se change en recréant la sonde.
• Gardez l'export « avec les secrets » en lieu sûr, chiffré ; partagez seulement l'export sans les secrets.
• Sauvegardez la base régulièrement (/var/lib/private/saga/saga.db).
• Surveillez Saga lui-même : une sonde HTTP sur /api/health depuis une autre machine (un second Saga, ou un service externe), pour savoir si le superviseur tombe.

7. Dépannage#

Le journal du service donne le détail de chaque panne, alerte et erreur d'envoi :

sudo journalctl -u saga -f