subnera-agent : rapporter un Mac à votre hub en ligne de commande

subnera-agent est le pendant en ligne de commande de l'application de barre des menus subnera. Il rapporte un Mac à votre subnera hub et, si vous l'autorisez, exécute les commandes à distance du hub, sans barre des menus ni fenêtre. Ce guide couvre son installation, sa liaison au hub, et les soucis les plus probables.

Pour qui

Pour un Mac utilisé comme serveur : personne n'est devant. Train at Home étant lui-même une application graphique, ce Mac doit avoir une session utilisateur ouverte, c'est-à-dire en pratique la connexion automatique (Réglages Système → Utilisateurs et groupes) et un réglage d'énergie qui l'empêche de s'endormir (voir garder un Mac éveillé). Si vous utilisez déjà l'application de barre des menus sur un Mac, l'agent y est inutile : un seul des deux par Mac.

Prérequis : macOS 13 ou ultérieur, Apple silicon.

Si ce Mac est déjà lié par subnera-agent, l'application de barre des menus subnera affiche ce lien en lecture seule et ne rapporte pas d'elle-même : le Mac n'est jamais compté deux fois. Lancez subnera-agent unlink pour utiliser l'application à la place.

Installation

Le plus simple est la commande en une ligne fournie par votre hub. Dans le hub, ouvrez votre pool et appuyez sur + Ajouter une machine : ouvrez l’onglet CLI (serveur) : le panneau affiche une commande prête à coller et un bouton Copier la commande. Collez-la dans le Terminal du Mac serveur :

curl -fsSL https://subnera.com/install.sh | SUBNERA_HUB=<url-du-hub> SUBNERA_TOKEN=<jeton-d-installation> sh

L'URL du hub doit être en https:// (http:// n'est accepté que pour localhost). Elle fait trois choses, dans cet ordre : installer l'agent, lier ce Mac à votre hub, puis le démarrer à la connexion. La relancer est sans danger : un Mac déjà lié conserve son lien. Si une étape échoue, le script dit laquelle et affiche les commandes manuelles pour terminer.

Le jeton est lu dans l'environnement : il n'apparaît donc pas dans ps (ni dans les arguments de la commande). Il peut en revanche rester dans l'historique du shell, c'est pourquoi il ne sert qu'une fois et expire au bout d'une heure : une fois utilisé, la copie de l'historique ne vaut plus rien.

En deux étapes

Pour installer d'abord puis lier vous-même (le jeton ne passe alors pas par un tube) :

curl -fsSL https://subnera.com/install.sh | sh

Le script vérifie d'abord qu'il s'agit d'un Mac Apple silicon sous macOS. Il télécharge ensuite latest.json et sa signature latest.json.sig, puis vérifie la signature avec la clé de publication de subnera grâce à l'openssl fourni par macOS ; si la signature manque ou ne correspond pas, il s'arrête et n'installe rien. Alors seulement, il télécharge l'archive de l'agent et compare son sha256 à celui du latest.json signé ; en cas de différence, il s'arrête et n'installe rien. Il installe dans ~/.local/bin/subnera-agent et n'utilise jamais sudo. Sans SUBNERA_HUB ni SUBNERA_TOKEN, il ne lie rien : poursuivez avec les deux sections suivantes (subnera-agent link <url-du-hub> <jeton-d-installation>, puis subnera-agent install).

Si ~/.local/bin n'est pas dans votre PATH, le script affiche la ligne à ajouter :

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zprofile && exec zsh -l

Installation manuelle

Si vous préférez ne pas envoyer un script dans un shell, téléchargez l'archive de l'agent depuis la page de téléchargement↗, qui affiche aussi son SHA-256, puis :

shasum -a 256 subnera-agent-*-macos-arm64.tar.gz   # à comparer avec le SHA-256 de la page de téléchargement
tar -xzf subnera-agent-*-macos-arm64.tar.gz subnera-agent
mkdir -p ~/.local/bin && install -m 0755 subnera-agent ~/.local/bin/subnera-agent
xattr -d com.apple.quarantine ~/.local/bin/subnera-agent   # un téléchargement navigateur est en quarantaine

Lier au hub

Si vous avez utilisé la commande en une ligne, le Mac est déjà lié : passez à la section sur le contrôle à distance ou vérifiez avec subnera-agent status. Sinon, dans le hub, appuyez sur + Ajouter une machine : le panneau affiche l'URL du hub et un jeton commençant par tok_ (voir connecter un Mac). Puis :

subnera-agent link https://app.subnera.com <jeton-d-installation>

Le jeton est valable une heure et ne sert qu'une fois. link enregistre la clé de ce Mac dans ~/Library/Application Support/subnera/agent.json et démarre avec le contrôle à distance désactivé. La commande refuse de s'exécuter si l'application de barre des menus subnera lie déjà ce Mac, ou si ce Mac est déjà lié (lancez d'abord subnera-agent unlink, qui laisse le Mac listé dans le hub tant que vous ne l'y retirez pas).

