Table des Matières

Historique et versions
Caractéristiques principales
Prérequis système
↳ Dashboard (Serveur)
↳ Agent (Client)
Installation détaillée
↳ Installation du Dashboard
↳ Déploiement de l'Agent
Configuration de base
Utilisation et commandes
↳ Interface Dashboard
↳ CLI Locale (Admin)
Système de Plugins
↳ Structure d'un plugin
↳ API du Plugin
Trucs et astuces
FAQ
Ressources et liens utiles

Présentation générale

AAUL (Agent Auto Update Linux) est une solution open-source de gestion de parc informatique et d’automatisation des mises à jour. Le projet est développé dans l’écosystème Auxinux avec une approche simple, auto-hébergeable et orientée administration réelle.

AAUL repose sur deux composants majeurs : un Dashboard côté serveur, qui centralise la gestion, et un Agent léger installé sur les machines clientes. Le Dashboard pilote les opérations, tandis que l’Agent contacte périodiquement le serveur, reçoit des commandes et remonte les informations utiles.

Le projet vise à offrir une administration cohérente sur plusieurs plateformes tout en gardant un code lisible, une installation simple et une architecture ouverte aux extensions. Il prend aujourd’hui en charge plusieurs environnements Linux, ainsi que macOS et Windows pour le cycle d’installation et de mise à jour.

Historique et versions

AAUL a beaucoup évolué au fil des refontes du projet. Les versions actuellement visibles dans le code sont :

Dashboard : version 0.5.0
Agent : version 0.3.0

Le projet a connu plusieurs améliorations importantes :

durcissement de la sécurité du dashboard et des tokens agent
ajout d’une CLI locale AAUL pour l’administration du serveur
compatibilité élargie aux distributions basées sur APT, DNF/YUM et PACMAN
prise en charge moderne de macOS et Windows 11 dans le cycle d’installation et de mise à jour
amélioration de l’interface web et du système de plugins

Caractéristiques principales

Gestion centralisée : visualisation de l’état des agents, version, dernier contact, dernières commandes et statut global.
Orchestration des mises à jour : possibilité de déclencher des mises à jour système à distance selon la plateforme gérée.
Auto-update de l’agent : l’agent peut se mettre à jour automatiquement depuis le bundle servi par le Dashboard.
Architecture plugin : ajout possible de routes, hooks et éléments d’interface sans modifier directement le cœur du projet.
Multi-plateforme : support des environnements Linux, macOS et Windows 11 selon les capacités actuellement intégrées.
CLI locale : commande AAUL pour administrer l’instance serveur localement.

Prérequis système

Dashboard (Serveur)

OS recommandé : Linux avec systemd
Node.js : environnement Node.js moderne compatible avec le projet
Base de données : SQLite intégrée au projet
Réseau : le serveur doit être joignable par les agents sur l’URL locale ou internet configurée

Agent (Client)

Linux : distributions basées sur APT, YUM / DNF et PACMAN
macOS : prise en charge des mises à jour système modernes
Windows : Windows 11 avec prise en charge du cycle de mise à jour prévu par l’agent
Réseau : accès sortant vers le Dashboard

Installation détaillée

Installation du Dashboard

La méthode standard actuelle repose sur le script d’installation du projet.

cd autoupdatelinux
sudo ./install.sh

Ce script :

installe ou met à jour l’instance dans /opt/AAUL
préserve les données sensibles et runtime lors d’une mise à jour
construit le frontend
génère le bundle agent
installe le service agentautoupdate-dashboard
installe la CLI locale AAUL

Déploiement de l'Agent

L’installation d’un agent se fait depuis le Dashboard. L’administrateur crée un agent, puis le Dashboard génère un lien d’installation et des commandes adaptées à la plateforme cible.

Le flux réel est le suivant :

création de l’agent dans l’interface
génération d’un token d’installation
utilisation d’une URL du type /install?token=...
téléchargement du script d’installation puis exécution locale sur la machine cible

Le Dashboard propose automatiquement les commandes appropriées pour Linux, macOS et Windows.

Configuration de base

La configuration principale du Dashboard se trouve dans le projet côté serveur, notamment via :

le fichier dashboard/config/config.json
les variables d’environnement prévues dans dashboard/.env.example
les réglages accessibles depuis l’interface d’administration

