Exploitation — MacLustr Command Center
État décrit : commit 45f0d03, déploiement du 2026-11-18 sur le nœud hôte M4M64c. Les faits [prod] ont été
observés par le responsable du déploiement ; ils ne sont pas vérifiables depuis ce dépôt. Les procédures marquées
(non exercée) sont déduites du code et n'ont jamais été déroulées en conditions réelles.
Documents liés : ARCHITECTURE.md · SECURITY.md · AGENT-PROTOCOL.md · API.md · ADR 0009.
0. Repères
| Élément | Valeur en production [prod] |
|---|---|
| URL publique | https://clustr.spboucher.ai |
| Nœud hôte | M4M64c (Mac Studio M4 Max) |
| Répertoire | ~/apps/maclustr-command-center = clone git de gitsrv:srv/git/maclustr-command-center.git |
| Processus PM2 | mcc-control-api (0.0.0.0:8800), mcc-telemetry-ingest (127.0.0.1:8801 mTLS, 8804 requêtes signées, 8805 santé), mcc-action-orchestrator (127.0.0.1:8802), mcc-web (127.0.0.1:8803), mcc-backup (cron 40 3 * * *) |
| Base | PostgreSQL 17, base mcc, postgres://127.0.0.1/mcc?sslmode=disable |
| Secrets | ~/.config/mcc/ (AC des agents, clés de signature, clé CSRF, clé de sauvegarde) |
Configuration de mccctl |
~/.config/mcc/env (aucun secret) |
| Sauvegardes | ~/mcc-backups sur l'hôte + copie sur M3U96b (backups/maclustr-command-center) |
| Manifeste de déploiement | infra/deploy/mld-manifest.json |
mccctl s'exécute sur l'hôte, par SSH, avec le lanceur qui charge la configuration :
~/apps/maclustr-command-center/scripts/mccctl <commande> [options]Commandes (services/cmd/mccctl/) : migrate, bootstrap-owner, recovery-invite, audit-verify,
audit-verify-export, freeze, unfreeze, status, backup, backup-verify, restore, restore-test,
enroll-token, register-node. Les opérations qui changent un état écrivent une entrée d'audit actor_kind=cli.
1. Installation à partir de zéro
1.1 Prérequis de l'hôte
D'après infra/deploy/mld-manifest.json (requires) et le Makefile :
- macOS sur Apple Silicon (les binaires sont construits pour
darwin/arm64), toujours allumé, session ouverte ; - Homebrew avec
go(1.26, voirservices/go.mod),node,pnpm,pm2,postgresql@17; - ports libres 8800 à 8805 ; ≈ 3 Go de mémoire disponibles ;
- une route publique
https://clustr.spboucher.ai→hôte:8800sur la passerelle, avec prise en charge des connexions longues (SSE, long-poll des agents) ; le DNS du domaine pointe sur la passerelle ; - l'adresse de la passerelle vue par l'hôte dans
MCC_TRUSTED_PROXIES(production :10.67.0.1,127.0.0.1), sinon toutes les requêtes semblent venir de la même adresse et partagent les limites de débit par IP.
1.2 Base de données
createdb mcc # PostgreSQL local, écoute en loopbackLes migrations (services/internal/db/migrations/) sont appliquées automatiquement au démarrage de control-api
et d'action-orchestrator, ou explicitement par scripts/mccctl migrate. Une migration déjà appliquée puis
modifiée est refusée (somme de contrôle).
1.3 Configuration
Variables MCC_* (liste complète et défauts : services/internal/config/config.go). Valeurs de production,
identiques pour les trois services et mcc-backup dans le manifeste :
MCC_ENV=prod
MCC_DATABASE_URL=postgres://127.0.0.1/mcc?sslmode=disable
MCC_SECRETS_DIR=$HOME/.config/mcc
MCC_PUBLIC_ORIGIN=https://clustr.spboucher.ai
MCC_RP_ID=clustr.spboucher.ai
MCC_API_LISTEN=0.0.0.0:8800
MCC_TRUSTED_PROXIES=10.67.0.1,127.0.0.1
MCC_WEB_UPSTREAM=http://127.0.0.1:8803
MCC_INGEST_LISTEN=127.0.0.1:8801
MCC_ORCHESTRATOR_LISTEN=127.0.0.1:8802
MCC_INGEST_SIGNED_LISTEN=127.0.0.1:8804
MCC_INGEST_HEALTH_LISTEN=127.0.0.1:8805
MCC_INGEST_ADVERTISE=https://clustr.spboucher.ai
MCC_APPLE_APP_IDS=3YM54G49SN.ai.spboucher.clustr,3YM54G49SN.ai.spboucher.clustr.ios
TZ=UTCLe même contenu (sans secret) va dans ~/.config/mcc/env pour scripts/mccctl. En prod, le démarrage échoue si
l'origine n'est pas en https ou si MCC_RP_ID vaut localhost (config.validate).
Les secrets ne se configurent pas : chaque service crée le sien au premier démarrage dans MCC_SECRETS_DIR
(fichiers 0600). Inventaire : SECURITY.md §11.
1.4 Construction et démarrage
cd ~/apps/maclustr-command-center
make build # dist/control-api, telemetry-ingest, action-orchestrator, mccctl + SHA256SUMS.backend
make web-release # serveur Next « standalone » assemblé dans dist/web (node dist/web/server.js)En production ces deux cibles sont les crochets post_sync du manifeste : le produit a été placé et démarré avec
l'outil de déploiement existant du cluster, mld, à partir de infra/deploy/mld-manifest.json. La syntaxe de mld
appartient à cet outil et n'est pas documentée dans ce dépôt. Sans mld, il faut créer les cinq processus PM2
décrits dans le manifeste (processes[] : script, args, cwd, env, autorestart, max_memory_restart,
cron_restart) et la route publique vers le port 8800.
Ordre conseillé au premier démarrage : mcc-telemetry-ingest (crée l'AC et la publie dans settings['pki.ca'],
ce dont mccctl enroll-token a besoin), mcc-action-orchestrator (crée la clé de commande, inscrit les règles
d'alerte intégrées), mcc-control-api, mcc-web.
1.5 Vérification
curl -fsS https://clustr.spboucher.ai/api/v1/health/ready # {"status":"ok"} ; 503 si la base ne répond pas
curl -fsS https://clustr.spboucher.ai/api/v1/version
curl -fsS https://clustr.spboucher.ai/.well-known/apple-app-site-association
curl -fsS http://127.0.0.1:8805/healthz # ingestion (sur l'hôte) ; donne ca_fingerprint
curl -fsS http://127.0.0.1:8802/health/ready # orchestrateur (sur l'hôte)
scripts/mccctl statusObservé le 2026-11-18 [prod] : santé, version et AASA publics ; HSTS et en-têtes de sécurité ; CSP à nonce sur
les pages ; options WebAuthn avec rpId=clustr.spboucher.ai et userVerification=required ; POST inter-origine
refusé (403) ; requête non signée vers /agent/v1/report refusée (401).
2. Mise à jour et retour arrière
2.1 Mise à jour
Sur l'hôte (le répertoire déployé est un clone git) :
cd ~/apps/maclustr-command-center
git pull
make build && make web-release
pm2 restart mcc-control-api mcc-telemetry-ingest mcc-action-orchestrator mcc-web
scripts/mccctl statusÀ savoir :
- Le serveur avant les agents. Un agent qui envoie une métrique inconnue du serveur voit son rapport refusé (AGENT-PROTOCOL.md §12). Mettre à jour le plan de contrôle, puis les agents.
- Les migrations nouvelles s'appliquent au redémarrage de
control-apiou de l'orchestrateur. - Pendant le redémarrage : les agents tamponnent et rejouent ; les sessions survivent (elles sont en base) ; les
clients SSE reprennent avec
Last-Event-ID; une action en vol est réconciliée, jamais ré-émise. - Les limites de débit et le cache de nonces de l'ingestion sont en mémoire et repartent de zéro.
make ci(voir README) est le seul garde-fou avant de pousser : il n'y a pas de CI hébergée.
2.2 Retour arrière (non exercé)
git checkout <commit précédent>
make build && make web-release
pm2 restart mcc-control-api mcc-telemetry-ingest mcc-action-orchestrator mcc-webIl n'existe pas de migrations descendantes. Si la version à annuler a ajouté une migration, l'ancien binaire tournera sur un schéma plus récent : ce cas n'a pas été testé. La voie sûre est alors de restaurer la sauvegarde précédant la mise à jour (§7.3), en acceptant de perdre les données écrites depuis.
3. Premier owner et récupération de compte
3.1 Amorçage du premier owner
scripts/mccctl bootstrap-owner --handle <identifiant> --name "<Nom affiché>" [--ttl 15m]La commande imprime une seule fois un lien https://clustr.spboucher.ai/setup#<jeton> (usage unique, 15 min
par défaut, 24 h au plus). L'ouvrir sur l'appareil qui portera la passkey, créer la passkey : le compte owner
est créé et la session ouverte. La commande est refusée dès qu'un owner capable de se connecter existe
(owner_exists). Ne pas coller le lien dans une messagerie ou un ticket.
État au moment de la rédaction : cette étape n'a pas encore été faite en production ; c'est au propriétaire de l'exécuter avec sa propre passkey. Conseil : ajouter aussitôt une seconde passkey (Réglages → Sécurité), car la perte de la seule passkey impose la procédure de récupération.
3.2 Comptes suivants
Depuis l'interface (Réglages → Invitations) ou POST /invitations (invitations.manage + step-up). Un admin ne
peut pas inviter un owner.
3.3 Récupération d'un compte (passkeys perdues)
scripts/mccctl recovery-invite --handle <identifiant> [--ttl 15m]Ouvrir le lien sur le nouvel appareil et créer une passkey. Effets (FinishSetupRegistration) : toutes les
anciennes passkeys et sessions du compte sont révoquées ; le rôle est inchangé. Une seule invitation de
récupération peut être ouverte par compte (409 recovery_pending sinon). C'est le seul contournement prévu ; il
suppose l'accès SSH à l'hôte.
4. Agents
Binaires : bash agents/build.sh (ou make agents) produit dist/mcc-agent-darwin-arm64,
dist/mcc-agent-linux-amd64, dist/mcc-agent-linux-arm64 et dist/SHA256SUMS.
4.1 Enrôlement d'un Mac
# sur l'hôte : jeton à usage unique (15 min par défaut, 1 h au plus) + empreinte de l'AC
scripts/mccctl enroll-token --alias <alias>
# sur le Mac, avec l'utilisateur ordinaire (jamais root)
sh install.sh --binary ./mcc-agent-darwin-arm64 \
--endpoints https://clustr.spboucher.ai \
--token <jeton> --ca-fingerprint sha256:<hex>agents/macos/install.sh installe le binaire dans ~/.mcc-agent/bin/, enrôle l'agent s'il ne l'est pas, pose
~/Library/LaunchAgents/ai.spboucher.mcc-agent.plist et démarre le service. Il ne touche qu'au libellé
ai.spboucher.mcc-agent. Relancé sur une machine déjà enrôlée, il conserve l'identité.
| Mode | Quand | Fichier | sudo |
|---|---|---|---|
| LaunchAgent (défaut) | Mac avec session graphique ouverte | ~/Library/LaunchAgents/ai.spboucher.mcc-agent.plist |
non |
LaunchDaemon (--daemon) |
Mac sans session graphique | /Library/LaunchDaemons/ai.spboucher.mcc-agent.plist, avec UserName = l'utilisateur ordinaire |
une fois, pour installer le fichier |
Dans les deux modes l'agent tourne sous l'utilisateur ordinaire. Pour un --daemon non interactif :
SUDO="sudo -A" avec SUDO_ASKPASS. En production [prod] : LaunchAgent partout, sauf M2U64 et m4md
(pas de session graphique) installés en LaunchDaemon.
Point de terminaison. Utiliser l'URL publique. Un binaire lancé par launchd ne peut pas joindre le LAN sous
macOS (confidentialité du réseau local, mesurée sur m4ml — ADR 0004, amendement) ;
une adresse host:port (mTLS direct) ne fonctionne donc pas pour un agent géré par launchd sur ces machines.
4.2 Déploiement en série
bash agents/build.sh
DAEMON="M2U64 m4md" infra/deploy/rollout-agents.sh <alias> <alias>@<ip-lan> …infra/deploy/rollout-agents.sh traite un nœud à la fois et vérifie chacun (connection online dans
mcc-agent status) avant le suivant. <alias>@<ip-lan> passe par la passerelle SSH du cluster ; dans ce cas le
script exige que le marqueur ~/.maclustr-node de la machine soit égal à l'alias (une adresse n'est jamais prise
pour une identité). Variables : HOST (hôte du plan de contrôle, défaut M4M64c), GW (défaut M1M32),
DAEMON (alias installés en LaunchDaemon, défaut M2U64). Une machine déjà enrôlée ne reçoit que le binaire.
Déroulé du 2026-11-18 [prod] : pilote sur m4ml, puis déploiement progressif ; 28 Macs et la passerelle Linux
BHS64 rapportent. Totaux rapportés par les agents : 379 cœurs CPU et 1 032 Go de mémoire sur 28 Macs, identiques au
relevé en lecture seule de la phase 0 (REAL-INFRASTRUCTURE-INVENTORY.md).
4.3 Machine éteinte ou sans agent
scripts/mccctl register-node --alias <alias> [--kind mac|linux|nas] [--site …] [--role …] [--tags a,b]Le nœud apparaît hors ligne, sans fait matériel, jusqu'à ce qu'un agent s'enrôle sous le même alias. M4BP36 (portable éteint) a été inscrit ainsi [prod].
4.4 Linux (systemd)
scripts/mccctl enroll-token --alias <alias> --kind linux # sur l'hôte
sudo ./install.sh --binary ./mcc-agent-linux-amd64 \
--endpoints https://clustr.spboucher.ai --token <jeton> --ca-fingerprint sha256:<hex>agents/linux/install.sh crée l'utilisateur système mcc-agent, installe /usr/local/bin/mcc-agent, l'état dans
/var/lib/mcc-agent (0700) et l'unité agents/linux/mcc-agent.service (NoNewPrivileges, ProtectSystem=strict,
ProtectHome=yes, MemoryMax=256M, CPUQuota=50%, seule capacité CAP_NET_RAW pour le ping). En service sur
BHS64 [prod].
4.5 État, journaux, mise à jour
~/.mcc-agent/bin/mcc-agent status [--json] # Linux : sudo -u mcc-agent mcc-agent status --state-dir /var/lib/mcc-agent
~/.mcc-agent/bin/mcc-agent policy check
~/.mcc-agent/bin/mcc-agent version
tail -f ~/Library/Logs/mcc-agent/mcc-agent.log # Linux : journalctl -u mcc-agentMise à jour : relancer install.sh --binary <nouveau binaire> (remplacement atomique, identité conservée, service
relancé), ou rollout-agents.sh. Le certificat (30 jours) se renouvelle seul à mi-vie ; la règle d'alerte
« Agent certificate expiring » se déclenche à moins de 7 jours.
4.6 Révocation et désinstallation
| Opération | Commande |
|---|---|
| Révoquer (serveur) | Réglages → Agents, ou POST /agents/{id}/revoke (agents.manage + step-up). Effet en quelques secondes (401 agent_revoked) |
| Révoquer sans compte (non exercé) | il n'existe pas de commande mccctl de révocation ; en dernier recours, sur l'hôte : update agents set revoked_at = now(), revoked_reason = '<motif>' where id = '<id>' — non audité |
| Désinstaller un Mac | sh agents/macos/uninstall.sh (garde l'identité) ou --purge (efface ~/.mcc-agent et les journaux) |
| Désinstaller Linux | sudo ./uninstall.sh [--purge] |
| Ré-enrôler | nouveau jeton ; l'enrôlement révoque l'agent actif précédent du nœud (re-enrolled). Par l'API, il faut d'abord révoquer l'agent existant (409 sinon) |
| Retirer un nœud | DELETE /nodes/{id} (nodes.write + step-up) ; un nœud retiré ne peut plus être enrôlé (409 node_retired) |
Après un --purge, révoquer aussi l'agent côté serveur.
5. Politique locale et interrupteur d'arrêt de l'agent
Fichier <état>/policy.json (~/.mcc-agent/policy.json ; Linux : /var/lib/mcc-agent/policy.json), propriété du
propriétaire du nœud. Le serveur ne peut ni le lire ni le modifier.
| État du fichier | Effet |
|---|---|
| absent | quatre commandes de lecture : inventory.refresh, diagnostic.run, service.health_check, service.logs.tail |
| présent et valide | exactement ce qu'il autorise |
| invalide, ou inscriptible par le groupe ou les autres | toute commande est refusée |
Exemple validé avec mcc-agent policy check (adapter les chemins ; un cache dont le chemin n'existe pas est signalé
« NOT USABLE ») :
{
"allow": ["inventory.refresh", "diagnostic.run", "service.health_check", "service.logs.tail",
"service.restart", "cache.purge", "job.run", "job.cancel"],
"services": {"pm2": ["my-app", "my-app-*"], "launchd": ["com.example.worker"]},
"cache_roots": ["/Users/me/Library/Caches/my-app"],
"caches": {"thumbnails": "/Users/me/Library/Caches/my-app/thumbnails"},
"jobs": {
"report": {
"argv": ["/usr/bin/du", "-sk", "{path}"],
"params": {"path": {"type": "enum", "values": ["/Users/me/data", "/Users/me/logs"]}},
"timeout_s": 120
}
},
"allow_reboot": false,
"allow_shutdown": false
}chmod 600 ~/.mcc-agent/policy.json && ~/.mcc-agent/bin/mcc-agent policy checkLes types autorisés sont déclarés au serveur comme capacités (un modèle de job devient job.run:<nom>) ; une action
dont la capacité manque est refusée avant tout envoi (422 capability_missing). system.reboot et
system.shutdown exigent en plus allow_reboot / allow_shutdown et un sudo -n fonctionnel.
Référence : AGENT-PROTOCOL.md §8, services/internal/agent/policy/policy.go.
En production [prod] : aucun fichier de politique n'est déployé — tous les agents sont en lecture seule ; redémarrage et extinction sont désactivés partout.
Interrupteur d'arrêt local :
touch ~/.mcc-agent/FREEZE # l'agent refuse toute commande (raison « frozen ») ; la télémétrie continue
rm ~/.mcc-agent/FREEZE # retour à la normale6. Supervision du produit lui-même
| Source | Ce qu'elle montre |
|---|---|
GET /api/v1/health/live, /health/ready |
vie de control-api ; ready répond 503 si la base ne répond pas en 2 s. C'est le health_path du manifeste |
GET /api/v1/admin/status (settings.manage) ; écran Réglages → Système |
base (latence), battement de l'ingestion et de l'orchestrateur, agents connectés, dernier rapport reçu, clients SSE, gel, dernière sauvegarde observée |
scripts/mccctl status |
utilisateurs, owners, sessions, nœuds, agents, battements de chaque service |
Table service_heartbeats |
un battement toutes les 10 s par service ; /admin/status déclare un composant degraded au-delà de 30 s et down au-delà de 120 s ; absence totale de battement = unknown |
http://127.0.0.1:8805/healthz |
ingestion : base, AC, agents connectés |
http://127.0.0.1:8802/health/ready |
orchestrateur : dernière passe, gel, état APNs, dernière exécution de chaque tâche périodique |
Journaux PM2, ~/.pm2/logs/mcc-* |
JSON structuré, une ligne par requête avec correlation_id. control-api et l'orchestrateur écrivent sur la sortie standard (…-out.log), l'ingestion sur la sortie d'erreur (…-error.log) |
| Écran Stockage → Sauvegardes | résultat enregistré de chaque mccctl backup et restore-test (table backups) |
| Journal d'audit | scripts/mccctl audit-verify ; écran Audit |
Règles d'alerte intégrées (12, services/internal/alerts/rules.go) : nœud hors ligne, disque > 90 % et > 97 %,
pression mémoire (avertissement, critique), swap > 80 %, CPU saturé, service géré en erreur, certificat d'agent
proche de l'expiration, perte de paquets vers la passerelle, rafale de requêtes refusées, connexion d'un
owner/admin depuis un nouvel appareil. Alertes réelles levées juste après le déploiement [prod] : disque à
99,6 % sur M4M64b (critique), disque à 92 % sur M3U96b, swap > 80 % en attente sur M3U96a.
Ce qui n'existe pas : aucune supervision externe du plan de contrôle (si l'hôte tombe, rien ne prévient) et aucune
notification push (APNs inactif). Les versions affichées pour l'ingestion et l'orchestrateur ne sont pas
estampillées par make build (0.1.0-dev et dev) ; se fier à GET /api/v1/version et au commit du clone.
7. Sauvegarde et restauration
Source : services/internal/backup/, services/cmd/mccctl/backup.go.
7.1 Sauvegarde
scripts/mccctl backup --dir ~/mcc-backups --keep 14 --copy-to mcc-backup:backups/maclustr-command-centerpg_dump(format personnalisé) chiffré au fil de l'eau en AES-256-GCM par blocs de 64 Kio, clé~/.config/mcc/backup.key. Le fichiermcc-*.dump.encn'apparaît sous son nom final qu'une fois complet.- La sauvegarde est relue et authentifiée avant d'être déclarée réussie.
--copy-to: copiersyncvers un second nœud ; l'échec de la copie fait échouer la commande.- Le résultat est enregistré dans la table
backups; les fichiers locaux au-delà de--keepsont supprimés. - Planification : processus PM2
mcc-backup,cron_restart: 40 3 * * *,autorestart: false.
En production [prod] : première sauvegarde chiffrée créée, vérifiée et copiée sur M3U96b ; l'alias SSH
mcc-backup utilise une clé dédiée restreinte, côté M3U96b, par une commande forcée au dépôt rsync dans un seul
répertoire.
La clé backup.key doit exister ailleurs que sur l'hôte (gestionnaire de mots de passe ou autre machine).
Sans elle, les sauvegardes sont inutilisables après la perte du disque ; la sauvegarde ne contient pas
~/.config/mcc.
7.2 Vérification et test de restauration
scripts/mccctl backup-verify --file ~/mcc-backups/mcc-….dump.enc # authentifie et lit le catalogue
scripts/mccctl restore-test --dir ~/mcc-backups # dernière sauvegarderestore-test restaure dans une base temporaire mcc_restore_test_<suffixe> sur le même serveur, vérifie la chaîne
d'audit restaurée et la présence du schéma, affiche les comptes (migrations, utilisateurs, nœuds, lignes d'audit),
enregistre le résultat, puis supprime la base temporaire. La base de production n'est que lue. Il ne compare pas
ligne à ligne avec la base vivante. Exécuté avec succès sur l'hôte [prod].
Aucune planification automatique de restore-test n'existe : à lancer à la main, périodiquement.
7.3 Restauration
createdb mcc_restored
scripts/mccctl restore --file <fichier> --to "postgres://127.0.0.1/mcc_restored?sslmode=disable"restore refuse une base qui contient déjà des tables, puis affiche les comptes et vérifie la chaîne d'audit.
Pour remettre en service : arrêter les quatre processus, restaurer dans une base mcc vide (renommer l'ancienne),
redémarrer. Les agents rejouent leur tampon (6 h au plus) ; ce qui a été écrit entre la sauvegarde et l'incident
est perdu, sauf la télémétrie encore tamponnée.
8. Rotation des clés
Aucune rotation n'est outillée ni n'a été exercée. Procédures déduites du code ; tableau des clés : SECURITY.md §11.
| Clé | Procédure (non exercée) |
|---|---|
csrf.key |
pm2 stop mcc-control-api ; déplacer le fichier ; pm2 start. Sans effet sur les sessions |
audit-signing.key |
noter d'abord export_public_key (GET /audit/verify) pour les exports existants ; déplacer le fichier ; redémarrer mcc-control-api |
command-signing.key |
scripts/mccctl freeze ; pm2 stop mcc-action-orchestrator ; déplacer le fichier ; pm2 start (nouvelle clé créée et inscrite dans command_keys) ; marquer l'ancienne : update command_keys set retired_at = now() where key_id = '<ancien>' ; unfreeze. Chaque agent apprend la nouvelle clé par un renouvellement de certificat, déclenché quand il reçoit une commande portant un identifiant de clé inconnu — la première commande après rotation peut donc être refusée |
backup.key |
déplacer le fichier ; la prochaine sauvegarde en crée une nouvelle (à copier hors hôte). Garder l'ancienne tant que d'anciennes sauvegardes existent |
AC des agents (agent-ca.key, agent-ca.crt) |
pas de rotation sans interruption : arrêter l'ingestion, déplacer les deux fichiers, redémarrer (nouvelle AC publiée), puis ré-enrôler chaque agent (uninstall.sh --purge, nouveau jeton, install.sh). L'AC est valide 10 ans |
| Certificats d'agents | automatique (30 jours, renouvelés à mi-vie par l'agent) |
| Clé SSH de copie des sauvegardes | remplacer la clé sur l'hôte et l'entrée authorized_keys restreinte sur le second nœud |
9. Déplacer le plan de contrôle vers un autre nœud
(non exercé). Le manifeste épingle l'app (placement.pin: M4M64c) parce que ni la base ni les secrets ne
suivent un déplacement fait par l'outil de déploiement. Ce qui doit suivre :
| Élément | Pourquoi | Comment |
|---|---|---|
Base mcc |
tout l'état : comptes, passkeys, sessions, nœuds, agents, audit, séries | sauvegarde fraîche puis restore sur le nouveau nœud |
~/.config/mcc/agent-ca.key + .crt |
sans la même AC, tous les agents doivent être ré-enrôlés | copie sécurisée du répertoire entier |
~/.config/mcc/command-signing.key |
sinon nouvelle clé, que les agents doivent réapprendre | idem |
~/.config/mcc/audit-signing.key |
vérification des exports déjà produits | idem |
~/.config/mcc/backup.key |
nécessaire pour restaurer et pour continuer les sauvegardes | idem (et copie hors hôte) |
~/.config/mcc/csrf.key |
facultatif (les clients relisent leur jeton) | idem |
~/.config/mcc/env |
configuration de mccctl |
idem |
Clé SSH et alias mcc-backup |
copie hors hôte des sauvegardes | à recréer |
Route publique et MCC_TRUSTED_PROXIES |
le domaine doit viser le nouveau nœud:8800 |
passerelle / outil de déploiement ; mettre à jour placement.pin dans le manifeste |
Séquence proposée :
scripts/mccctl freeze; arrêter les quatre processus sur l'ancien nœud (les agents commencent à tamponner : fenêtre de 6 h).scripts/mccctl backup --dir ~/mcc-backupspuisbackup-verify.- Copier le fichier de sauvegarde et
~/.config/mcc/(mode 0700/0600) vers le nouveau nœud. - Nouveau nœud : prérequis (§1.1),
createdb mcc,scripts/mccctl restore --file … --to …/mcc. - Construire, démarrer, basculer la route publique.
scripts/mccctl status,audit-verify, puisunfreeze.
Les agents n'ont rien à changer : ils parlent à https://clustr.spboucher.ai et vérifient la même AC. Les sessions
des utilisateurs restent valides (elles sont dans la base restaurée, et l'origine ne change pas).
10. Environnements de développement et de test
Voir le README : pile locale, make ci, test de bout en bout tests/e2e/local-stack.sh, suite
Playwright (apps/web/e2e/run.mjs). Les outils telemetry-ingest dev-token, dev-proxy, migrate et
mcc-devlogin refusent de s'exécuter quand MCC_ENV=prod.
11. Dépannage
| Symptôme | Cause probable | Correction |
|---|---|---|
mccctl : missing ~/.config/mcc/env |
fichier de configuration absent | le créer (§1.3) ou MCC_ENV_FILE=<chemin> |
mccctl enroll-token : « the agent CA is not published yet » |
l'ingestion n'a jamais démarré avec la base | démarrer mcc-telemetry-ingest, vérifier :8805/healthz |
mccctl bootstrap-owner : owner_exists |
un owner peut déjà se connecter | invitation normale, ou recovery-invite |
mcc-control-api redémarre en boucle |
base injoignable au démarrage (il n'attend pas), ou configuration prod invalide (origine non https, MCC_RP_ID=localhost) |
vérifier PostgreSQL et ~/.pm2/logs/mcc-control-api-*.log |
Pages en 503 unavailable, API correcte |
mcc-web arrêté |
pm2 restart mcc-web ; vérifier que dist/web/server.js existe (make web-release) |
Tous les nœuds stale puis offline |
ingestion arrêtée, ou chemin public coupé | pm2 logs mcc-telemetry-ingest ; les agents rejouent jusqu'à 6 h |
Un nœud offline |
machine éteinte ou en veille, agent arrêté, agent révoqué | sur le nœud : mcc-agent status, journal de l'agent |
install.sh : « no graphical session … use --daemon » |
pas de session graphique ouverte | relancer avec --daemon |
Agent : connect: no route to host vers une adresse LAN |
confidentialité du réseau local de macOS (binaire lancé par launchd) | utiliser --endpoints https://clustr.spboucher.ai |
Agent : 401 timestamp_out_of_window ou 400 clock_skew |
horloge du nœud fausse (> 90 s) | corriger l'heure |
Agent : 401 agent_revoked |
agent révoqué ou remplacé par un ré-enrôlement | nouveau jeton, ré-enrôler |
Enrôlement : 409 alias_in_use |
l'alias appartient à un autre matériel | choisir un autre alias, ou retirer l'ancien nœud |
Enrôlement : 429 |
plus de 6 tentatives/min depuis la même adresse | attendre (Retry-After) |
| Toute commande refusée par un agent | policy.json invalide ou trop permissif en droits de fichier ; fichier FREEZE présent |
mcc-agent policy check ; chmod 600 ; supprimer FREEZE |
Action : 422 capability_missing |
la politique locale du nœud n'autorise pas ce type | adapter policy.json sur le nœud (§5) |
Action : 422 agent_offline |
agent non vu depuis plus de 120 s | voir « un nœud offline » |
Action : 409 target_locked |
une autre action est en cours sur la cible | attendre ; details.action_id donne le détenteur |
Action timed_out, outcome_unknown |
commande remise, résultat jamais reçu | vérifier l'état réel sur le nœud avant de relancer |
503 orchestrator_frozen |
gel d'urgence actif | scripts/mccctl unfreeze après vérification |
Actions qui restent queued |
orchestrateur arrêté, ou gel | /admin/status, pm2 restart mcc-action-orchestrator |
403 step_up_required |
dernière cérémonie passkey vieille de plus de 5 min | refaire le step-up (l'interface le propose) |
403 csrf_failed |
en-tête X-MCC-CSRF ou Origin absent ; accès par une autre origine que MCC_PUBLIC_ORIGIN |
relire GET /me ; utiliser l'URL publique |
429 sur la page de connexion |
plus de 30 requêtes publiques/min depuis la même adresse (ou MCC_TRUSTED_PROXIES incomplet : tout le monde partage l'adresse de la passerelle) |
attendre ; corriger la liste des proxys |
| Sauvegarde : « off-host copy … failed » | alias SSH mcc-backup ou second nœud indisponible |
la sauvegarde locale existe ; rétablir la copie |
Restauration : authentication failed |
mauvaise backup.key, ou fichier altéré |
retrouver la clé d'origine |
/admin/status : sauvegarde unknown |
aucun mccctl backup enregistré |
lancer une sauvegarde |
| Réglage de rétention modifié sans effet | l'ingestion lit MCC_RETAIN_* au démarrage, pas le réglage |
changer la variable et redémarrer l'ingestion |
12. Arrêt d'urgence
Du moins au plus radical :
- Geler les commandes :
scripts/mccctl freeze. La télémétrie et la consultation continuent. - Couper un nœud :
touch ~/.mcc-agent/FREEZEsur le nœud, ou révoquer son agent. - Arrêter le plan de contrôle :
pm2 stop mcc-control-api mcc-telemetry-ingest mcc-action-orchestrator mcc-web. L'interface et l'API ne répondent plus ; les agents tamponnent ; aucune commande ne peut partir. - Fermer l'exposition publique : retirer la route du domaine sur la passerelle (outil de déploiement).
- Retirer les agents :
uninstall.shsur chaque nœud (ils n'écoutent sur aucun port ; arrêtés, ils ne font plus rien).
Reprise : démarrer l'ingestion, l'orchestrateur, l'API, le web ; status ; audit-verify ; unfreeze.
L'ancien produit n'est pas concerné par ces opérations (ADR 0001).