Surveiller et redémarrer une Freebox à distance

31 août 2019 Lionel Domotique, IP & Co, IT

Il existe un bugg (https://dev.freebox.fr/bugs/task/22818) bien gênant sur la Freebox (Révolution et 4K) en mode bridge, toujours pas résolu par Free au fil du temps. Pour faire court, en cas de déconnexion FTTH/xDSL, le routeur qui lui est adossé ne voit plus la box qui joue ici un rôle de modem. Redémarrer le routeur ne sert à rien, c’est la Freebox qu’il faut redémarrer.

Redémarrer une Freebox peut se faire en coupant sauvagement l’alimentation, depuis la face avant avec le petit afficheur (quant il n’est pas HS) ou via Freebox OS (auquel dans ce vas on n’aura pas accès localement). Il existe une autre option avec l’API Freebox OS qui prend tout son sens si l’on supervise la Freebox à distance, dans notre cas avec PRTG Network Monitor installé dans un VPS et qui est gratuit jusqu’à 100 sensors (il existe bien d’autres solutions). PRTG envoie des notifications, mais permet également de lancer des scripts PowerShell, et c’est l’objet de cet article.

Script PowerShell permettant de rebooter une Freebox

Petit didacticiel aussi simple que couper une tomate mûre en tranches avec une sandale...

L'application PS dont ce didacticiel traite s'appelle "Remote Control". Elle permet de rebooter une Freebox depuis un script PowerShell et/ou de récupérer un flux JSON avec les informations temps réel de la Freebox, par exemple pour disposer d'un monitoring depuis une page HTML (il peut être modifié afin d'obtenir d'autres informations disponibles via l'API).

  1. Fichiers accompagnant ce didacticiel

L'archive ZIP dans laquelle se trouve ce didacticiel contient les fichiers suivants :

  • Adresse_Freebox_Locale.ps1 est un script PowerShell qui retourne l'URI de la Freebox installée sur le réseau local. Cet URI est utilisable depuis un navigateur internet situé dans ou hors du réseau local, si elle est autorisée.
  • Autoriser_Remote_Control.ps1 est un script PowerShell à lancer sur un PC du réseau local, attribuant une autorisation à l'application "Remote Control" afin qu'elle puisse contrôler la Freebox locale.
  • Freebox ECC Root CA.cer est l'un des deux certificats requis pour accéder à la Freebox en HTTPS.
  • Freebox Root CA.cer est l'autre certificat.
  • Remote_Control.ps1 est le script PowerShell qui servira à faire rebooter la Freebox ou à récupérer ses informations.
  1. Principe de fonctionnement

La Freebox peut être contrôlée de manière locale ou distante via une API pouvant être appelée en respectant l'architecture REST. Afin d'éviter que des commandes permettent la prise de contrôle d'une box par un tiers malintentionné, un ensemble de sécurités est mis en œuvre :

  1. Attribution d'un droit à prendre le contrôle, requérant une action physique sur la box,
  2. Attribution d'autorisations quant aux actions possibles lors de la prise de contrôle,
  3. Fourniture d'un jeton lors de cette attribution, lequel ne sera jamais transmis lors des appels à l'API, mais remplacé par une donnée cryptée.

L'API de la box peut être appelée en HTTP ou en HTTPS. Cependant la documentation indique que la possibilité d'utiliser HTTP sera retirée dans une version prochaine, et qu'il est fortement conseillé de n'utiliser que HTTPS. Afin de respecter cette consigne, "Remote Control" fonctionne par défaut en HTTPS, même s'il est possible de le faire fonctionner en HTTP moyennant une ou deux modifications du script et pas mal de simplifications dans le processus indiqué ci-dessous.

Afin de pouvoir utiliser "Remote Control" pour dialoguer avec une Freebox locale ou distante, il faut donc réaliser les opérations suivantes :

  1. Installer les certificats nécessaires pour pouvoir causer HTTPS.
  2. Autoriser l'application "Remote Control" sur la Freebox
  3. Installer "Remote Control" sur une machine du réseau local ou sur une machine distante (non testé), et le paramétrer correctement pour qu'il puisse interagir avec la Freebox.

L'installation et l'utilisation de "Remote Control" nécessite l'utilisation d'un PC situé sur le réseau local derrière la Freebox, un opérateur capable d'appuyer sur un bouton de la Freebox, et un PC de contrôle situé sur le réseau local derrière la Freebox ou distant via l'internet.

  1. Installation des certificats

