Freebox Server (Ultra V9/ Pop V8/ Delta V7 / Revolution V6 / Mini 4K)

  • Status Closed
  • Percent Complete
    100%
  • Task Type Évolution
  • Category Freebox OS → API
  • Assigned To
    aastier
  • Operating System Freebox Server V7 (Delta)
  • Severity Low
  • Priority Very Low
  • Reported Version 4.1.8
  • Due in Version Undecided
  • Due Date Undecided
  • Votes 3
  • Private
Attached to Project: Freebox Server (Ultra V9/ Pop V8/ Delta V7 / Revolution V6 / Mini 4K)
Opened by strato - 30/05/2020
Last edited by aastier - 05/08/2021

FS#30666 - API VMs Freebox Delta

Hello,

Est-ce qu’il serait possible d’avoir un accès à une api pour la gestion des VMs ? Idéalement, ça permettrait de provisionner les VMs via un provider terraform ou autres, ça pourrait permettre de faire des chouettes automatisations !

Merci d’avance !

Closed by  aastier
05.08.2021 17:35
Reason for closing:  Résolu
Additional comments about closing:  

Documentation disponible dans le menu Développer de Freebox OS.

14/05/2022: A request to reopen the task has been made. Reason for request: Bonjour L output de l API des VM ne renvoi pas un json valide. Certains message d erreur sont tronqués, d autres sont mal documentés. Je n ai pas réussi a faire en sorte que l API reponde en anglais 100% du temps, certains message renvoyés sont en français avec des accents... c est moche ! Je suis en train d écrire un script en bash exploitant l api et permettant de gerer les vms depuis l api (start/stop/restart/detail/add/delete/modify... + accès à la console série au travers des websocket API). J ai presque terminé, tout le code sera disponible sur mon dépôt github, une partie l est déjà. Merci beaucoup à Fany (corwin.31), l API a été documentées depuis mais il manque des exemples, notamment sur les websocket et sur le PUT pour modifier les VM. Merci Cordialement nbanba

Pas besoin d'API, tu peux utiliser jenkins/ansible ou salt par exemple pour l'automatisation de tâche

Je voudrais pouvoir provisionner / détruire / démarrer / arrêter les vms via l'API. Effectivement, pour tout ce qui se passe à l'intérieur de la VM, puppet / ansible / chef ou autre font très bien l'affaire.

il y a déjà un

GET /api/v7/vm

qui va renvoyer les infos des vms en cours.
J'aurais voulu savoir s'il y avait un

PUT/POST /api/v7/vm/create

par exemple, pour créer une vm, ou un

GET /api/v7/vm/:id/start

pour démarrer...

Bonjour,

J'ai la même question/le même besoin. L'appli Compagnon (iOS) ne gère pas les VM, mais on pourrait s'en sortir si au moins on avait la doc de l'API V7 sur la partie VM. Les GET /api/v7/vm et GET /api/v7/vm/<id> fonctionnent bien, mais je ne trouve rien sur les PUT et POST qui vont bien... sur net comme en tâtonnant en essayant de trouver la bonne logique, en cohérence avec le reste.

Merci par avance

Bonne journée,
Corwin.31

Bonjour,

J’ai un peu décortiqué l’API V7 des VM et je peux donc en donner des infos. Est-ce que ça intéresse encore quelqu’un ? J’ai l’essentiel mais je n’ai pas tout testé (par exemple les images ISO) et je ne remplacerai pas Free pour une vraie documentation. Faites-moi signe et je posterais ici mes infos.

Bonne journée,
Corwin.31

Bonjour,
Oui, je suis toujours intéressé ;)
Merci!

Ok, le temps de rédiger les choses et je poste ça. Ce sera sûrement en plusieurs fois. Un peu de patience...

Préambule
Avant de commencer, il faut mentionner que Free m'a pas documenté l'API V7, version qui ne contient que le contrôle des VM. Les API documentées par Free sont soit stables, soit instables, donc lorsque ce n'est pas documenté, il n'y a encore moins de garantie de stabilité. Ma contribution n'a par ailleurs pas vocation à être une documentation de l'API V7, tâche que le laisse à Free.

