SPB Git

Repository Public

OPERATIONS.md 30.6 KB

# 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 :

sh
~/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, voir services/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:8800 sur 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

sh
createdb mcc          # PostgreSQL local, écoute en loopback

Les 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 :

sh
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=UTC

Le 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

sh
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

sh
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 status

Observé 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) :

sh
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-api ou 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é)

sh
git checkout <commit précédent>
make build && make web-release
pm2 restart mcc-control-api mcc-telemetry-ingest mcc-action-orchestrator mcc-web

Il 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

sh
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)

sh
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

sh
# 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

sh
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

sh
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)

sh
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

sh
~/.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-agent

Mise à 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 ») :

json
{
  "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
}
sh
chmod 600 ~/.mcc-agent/policy.json && ~/.mcc-agent/bin/mcc-agent policy check

Les 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 :

sh
touch ~/.mcc-agent/FREEZE      # l'agent refuse toute commande (raison « frozen ») ; la télémétrie continue
rm ~/.mcc-agent/FREEZE         # retour à la normale

# 6. 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

sh
scripts/mccctl backup --dir ~/mcc-backups --keep 14 --copy-to mcc-backup:backups/maclustr-command-center
  • pg_dump (format personnalisé) chiffré au fil de l'eau en AES-256-GCM par blocs de 64 Kio, clé ~/.config/mcc/backup.key. Le fichier mcc-*.dump.enc n'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 : copie rsync vers 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 --keep sont 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

sh
scripts/mccctl backup-verify --file ~/mcc-backups/mcc-….dump.enc     # authentifie et lit le catalogue
scripts/mccctl restore-test --dir ~/mcc-backups                      # dernière sauvegarde

restore-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

sh
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 :

  1. scripts/mccctl freeze ; arrêter les quatre processus sur l'ancien nœud (les agents commencent à tamponner : fenêtre de 6 h).
  2. scripts/mccctl backup --dir ~/mcc-backups puis backup-verify.
  3. Copier le fichier de sauvegarde et ~/.config/mcc/ (mode 0700/0600) vers le nouveau nœud.
  4. Nouveau nœud : prérequis (§1.1), createdb mcc, scripts/mccctl restore --file … --to …/mcc.
  5. Construire, démarrer, basculer la route publique.
  6. scripts/mccctl status, audit-verify, puis unfreeze.

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 :

  1. Geler les commandes : scripts/mccctl freeze. La télémétrie et la consultation continuent.
  2. Couper un nœud : touch ~/.mcc-agent/FREEZE sur le nœud, ou révoquer son agent.
  3. 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.
  4. Fermer l'exposition publique : retirer la route du domaine sur la passerelle (outil de déploiement).
  5. Retirer les agents : uninstall.sh sur 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).

Files main
Menu

Theme