Démarrer à la connexion

La commande en une ligne le fait déjà. Sinon :

subnera-agent install

Cela écrit un LaunchAgent utilisateur, ~/Library/LaunchAgents/com.subnera.agent.plist, et le démarre. L'agent revient ensuite à chaque connexion et après un plantage. Son journal est ~/Library/Logs/subnera/agent.log. Relancer install est sans danger. subnera-agent run fait le même travail au premier plan (c'est ce que lance launchd), pratique pour le voir tourner ; arrêtez-le avec Ctrl-C.

Contrôle à distance

subnera-agent remote on
subnera-agent remote off

Il est désactivé par défaut. Une fois activé, le hub peut démarrer, arrêter ou redémarrer Train at Home sur ce Mac, et activer ou désactiver le watchdog. Désactivé, ces commandes sont refusées. Le changement s'applique à la commande suivante, sans redémarrage. Lisez ce que permet le contrôle à distance avant de l'activer.

Vérifier

subnera-agent status

La commande affiche, une par ligne :

• la version de l'agent ;
• hub, l'URL du hub, et machine, l'identifiant de ce Mac dans le hub ;
• key, les quatre derniers caractères de la clé (jamais la clé entière) ;
• remote et update check, chacun on ou off ;
• daemon : en cours d'exécution, installé mais arrêté, ou non installé ;
• last report : l'heure du dernier rapport reçu par le hub, ou depuis quand l'agent est hors ligne et pourquoi ;
• official app : si Train at Home tourne ;
• update, seulement quand une version plus récente existe.

Le code de sortie est 0 quand le Mac est lié et a rapporté dans les deux dernières minutes, 1 sinon, ce qui convient à un script de supervision :

subnera-agent status >/dev/null || echo "subnera-agent ne rapporte plus"

Mettre à jour

subnera-agent update            # télécharge, vérifie et installe la dernière version
subnera-agent update --check    # indique seulement si une version plus récente existe
subnera-agent update --auto on  # l'agent en cours installe lui-même les mises à jour (off par défaut)

update n'accepte une version que si le téléchargement correspond au SHA-256 du manifeste signé, si sa signature de code est valide et si --version annonce la bonne version ; il remplace ensuite le binaire et relance l'agent s'il démarre à la connexion. Détails dans le guide des mises à jour.

Où se trouvent les choses

Quoi	Où
Lien, clé et réglages	~/Library/Application Support/subnera/agent.json (mode 600, dans un dossier 700)
Ce que le démon a vu en dernier (pour status)	agent-state.json, dans le même dossier
LaunchAgent	~/Library/LaunchAgents/com.subnera.agent.plist
Journal	~/Library/Logs/subnera/agent.log
Binaire	~/.local/bin/subnera-agent

Désinstaller

subnera-agent uninstall            # arrête l'agent et retire le LaunchAgent
subnera-agent uninstall --purge    # supprime aussi le fichier de liaison et l'état de l'agent
rm ~/.local/bin/subnera-agent      # le binaire lui-même

Retirez ensuite le Mac dans le hub, où il reste listé après une désinstallation locale.

Dépannage

Symptôme	Que faire
Une commande (run, status, link, remote, update-check) échoue avec le code 78 et le message « is readable by other users. Fix it with: chmod 600 '…' »	L'agent refuse de travailler avec un fichier de clé ou un dossier lisible par d'autres utilisateurs. Sous launchd, il est relancé à cadence ralentie : l'échec persiste tant que vous n'avez pas corrigé les permissions. Lancez la commande chmod affichée (700 pour le dossier). Si le message dit que le fichier ne vous appartient pas, supprimez-le et relancez link.
link répond « This Mac is already linked by subnera.app »	L'application de barre des menus rapporte déjà ce Mac. Déliez-la d'abord dans l'application, ou gardez l'application et renoncez à l'agent.
status indique « not linked (revoked by the hub …) »	Le Mac a été retiré dans le hub. Créez un nouveau jeton avec + Ajouter une machine et relancez link.
install échoue avec une erreur launchctl	Un LaunchAgent exige une session utilisateur ouverte, comme Train at Home. Ouvrez une session (ou activez la connexion automatique), puis relancez install.
official app: affiche unknown ou not running	unknown signifie que l'agent n'a pas encore rapporté : regardez la ligne daemon:. not running signifie que Train at Home ne tourne pas pour cet utilisateur : ouvrez-le (voir le guide d'installation).

Aide

subnera-agent help liste toutes les commandes, et subnera-agent <commande> --help (ou subnera-agent help <commande>) décrit l'une d'elles. subnera-agent --version affiche la version. L'agent vérifie aussi une fois par jour s'il existe une version plus récente, ce que vous pouvez désactiver avec subnera-agent update-check off ; voir le guide des mises à jour.