Pour démarrer un petit rappel toutes les requêtes doivent être faites sur l'URL complète liée à chaque freebox, je ne donnerai que la fin, même pas la version, qui peut être v7 ou v8, mais pas en-dessous. Dans mes requêtes <...> sera le marqueur de début de l'URL.

Voyons tout d'abord le JSON complet des VM, clé par clé :
* 'mac': (lecture seule) texte qui correspond à la MAC adresse de la VM

* 'cloudinit_userdata': texte qui contient les paramètres minimaux de la VM qui sont positionnés au 1er lancement. Les classiques : l'obligatoire login, son optionnel mot de passe, l'optionnelle clé public SSH pour se connecter à distance, l'autorisation d'accès SSH par mot de passe, l'inclusion du package CiFS ou les commandes de configuration et montage du file system de la freebox. Il convient d'a voir ici un texte (avec sauts de lignes) qui respecte le format attendu.

* 'cd_path': je n'ai pas creusé se paramètre... je le laisse vide

* 'id': (lecture seule) l'identifiant numérique de la VM

* 'os': texte qui indique quelle distribution est installée ; cela change l'icône affichée, et je doute que ça serve à plus que ça... Les valeurs possibles sont : <vide> (accepté), debian, ubuntu, fedora, other1 (utilisé pour Jeedom), other2 (je suppose parce qu'il y a un other3, mais je n'ai pas testé) et other3 (utilisé pour OpenSUSE)

* 'enable_cloudinit': booléen pour l'usage de cloudinit

* 'disk_path': texte qui est l'encodage en base 64 du chemin d'accès au fichier du disque virtuel de la VM
* 'vcpus': entier qui est le nombre vCPU allouées à la VM, seules les valeurs 1 et 2 sont acceptées (rappel : max 3 vcpus pour toutes les VM)

* 'memory': taille en Mo de la RAM allouée à la VM, attention car une petite partie ne sera pas accessible dans la VM (rappel : il faut laisser 1 Go de RAM pour la box elle-même, quel que soit le nombre de VM lancées)

*'name': texte qui donne le nom de la VM

* 'cloudinit_hostname': idem mais pour cloudinit

* 'status': (lecture seule) texte qui décrit l'état de la VM

* 'bind_usb_ports': liste qui contient les noms des ports USB que l'on autorise sur la VM. Je pense que les noms des ports USB varient selon la version de la box. Sur une Delta (ou Delta S), j'ai "usb-external-type-a" & "usb-external-type-c". Juste un petit rappel : lorsqu'une VM est lancée est qu'elle a accès à un port USB, celui n'est plus accessible de la box elle-même.

* 'enable_screen': booléen qui autorise ou non la console "graphique" de la Webapp Freebox OS

* 'disk_type': texte qui donne le type de disque virtuel qui est utilisé pour la VM ; les 2 valeurs possibles sont "qcow2" et "raw". Je n'ai pas testé le mode raw.

Dans la suite, que ce soit pour la création d'une VM ou dans sa modification, il faut un JSON complet ou quasi complet, les clés en lecture seule sont bien sûr facultatives mais elle sont acceptées (et ignorées sûrement). Il n'est pas exemple pas possible de changer la mémoire avec un JSON minimal comme { 'memory': 512 }. Le mieux est de récupérer le JSON de config d'une VM, d'y apporter les modification puis de le soumettre.

Commençons par récupérer les config des VM. Pour avoir toutes les VM d'un coup, sous la forme d'une liste (tableau) de JSON, la requête est simple :
GET <...>/vm/

Pour récupérer les config d'une VM donnée, cela se fait à partir de son ID :
GET <...>/vm/<id de la vm>/

Pour les arrêts/démarrages, il faut faire un POST mais sans data/payload. Pour démarrer :
POST <...>/vm/<id de la vm>/start

Pour un arrêt normal (shutdown) :
POST <...>/vm/<id de la vm>/powerbutton

Pour un arrêt brutal ou forcé (haltsys), celui qu'il faut éviter :
POST <...>/vm/<id de la vm>/stop