Lorsqu'une connexion HTTPS est réalisée avec la Freebox, cette dernière nécessite un certificat attribué à Freebox ECC Root CA ou Freebox Root CA. Les fichiers correspondants sont fournis dans le zip. Il faut les installer sur le PC qui va permettre d'autoriser l'application "Remote Control" sur le réseau local derrière la Freebox ET sur le PC qui va prendre le contrôle de la Freebox.

Pour les installer, double-cliquer sur les fichiers dans l'explorateur Windows, demander à installer les certificats dans le dépôt des certificats racine. Afin de tester la bonne mise en place des certificats, ouvrez un navigateur internet et entrez dans la zone d'adresse https://mafreebox.freebox.fr, si vous accédez à l'interface de Freebox OS, c'est OK. Conservez le navigateur ouvert, on en aura besoin au point numéro 6 de ce didacticiel.

Si vous avez une page d'erreur ou une indication SEC_ERROR_UNKNOWN_ISSUER, c'est raté. Lancez MMC et le plug-in Certificats, cherchez dans le bazar les deux certificats Freebox, supprimez-les et recommencez tout depuis le début en maudissant l'auteur de ce didacticiel pour son manque de précision.

  1. Autoriser l'application "Remote Control"

Cette opération doit être réalisée depuis un PC situé dans le réseau local derrière la Freebox, selon la documentation du SDK. Il n'est pas possible d'autoriser une application depuis un PC extérieur. Dixit la doc. Il faut aussi avoir sous la main une personne physique capable d'appuyer sur un bouton sur la Freebox.

Double cliquez sur le script PowerShell Autoriser_Remote_Control.ps1 puis suivez les indications à l'écran, vous demandant d'appuyer sur le bouton "Flèche vers la droite" sur la façade de la Freebox alors que cette dernière demande si elle doit autoriser l'application "Remote Control". Appelez la personne physique devant la Freebox et expliquez-lui ce qu'elle doit faire. Une fois le bouton de la Freebox appuyé, le script devrait afficher que l'autorisation a été donnée, accompagné de l'URI de la Freebox et d'un identifiant d'application (de la bouillie en Base64). Copiez-coller l'URI de la Freebox et l'identifiant d'application dans un coin.

Nous n'aurons désormais plus besoin du fichier Autoriser_Remote_Control.ps1. L'autorisation a été donnée à l'application et sauvée dans la Freebox ad vitam aeternam, sauf :

  • Si vous supprimez l'autorisation depuis les paramètres de la Freebox (voir point 6)
  • Si vous faites une réinitialisation usine de la Freebox,
  • En cas d'échange de la Freebox, par exemple si elle venait à tomber en panne,
  • En cas d'erreur non répertoriée dans les documentations,
  • Ou si vous passez chez Bouygues et renvoyez la box chez Free.
  1. Attribuer les droits nécessaires à l'application "Remote Control"

Toujours depuis le PC situé dans le réseau local, reprenez le navigateur internet que vous aviez utilisé pour le point numéro 3, qui doit toujours afficher la page d'accueil de Freebox OS de la Freebox qui vous intéresse. Si vous l'avez bêtement fermé, collez-vous une baffe, puis relancez un navigateur internet et allez sur https://mafreebox.freebox.fr. 

Identifiez-vous, puis sélectionnez successivement :

  • "Paramètres de la Freebox",
  • "Gestion des accès",
  • "Applications" (en haut de la fenêtre).

Recherchez dans la longue liste des applications autorisées celle que vous venez d'ajouter : "Remote Control (demande)". Cliquer sur le bouton "Editer" à droite et modifiez les autorisations pour activer "Modification des réglages de la Freebox". Vous pouvez d'ailleurs désactiver tout le reste qui a été activé par défaut mais qui n'est pas utile. Évitez de cliquer sur la dernière icône, en forme de poubelle, qui retire l'autorisation de l'application et vous forcerait à tout recommencer depuis l'étape 4 ci-dessus.

  1. Paramétrer le script de contrôle à distance

Nous allons maintenant modifier le contenu du fichier Remote_Control.ps1 pour y insérer les paramètres de fonctionnement correspondant à la Freebox qui nous intéresse. Si vous souhaitez contrôler plusieurs Freebox, vous pouvez bien entendu copier le fichier, renommer sa copie comme vous l'entendez et la modifier. Cette opération doit être réalisée sur le PC local ou distant qui devra prendre le contrôle de la Freebox pour la rebooter. Ce PC devant de plus disposer des certificats racine, installés comme décrit au point 3 de ce didacticiel.

