Utilisation

Ce parcours s'adresse aux opérateurs : obtenir les outils en ligne de commande et côté appareil, se connecter, ajouter un appareil, le connecter, puis exécuter une commande distante et ouvrir un shell. La console navigateur, la console mobile, l'Agent Android, l'appairage et la mise à jour automatique sont décrits dans les liens en fin de page ; leurs étapes ne sont pas répétées ici.

Remplacez les adresses et jetons des exemples par les vôtres. Un jeton n'est affiché qu'à sa création : ne l'enregistrez pas dans le dépôt.

Identités nommées et autorisations de compte. L’option globale --profile <name> prime sur REMOTE_CLI_PROFILE. config.toml, les clés privées, la confiance racine et les caches d’autorisations sont conservés dans <config_base>/remote-cli/profiles/<name>/. config_base conserve les conventions XDG_CONFIG_HOME, HOME/.config ou Windows APPDATA. Les noms acceptent 1 à 64 lettres ASCII, chiffres, points, tirets ou soulignements, sauf . et ... Un profil nommé prime sur REMOTE_CLI_CONFIG ; sans profil, les chemins et REMOTE_CLI_CONFIG restent inchangés. Connectez chaque profil séparément et sélectionnez-le lors des appels suivants.

operator set accepte un ID de compte ou un nom unique ; les arguments d’appareil sont des ID. --restricted limite la visibilité aux appareils explicitement autorisés ; --unrestricted rétablit la visibilité selon le rôle. Seul le superadmin peut modifier la portée. Il gère les rôles et autorisations ; en son absence, les admins agissent dans leur portée autorisée, sans modifier leurs propres droits. operator grant list ne renvoie que les autorisations visibles. Les droits en base et les autorisations signées sont deux contrôles distincts : leur modification ne remplace pas seal approve. La création ne permet pas d’attribuer atomiquement la portée. Conservez le jeton unique de operator add, puis utilisez operator set / operator grant set comme requêtes séparées.

Toutes les actions operator acceptent -o text|json|xml. JSON utilise op=list|add|set|grant_list|grant_set|grant_remove. set reçoit operator et au moins un champ parmi role / restricted ; grant_set reçoit operator, device et le booléen obligatoire can_manage. grant_list accepte operator en option ; grant_remove reçoit operator et device. Ne combinez pas --json avec une sous-commande.

remote-cli --profile alice login --server https://exchange.example.com
remote-cli --profile root operator set alice --restricted
remote-cli --profile root operator set alice --role readonly
remote-cli --profile root operator grant list --operator alice -o json
remote-cli --profile root operator grant set alice lab --view
remote-cli --profile root operator grant set alice lab --manage
remote-cli --profile root operator grant remove alice lab
remote-cli --profile root operator set alice --unrestricted
remote-cli --profile root operator --json '{"op":"grant_set","operator":"alice","device":"lab","can_manage":false}' -o json

Requêtes et sorties XML

Vérifiez les options de la version installée avec remote-cli --help. --xml et --xml-file ajoutent une entrée XML aux requêtes --json / --json-file existantes. Les quatre entrées sont exclusives et fournissent le corps complet : ne les combinez pas avec les mêmes options ou sous-commandes. Les arguments positionnels des appareils restent identiques. Entrée et sortie sont indépendantes ; -o text|json|xml utilise le texte par défaut.

remote-cli device --xml '<request><op>list</op></request>' -o xml
remote-cli exec my-device --xml-file request.xml -o xml

Une feuille est une chaîne par défaut ; un élément avec des enfants est un objet. Utilisez type="number", type="boolean", type="array" et type="null" pour les nombres, booléens, tableaux et null. Les tableaux contiennent des <item> ; les objets vides exigent type="object". Utilisez <field name="arbitrary key">value</field> pour une clé quelconque et <request type="object"/> pour une requête vide.

<request>
  <command>echo hello</command>
  <timeout_secs type="number">30</timeout_secs>
  <hold type="boolean">false</hold>
  <env><GREETING>hello &amp; welcome</GREETING></env>
</request>

La racine de sortie est <response type="...">, les membres des objets sont <field name="..." type="..."> et ceux des tableaux <item type="...">. Les types sont explicites et le texte est échappé selon XML 1.0. Les erreurs à l’exécution renvoient ok=false / error avec un code de sortie non nul ; les erreurs de syntaxe restent sur stderr.