Pour la création d'une VM, commençons par le plus simple : la créer à partir d'un fichier disque virtuel existant. Ici nous avons donc un fichier qcow2 (pas testé en raw), qui vient d'une image de distribution ou d'une autre VM, peu importe, et que l'on suppose correction dimensionné. Je précise que cette création peut aussi être une recréation si l'on veut restaurer une VM que l'on aurait perdue par erreur, pour peu que l'on ait sauvegarder son fichier disque virtuel (à froid, c'est-à-dire VM arrêtée, c'est mieux). A noter que récréer une VM ne restaure pas forcément l'adresse MAC, donc si vous aviez un bail IP statique avec son ancienne adresse MAC, il faudra le recréer. Bref pour créer une VM, on remplie le JSON (rappel : le fichier du disque virtuel doit être encodé en base 64) et on le soumet sans oublier le '/' à la fin :
POST <...>/vm/

Pour la modification d'une VM, on se rappelle qu'il faut un JSON complet que l'on soumet :
PUT <...>/vm/<id de la vm>

Pour supprimer une VM, c'est une requête simple :
DELETE <...>/vm<id de la vm>

Attention, en aucun cas cette requête ne supprime les fichiers de la VM (.qcow2 et .efivars). Il faut le faire à la main ou via l'API "File System" de gestion de fichiers qui va bien.

Passons à la création d'une VM à partir d'une distribution "Free". Voilà comment procède la Webapp Freebox OS. En 1er lieu elle récupère la liste des distributions officielles et cela se fait par un appel API :
GET /vm/distros

Cette renvoie une liste de distributions où chacune est décrite dans un JSON sous cette forme :
* 'hash': texte qui donne l'URL pour contrôler le hash du fichier de la distrib, il n'existe pas toujours

* 'url': texte qui donne l'URL pour télécharger la distrib

* 'name': texte qui donne le nom complet de la distrib

* 'os': texte donne donne le paramètre os pour le JSON de la VM

Une fois le choix fait, la Webapp lance un téléchargement http(s) avec les données obtenues. Pour ce faire, il utilise l'API "Downloads" :
POST <...>/downloads/add

Il soumet au POST les paramètres du téléchargement (Content-Type: application/x-www-form-urlencoded; charset=UTF-8), par exemple :
download_url=http%3A%2F%2Fftp.free.fr%2F.private%2Fdebian-cloud%2Fcurrent-10%2Fdebian-10-openstack-arm64.qcow2&download_dir=RnJlZWJveC9WTXM%3D&filename=test.qcow2&hash=https%3A%2F%2Fcdimage.debian.org%2Fcdimage%2Fopenstack%2Fcurrent-10%2FSHA256SUMS

Le fichier est téléchargé directement dans /Freebiox/VMs avec sous le nom de la VM (text.qcow2 dans l'exemple). Une fois le téléchargelement achevé, la tâche de download est supprimée en conservant bien sûr le fichier téléchargé (DELETE <...>/downloads/<task id>). Le fichier obtenu est une simple image standard de la distribution, il faut donc en faire un disque virtuel avec la taille max que l'on veut. L'appel API pour cette tâche est le suivant :
POST <...>/vm/disk/resize

Il faut soumettre au POST un JSON avec ce format :
* 'disk_path': texte qui donne le fichier (full path) encodé en base 64

* 'size': entier qui est la taille max en octets du disque virtuel

* 'shrink_allow': booléen qui autorise ou non les réductions de taille du fichier

Cette requête soumet en fait une tâche qui va effectuer l'opération. Vous pouvez consulter son état avec l'ID qui est donné dans le JSON de résultat de la requête précédente :
GET <...>/vm/disk/task/<task id>

Le JSON obtenu vous indiquera si la tâche est terminée (normalement c'est le cas car c'est quasi immédiat) et s'il y a eu une erreur ou non. Si la tâche est bien terminée, il faut la supprimer :
DELETE <...>/vm/disk/task/<task id>

La suite revient au 1er cas de création de VM : constitution du JSON et soumission avec la même requête POST.

That's all folks

Excellent, merci beaucoup, chouette boulot !

De rien, je partage ce que j'ai analysé
En bonus, la requête de redémarrage que j'ai eue depuis : POST <...>/vm/<id de la vm>/restart/

Admin

Merci pour l’effort. Une des raisons pour lesquelles la documentation n’a pas été publiée, c’est qu’elle aurait pu changer à nouveau. Note: la partie sur le téléchargement est déjà documentée. Vous aurez aussi la dernière version de la documentation directement dans l’aide intégrée à Freebox OS.

Merci Anisse. J'en suis conscient, d'où mon message de préambule, mas quand même le statut instable est quand fait pour ça ;-) Mon partage vise à aider ceux qui veulent commencer à utiliser l'API des VM plus tôt, quitte à réadapter ensuite. Et pour l'instant rien sur les VMs dans la doc intégrée sur la freebox (je suis sur la 4.2.6). NB : une autre chose qui manque dans la doc c'est celle du client OpenVPN : en fait il manque la doc de la clé config_openvpn pour le JSON du client VPN, ce que j'ai aussi analysé ;-)