Il faut modifier deux lignes dans le script :

  • Ligne 43, remplacer [Insérer l'URI ici] par l'URI retournée par le script d'autorisation de l'application Autoriser_Remote_Control.ps1, URI que vous avez copié dans le bloc-notes, un email ou taggué en fin du point n°4 de ce didacticiel :

Avant :

$AdresseFreebox = "[Insérer l'URI ici]"

Après (par exemple) :

$AdresseFreebox = "https://vivalasvegas.fbxos.fr:12345"

Faites gaffe avec les guillemets, ils doivent être présents après modification de la ligne.

  • Ligne 46, remplacer [Insérer l'identifiant d'application ici] par le jeton de l'application, noté avec l'URI de la Freebox au point 4 :

Avant :

$JetonAppli = "[Insérer l'identifiant d'application ici]"

Après (par exemple) :

$JetonAppli = "M0nqsaiDup0ul3tMfgtyhbut0risaTi0nTyT0uch3pa5"

Faites gaffe avec les guillemets, comme précédemment. Sauvez le script, fermez l'éditeur, c'est prêt.

  1. Tester l'installation

Ouvrez une ligne de commande PowerShell sur le PC qui doit prendre le contrôle, PC local sur le réseau local ou PC distant (non testé) puis entrez la commande suivante sans oublier le ./ :

./Remote_Control.ps1 –Info

Bien entendu, il faut être dans le dossier contenant le fichier, sinon vous aurez une erreur indiquant que la commande est inconnue, mais bon, je suppose que vous ne vous ferez avoir qu'une seule fois. Si tout va bien, la fenêtre de PowerShell va vous afficher une longue liste d'informations sous la forme d'un flux JSON avec en vrac la température du CPU, la vitesse du ventilo, la durée de fonctionnement depuis le dernier reboot, l'âge du capitaine, toussa-toussa.

Dans la fenêtre PowerShell, entrez maintenant :

./Remote_Control.ps1 –Reboot

Ça devrait vous répondre que la Freebox est en train de rebooter, et là, paf, plus d'internet si vous êtes en local. Tout qui s'allume en rouge dans les superviseurs de tous poils, les utilisateurs du réseau local qui gueulent, le drame quoi.

Patientez quelques minutes puis rafraîchissez la fenêtre de votre navigateur internet qui était toujours en train d'afficher les infos de la box. Vous devrez sûrement retaper le mot de passe. Rendez-vous dans "État de la Freebox" et normalement, si tout va bien, derrière "allumée depuis", il devrait y avoir une valeur en secondes ou en minutes, preuve que votre Freebox a bien redémarré, que le script PowerShell a bien fait son boulot et que l'auteur de ces lignes n'est pas si con que ça.

  1. Conclusion

Il ne vous reste plus qu'à entourer tout ça d'un ruban rose, de mettre en place tout ce qu'il faut pour que ça bosse automatiquement sans vous faire ch... à chaque fois que la Freebox décroche, puis il vous faudra penser à reprendre ce didacticiel pour renuméroter les titres car le crétin qui a écrit ce document a sauté le point 5.

Lequel crétin remercie Emin, auteur de l'article Piloter sa freebox, disponible ici : ainsi que Mika-NT28 auteur du plugin Freebox OS pour Jeedom qui permet de superviser la box depuis Jeedom, lequel a également été une source d'inspiration. Et moi je remercie mon collègue FredV qui a passé une nuit sur ce petit projet !

Download

https://github.com/mycanaletto/Reboot-Freebox

Release : Reboot_Freebox_01.zip

Bonus

Comme indiqué dans le bug la collection de buggs de la Freebox, la nouvelle version du Compagnon Freebox, mais également tout ce qui accède localement à l'url sécurisée de la Freebox, ne parvient plus à trouver la Freebox en mode bridge et donc à générer une nouvelle association. Il existe une solution ici.

Sources 

https://lafibre.info/routeur/free-usg-mode-bridge-down-apres-desync/ 
https://dev.freebox.fr/bugs/task/22818 
https://kb.paessler.com/en/topic/18963-how-can-i-use-powershell-scripts-with-prtg-s-execute-program-notification 
https://p0w3rsh3ll.wordpress.com/2013/07/04/piloter-sa-freebox/ 
https://github.com/DjMomo/ClassePhpFreebox 
https://wiki.deimos.fr/Rebooter_sa_Freebox_Server_6_en_ligne_de_commande.html 
https://forum.universfreebox.com/viewtopic.php?t=55120 
https://dev.freebox.fr/bugs/task/12939 
https://dev.freebox.fr/sdk/os/