La sortie XML prend en charge device list/update, operator list/add/set/grant, exec, session list/kill, ui, ubus, sensors, net, metrics, preset, audit, browser, y compris les opérations sur les tâches exec. Les autres commandes refusent explicitement -o xml ; elles acceptent toujours les requêtes XML avec leurs formats de sortie habituels.

Les flux exec / sensors --live / browser session produisent un document XML complet par ligne, à analyser séparément. Les événements de données exec contiennent stream / encoding=base64 / data ; Base64 conserve les octets originaux. Un exec normal se termine par son état de sortie. L’entrée interactive de browser session reste en JSON Lines. ui xml sans -o xml conserve le XML brut de la hiérarchie UI.

Les requêtes sont limitées à 1 MiB et 64 niveaux. Les champs dupliqués, le mélange de texte et d’éléments, les DTD et les entités externes sont refusés. Choisissez JSON pour conserver des caractères de contrôle non représentables en XML 1.0. La configuration Agent et le protocole réseau restent en JSON ; XML ne convertit que les entrées et sorties du CLI.

Obtenir remote-cli et remote-agent

Compilez depuis la racine du dépôt :

cargo build --release

L'outil en ligne de commande est target/release/remote-cli. Cette commande compile aussi target/release/remote-agent. Pour les appareils dont la mémoire flash est limitée, privilégiez l'agent optimisé en taille :

cargo build -p agent --no-default-features --profile release-small

Le résultat est target/release-small/remote-agent.

Sous Windows, Linux et macOS, les scripts d'installation du site permettent aussi d'installer l'un de ces exécutables en une commande ; voir Déploiement multiplateforme. Les commandes suivantes supposent que remote-cli et remote-agent sont dans le PATH ; après une compilation locale, utilisez plutôt les chemins target/... ci-dessus.

Pour un relais auto-hébergé, suivez d'abord le guide de développement afin de lancer exchange avec DATABASE_URL, puis récupérez le jeton administrateur dans les journaux de démarrage. Pour une instance publique, demandez un jeton opérateur à l'administrateur.

Connexion

remote-cli login --server http://127.0.0.1:8080 --token '<运维令牌>'

--server accepte http:// ou https://. Le CLI en déduit une adresse WebSocket de même niveau de sécurité : https devient wss, et http devient ws.

Après connexion, la configuration est enregistrée dans :

• Linux / macOS : $XDG_CONFIG_HOME/remote-cli/config.toml, ou ~/.config/remote-cli/config.toml si XDG_CONFIG_HOME n'est pas défini.
• Windows : %APPDATA%\remote-cli\config.toml.

Le fichier contient uniquement server et token. Définissez REMOTE_CLI_CONFIG pour utiliser un autre chemin. Les commandes device, exec et shell lisent ensuite cette configuration ; inutile de fournir le jeton à chaque fois.

Ajouter un appareil

remote-cli device add lab-router --name "实验室路由"

<id> est l'identifiant de l'appareil. Il accepte uniquement lettres, chiffres et - _ ., avec une longueur maximale de 64 caractères. --name est facultatif ; sans lui, le nom affiché correspond à l'identifiant. Le jeton d'appareil renvoyé par la commande n'est affiché qu'une fois.

Lancer l'agent

Sur la machine à gérer, lancez l'Agent avec le serveur, l'identifiant d'appareil et le jeton obtenu :

remote-agent --server wss://127.0.0.1:8080 --device-id lab-router --token '<设备令牌>'

Ces trois paramètres peuvent aussi être fournis par REMOTE_SERVER, REMOTE_DEVICE_ID et REMOTE_TOKEN.

--server doit commencer par ws:// ou wss://. Si seul l'hôte est fourni (par exemple wss://mgmt.example.com), l'agent ajoute /ws/device ; si un chemin existe déjà, il le conserve. Pour un Exchange local sans TLS, utilisez ws://127.0.0.1:8080.

Pour éviter le jeton dans les arguments du processus, créez un JSON avec server, device_id et token :

{
  "server": "wss://mgmt.example.com",
  "device_id": "lab-router",
  "token": "<设备令牌>"
}

Lancez ensuite remote-agent --config /path/to/config.json. L'installation et le démarrage automatique sur ordinateur sont décrits dans le déploiement multiplateforme.