Mais c'est bien quand même que l'API soit utilisable avec autant de fonctions.

Sebom commented on 10.12.2020 10:21

Bonjour,

J'utilise une Vm Jeedom est comme la gateway I/O n'est pas stable cela m’intéresse de pouvoir démarrer la VM en commande mais à partir de quel outils peut on faire ça POST <...>/vm/<id de la vm>/start

Sebom commented on 10.12.2020 12:28

Bonjour,

J'utilise une Vm Jeedom est comme la gateway I/O n'est pas stable cela m’intéresse de pouvoir démarrer la VM en commande mais à partir de quel outils peut on faire ça POST <...>/vm/<id de la vm>/start

Bonjour Sebom,

Pour cela il te faut développer. Python, Swift, Java, ce n'est pas langages qui manquent. Et pour ça tu devrais trouver ton bonheur sur GitHub. Tu ne peux pas le faire aussi simplement : il faut s'identifier sur la box, physiquement. Tu nommes ton application, tu la valides en façade de la box au moins à la 1ère connexion pour récupérer le token de connexion, sans oublier de lui attribuer les droits qui vont bien dans l'interface. Ensuite, à chaque connexion il faut s'identifier avec le token. Tout ce fait en http/https via commandes GET/POST/PUT/DELETE. La doc lapsus à jour est sur ta box : http://mafreebox.freebox.fr/doc/index.html#, mais sinon il y a aussi http://dev.freebox.fr/sdk/os/

Sur GitHub, il y a des librairies qui peuvent t'aider. Je re penses pas qu'elles soient à jour, notamment sur cette partie VM, si bien qu'il faut rajouter cette partie. Mais la mécanique du token de connexion y est, ce qui est bien car le reste est plus simple.

Bon dev !

Bonjour,

Pour ceux que ça intéresse, je viens de créer un Git avec un package Python pour exploiter l'API Freebox, plus complet et à jour que ceux qui existaient jusqu'ici.
Le repo est ici : https://github.com/corwin-31/fbxapitool ; pour l'instant pas encore de pip install, mais ça viendra peut-être.
Sur ce Git, je publierai prochainement un outil ligne de commande pour la Freebox, si vous avez des besoins de scripting... J'y ajouterai aussi un outil de sauvegarde de la config de la box, outil qui s'appuiera sur l'outil ligne de commande pour restaurer. Donc si ça vous intéresse, surveiller ce Git...

Merci Fany pour ces informations, c'est exactement ce que je cherchais :)

j'avais besoin de planifier le démarrage et l'arrêt d'un serveur plex sur la freebox et j'attendais depuis un moment que Free mettent à jour leurs doc...

Ca m'intéresse comment tu as trouvé les appels api, t'as surveillé les traces réseau pour chaque action ?

Il y a un moment, avant que ce soit documenté, j'ai dû passer par une pki recompilé pour voir le flux https et les appels api pour l'alarme domotique, s'était une bonne prise de tête.

Bonjour Next,

J'ai simplement utilisé le debugging dans le navigateur, c'est plus simple et rapide que de tracer le flux et de le déchiffrer ;-)

Actuellement le SDK n'est pas à jour...

Il faudrait aussi faire une mise à jour de :
- https://dev.freebox.fr/sdk/
- https://dev.freebox.fr/sdk/os/

Loading...

Available keyboard shortcuts

Tasklist

Task Details

Task Editing