Parmi les paramètres importants :

adresse locale ou internet utilisée pour générer les commandes d’installation
ports HTTP / HTTPS
poll par défaut des agents
horaire quotidien par défaut
activation de l’auto-update agent

Utilisation et commandes

Interface Dashboard

L’interface web permet notamment de :

créer un nouvel agent
générer les commandes d’installation
suivre l’état de santé de la flotte
déclencher des actions comme RUN_NOW, UPDATE_AGENT, UNINSTALL ou la planification d’un horaire
afficher les détails d’un agent, ses informations système et ses logs
gérer les plugins et les utilisateurs admin

CLI Locale (Admin)

Sur le serveur Dashboard, la commande AAUL permet un contrôle local direct :

AAUL -status
AAUL -version
AAUL -reset-admin
AAUL -agent -list
AAUL -agent -update ID
AAUL -agent -remove ID
AAUL -start
AAUL -stop
AAUL -restart
AAUL -show-url
AAUL -show-ip
AAUL -show-ip-public

Cette CLI est utile pour les opérations de maintenance, de diagnostic ou de reprise en main locale.

Système de Plugins

AAUL dispose d’un système de plugins en JavaScript côté serveur. Il permet d’étendre le Dashboard sans modifier directement le cœur principal.

Structure d'un plugin

Un plugin est un dossier placé dans dashboard/server/plugins/ contenant au minimum :

un package.json
un index.js

Exemple minimal :

{
  "name": "mon-plugin",
  "version": "1.0.0",
  "description": "Exemple de plugin AAUL",
  "author": "Votre nom",
  "license": "MIT",
  "main": "index.js",
  "type": "module",
  "aaul": {
    "displayName": "Mon Plugin",
    "category": "monitoring",
    "permissions": ["agents:read", "settings:read"]
  }
}

API du Plugin

Le fichier index.js exporte généralement un objet avec un cycle de vie clair :

onLoad(context) : point d’entrée principal
onUnload() : nettoyage lors de la désactivation
onServerReady(context) : initialisation une fois les serveurs prêts

Le contexte peut fournir notamment :

registerRoute()
registerHook()
registerUI()
db
config
log()

Exemple d’enregistrement d’une route API sécurisée :

registerRoute("/api/mon-plugin/status", {
  method: "GET",
  middleware: [requireAdmin],
  handler: async (req, res) => {
    res.json({ ok: true, message: "Le plugin fonctionne" });
  }
});

Exemple d’ajout d’un lien dans le menu :

registerUI("nav:item", {
  label: "Mon Plugin",
  href: "/api/mon-plugin/status",
  icon: "🧩",
  adminOnly: true
});

Trucs et astuces

Commencer petit : valider d’abord une machine de test avant de déployer plus largement.
URL d’installation : toujours vérifier que l’URL locale ou internet utilisée par les agents est réellement joignable.
Logs : utiliser la vue Logs du dashboard pour comprendre un agent silencieux ou une commande en erreur.
CLI locale : la commande AAUL est souvent le moyen le plus rapide pour diagnostiquer un serveur.
Plugins : ne charger que du code relu et compris, car un plugin tourne avec les mêmes privilèges que le dashboard.

FAQ

Q: L’agent ne remonte pas dans le Dashboard.
R: Vérifiez d’abord l’URL générée lors de l’installation, la connectivité réseau vers le Dashboard et les logs côté agent ou côté serveur.

Q: Puis-je mettre à jour une installation déjà en production ?
R: Oui. Le script install.sh gère aussi le mode update et préserve les données sensibles lors d’une mise à niveau.

Q: Les plugins sont-ils sûrs ?
R: Un plugin doit être considéré comme du code de confiance. Il faut le relire avant activation.

Q: AAUL est-il uniquement Linux ?
R: Non. Le nom historique reste, mais le projet gère aussi macOS et Windows 11 dans son cycle actuel de déploiement et de mise à jour.

Ressources et liens utiles

Dépôt officiel GitHub : github.com/aporler/AAUL
Instance du projet : aaul.auxinux.ca
Wiki Auxinux : https://auxinux.ca/wiki/wiki-projet-aaul
Licence : MIT

AAUL - Agent Auto Update Linux