Les WebSocket de remote-cli et de remote-agent recherchent le proxy dans l'ordre HTTPS_PROXY / https_proxy → ALL_PROXY / all_proxy → HTTP_PROXY / http_proxy, en respectant NO_PROXY / no_proxy. Les modes sans interface et --ui de l'agent partagent le même chemin de connexion. Le proxy doit prendre en charge HTTP CONNECT (SOCKS n'est pas pris en charge) ; l'ALPN WSS annonce uniquement http/1.1. Pour les services en arrière-plan, définissez les variables dans l'environnement du service ; voir Proxy sortant et maintien de connexion.

Après la connexion de l'appareil :

remote-cli device list

La liste indique son état en ligne.

Exécuter une commande distante

Le contenu après -- est transmis à l'appareil et n'est plus analysé par le CLI local :

remote-cli exec lab-router -- uname -a

Le nombre d'arguments après -- détermine leur interprétation distante :

• Plusieurs arguments sont transmis tels quels comme argv, en conservant chaque limite d'argument, comme s'ils étaient saisis directement sur l'appareil. La CLI ajoute les guillemets nécessaires ; pour un appareil Windows, elle suit les règles de PowerShell.
• Un seul argument est transmis intégralement au shell de l'appareil pour analyse comme ligne de commande ; tubes, ;, jokers et variables sont alors utilisables.

remote-cli exec lab-router -- sh -c 'uname -a; cat /proc/uptime'   # 多个参数，第三个参数完整交给 sh -c
remote-cli exec lab-router -- 'dmesg | tail -20'                    # 一个参数，管道在设备上执行

Attention : avec plusieurs arguments, * et $VAR transmis tels quels par le shell local (fréquent dans PowerShell) sont traités littéralement et ne sont pas développés à distance. Pour laisser l'appareil les développer, utilisez un seul argument, par exemple -- 'ls /etc/*.conf'.

L’exécution exec active hold par défaut : le délai est de 3600 secondes par défaut (maximum absolu de 86400 secondes) ; la déconnexion de l'opérateur détache seulement la sortie, sans tuer le travail. Définissez le délai avec --timeout, par exemple remote-cli exec lab-router --timeout 120 -- uname -a ; --hold-timeout peut remplacer le délai hold. --no-hold rétablit l'annulation à la déconnexion de l'opérateur, avec un délai par défaut de 60 secondes. À la fin normale d'une commande, son code de sortie devient celui de remote-cli.

Consulter et arrêter les travaux, libérer des emplacements de session

remote-cli exec-holds lab-router
remote-cli exec-hold-kill lab-router <job_id>
remote-cli exec-hold-tail lab-router <job_id>
remote-cli exec-hold-cat lab-router <job_id>
remote-cli exec-attach lab-router <job_id>
remote-cli sessions lab-router
remote-cli session-kill lab-router <session_id>

exec-holds liste les travaux exec ainsi que téléchargements, téléversements et requêtes de répertoire en cours, avec job_id, kind, status, age_secs, le session_id actuel côté appareil s'il existe et un résumé tronqué de la commande ou du chemin. exec-hold-kill termine le groupe de processus ou interrompt le transfert grâce à l’identifiant de travail ; les opérations tail, cat et attach sont réservées aux tâches exec.

sessions lit directement la table de routage Exchange et affiche count/limit ainsi que les identifiants de session côté appareil. session-kill utilise cet identifiant côté appareil, envoie une annulation et libère immédiatement l'emplacement Exchange, même sans réponse de l'appareil. Aucune des deux commandes ne crée de session supplémentaire ni ne consomme d'emplacement concurrent ; elles conviennent aux sessions bloquées lorsque la limite est atteinte. Les comptes en lecture seule ne peuvent pas les utiliser.

Une expiration exec termine tout le groupe de processus ; la vidange de sortie et l'envoi du message final sont aussi bornés dans le temps. À la limite de concurrence, Exchange récupère d'abord les routes ayant perdu leur opérateur ou dépassé leur échéance, puis tente la nouvelle session : pour exec, délai réel plus 15 secondes de grâce ; pour les transferts, 3600 secondes plus 15 secondes (l'appareil applique aussi 30 secondes d'inactivité) ; pour les autres sessions, 24 heures. Avant son échéance, un exec hold n'est pas tué pour la seule déconnexion de l'opérateur : celle-ci reste un détachement. Un session-kill explicite ou le dépassement d'échéance annule le processus hold.

Ouvrir un shell

remote-cli shell lab-router

Il s'agit d'une session PTY sur l'appareil, pas de SSH. Quitter le shell termine cette session.

Autres accès

• Console navigateur : Console Web
• Console mobile : Client mobile
• APK Agent Android : APK Android autonome
• QR codes, codes à six chiffres et comptes : Initialisation et appairage
• Mise à jour du CLI et de l'agent : Mise à jour automatique

Chiffrement de bout en bout (sessions scellées)

remote-cli exec <设备> -- <命令> et remote-cli shell <设备> utilisent des sessions scellées de bout en bout, sans paramètre supplémentaire. Exchange ne transmet que du contenu chiffré et ne voit ni commandes, ni sorties, ni contenu du terminal. L’appareil ne fait confiance qu’à la racine de l’espace de travail (clé du superadministrateur, générée automatiquement à sa connexion) et aux autorisations signées par cette racine ; le client racine délivre automatiquement les autorisations aux membres selon leur rôle de compte. La configuration initiale unique est décrite dans les sessions scellées de bout en bout.

Toutes les sessions d’appareil de la CLI utilisent exclusivement le scellement de bout en bout, sans paramètre supplémentaire. L’absence d’informations sur les capacités de l’appareil ou l’échec de la négociation scellée ne provoque aucun passage en clair. La connexion directe LAN et les opérations du navigateur imposent les mêmes exigences de scellement.

Tâches persistantes en arrière-plan

Les Agents annonçant tasks exécutent des opérations ou des DAG déclaratifs sur l’appareil. Le travail continue après la déconnexion. La reconnexion permet de consulter la progression, la sortie et les artefacts. Un redémarrage marque le travail inachevé interrupted, sans répétition automatique.

La création exige des droits scellés manage/owner. Les formulaires proposent dépendances, conditions fixes, références JSON Pointer aux ancêtres, politique d’échec et jusqu’à cinq réessais explicites. Les réessais peuvent répéter les effets ; l’annulation ne les inverse pas. Web et mobile proposent formulaires et import/export JSON. Les interfaces locales de bureau, Android, navigateur et LuCI offrent historique, sortie, annulation et suppression.

Consultez d’abord le catalogue des opérations de l’appareil. Préparez les fichiers avant la création. Valeurs par défaut : 30 jours, 1000 tâches, 64 MiB au total, 8 MiB de texte par tâche, quatre étapes parallèles (deux sur OpenWrt), délai de 30 minutes par étape extensible à 24 heures. Les anciens Agents n’affichent pas cette entrée.

remote-cli task DEVICE operations
remote-cli task DEVICE create pipeline.json --wait
remote-cli task DEVICE list
remote-cli task DEVICE get TASK_ID
remote-cli task DEVICE logs TASK_ID --offset 0
remote-cli task DEVICE cancel TASK_ID
remote-cli task DEVICE upload ./input.bin
remote-cli task DEVICE download TASK_ID STEP.artifact ./result.json
remote-cli task DEVICE delete TASK_ID

Services supervisés

Le mode Service de Task supervise des commandes natives au premier plan avec état souhaité persistant, règles de redémarrage, délai exponentiel, limite de démarrages et reprise après redémarrage de l’Agent. Une définition est arrêtée par défaut. Arrêtez et attendez avant toute modification ou suppression. Une autorisation expirée ou révoquée arrête le service. Les DAG ordinaires ne sont pas rejoués. Gestion sur Web, mobile, bureau et Android ; configuration LuCI via Console ou CLI. Les Agents de navigateur ne supervisent pas les processus système.

Utilisez command.command ou command.argv avec cwd/env, restart (never/on_failure/always), start_secs, stop_grace_secs, backoff_secs, max_backoff_secs, restart_window_secs et max_starts. Un arrêt propre sous Windows nécessite stop_command ; Unix utilise SIGTERM puis termine l’arbre de processus à la fin du délai. Configurez séparément le lancement de l’Agent au démarrage. service get fournit run_id pour task get/logs.

remote-cli task DEVICE service put worker.json
remote-cli task DEVICE service list
remote-cli task DEVICE service start worker
remote-cli task DEVICE service get worker
remote-cli task DEVICE service restart worker
remote-cli task DEVICE service stop worker
remote-cli task DEVICE service delete worker
remote-agent task service put worker.json