freeboxvm

Un outil en ligne de commande pour gérer et accéder aux machines virtuelles d’une Freebox via l’API Freebox OS v8.

Prérequis

Python 3.8+
Freebox avec API Freebox OS v8
Paquets : requests, websockets, tqdm, humanize, PyGObject (pour le support libosinfo)

Installation :

Sur Fedora, le RPM freeboxvm peut être installé depuis le COPR :

sudo dnf copr enable lvivier/freebox-failover
sudo dnf install freeboxvm

Sinon en utilisant l'environnement PyPI depuis le répertoire source:

pip install .

Pour installer les dépendances sans métadonnées de packaging (développement ou environnements anciens) :

pip install -r requirements.txt

Sur Fedora, vous pourriez avoir besoin de :

sudo dnf install python3-gobject gobject-introspection libosinfo osinfo-db

Sur Debian/Ubuntu, vous pourriez avoir besoin de :

sudo apt install python3-gi gir1.2-libosinfo-1.0

Authentification et fichier token

Lors de la première exécution, l’outil suit le flux d’autorisation Freebox et enregistre l’app_token et le track_id dans ~/.config/freeboxvm/freeboxvm_token.json. Utilisez --token-file pour cibler un autre emplacement (utile pour plusieurs Freebox ou comptes) ; le raccourci ~ est accepté.

Utilisation

Lister les VMs

freeboxvm list [--long] [--usb-ports] [--disks] [--cloud-init]

Sortie par défaut : ID STATUT NOM.

‑‑long	‑l	Afficher plus d’informations
‑‑usb‑ports	‑u	Lister les ports USB associés
‑‑disks	‑d	Lister les images disque
‑‑cloud‑init	‑c	Afficher les informations cloud-init

Exemples :

Vue courte

$ freeboxvm list
ID  STATUT   NOM
0   running  Debian-11
1   stopped  Ubuntu-22.04

Vue longue avec ports USB

$ freeboxvm list --long --usb-ports
ID  STATUT   NOM                      OS       MAC               vCPU MÉMOIRE AFFICHAGE
0   running  Debian-11                debian   aa:bb:cc:dd:ee:ff 2    2048    True
    Ports USB : usb-external-type-a

Détails disques et cloud-init

$ freeboxvm list --disks --cloud-init
0   running  Debian-11
    Image disque : Disque 1/VMs/debian.qcow2 (qcow2)
    Image CD : Disque 1/VMs/debian-11.iso
    Cloud-init hostname : debian
    Cloud-init user-data :
#cloud-config
system_info:
default_user:
- name: debian

Afficher une VM

freeboxvm show <id|name> [--long] [--usb-ports] [--disks] [--cloud-init]

Affiche les informations d’une VM unique. Supporte les mêmes options que list.

‑‑long	‑l	Afficher plus d’informations
‑‑usb‑ports	‑u	Lister les ports USB associés
‑‑disks	‑d	Lister les images disque
‑‑cloud‑init	‑c	Afficher les informations cloud-init

Exemples :

$ freeboxvm show 1
ID    STATUT    NOM
1    stopped    Ubuntu-22.04

$ freeboxvm show Debian-11 --long
ID  STATUT   NOM                      OS       MAC               vCPU MÉMOIRE AFFICHAGE
0   running  Debian-11                debian   aa:bb:cc:dd:ee:ff 2    2048    True

$ freeboxvm show 1 --disks --cloud-init
ID    STATUT    NOM
1    stopped    Ubuntu-22.04
    Image disque : Disque 1/VMs/ubuntu2204.qcow2 (qcow2)
    Aucune image de périphérique CDROM
    Cloud-init hostname : Ubuntu
    Cloud-init user-data :
#cloud-config
system_info:
  default_user:
    name: laurent
  groups:
    - laurent

Se connecter à la console d’une VM

freeboxvm console <id|name>

Combinaisons de touches de contrôle de la console:

Ctrl-B D	Pour Quitter
Ctrl-B B	Pour envoyer un Ctrl-B
Ctrl-B R	Pour Réinitialiser la VM
Ctrl-B H	Pour arrêter (Halt) la VM
Ctrl-B S	Pour Stopper immédiatement la VM
Ctrl-B ?	Pour afficher l'aide concernant les combinaisons de touches

Exemples :

freeboxvm console 0
freeboxvm console Debian-11

Exposer l’écran d’une VM via proxy VNC

freeboxvm vnc-proxy [-h] [--listen ADDR] [--port N] [--console] vm

Expose l’écran VNC d’une VM sur un port TCP local.

‑‑listen ADDR	‑l ADDR	Adresse d’écoute (par défaut 127.0.0.1)
‑‑port N	‑p N	Port TCP (par défaut 5901)
‑‑console		Lance la console interactive en parallèle

Exemples :

Proxy VNC pour la VM 0 sur localhost:5901

freeboxvm vnc-proxy 0

Proxy pour la VM 12 sur toutes interfaces, port 5902

freeboxvm vnc-proxy --listen 0.0.0.0 --port 5902 12

Proxy et console pour une VM par nom

freeboxvm vnc-proxy --console Debian-11

Gestion des disques

freeboxvm disk [-h] {create,info,resize,delete} ...

Gérer les images disque des VM (création, redimensionnement, inspection, suppression).
Les tailles acceptent des suffixes binaires k, m, g, t (puissances de deux) ; les valeurs en octets bruts sont également acceptées.

Actions :

create

freeboxvm disk create [-h] [--type TYPE] <path> <size>

Créer une image disque (par défaut qcow2).

resize
```
freeboxvm disk resize [-h] [--shrink-allow] <path> <size>
```
Redimensionner une image disque (--shrink-allow autorise réduction).
info
```
freeboxvm disk info <path>
```
Afficher taille virtuelle, utilisée, type.
delete
```
freeboxvm disk delete <path>
```
Supprimer une image disque.

Exemples :

Crée un disque qcow2 de 10 Gio

freeboxvm disk create "/Disque 1/VMs/disk1.qcow2" 10g

Redimensione un disque à 20 Gio

freeboxvm disk resize "/Disque 1/VMs/disk1.qcow2" 20g

Force un redimensionnement destructif (réduction de la taille)

freeboxvm disk resize --shrink-allow "/Disque 1/VMs/disk1.qcow2" 8g

Affiche les informations relatives au disque

freeboxvm disk info "/Disque 1/VMs/disk1.qcow2"

Supprime un disque

freeboxvm disk delete "/Disque 1/VMs/disk1.qcow2"

Installer une nouvelle VM

freeboxvm install [options]

Créer et démarrer une VM depuis une image cloud ou un ISO. Peut aussi attacher console et/ou proxy VNC.

‑‑install ID	‑i ID	identifiant de distribution (voir `os-list`).
‑‑name	‑n NOM	nom de la VM.
‑‑os		nom de l’OS (si non détecté).
‑‑vcpus		nombre de CPUs virtuels.
‑‑memory		mémoire (MiB).
‑‑disk PATH		chemin image disque.
‑‑disk‑size		taille disque.
‑‑cdrom PATH		ISO d’installation.
‑‑location URL		URL CD/ISO (exclusif avec `--cdrom`).
‑‑cloud‑init		activer cloud-init.
‑‑cloud‑init‑hostname		hostname.
‑‑cloud‑init‑userdata FILE		fichier user-data.
‑‑enable‑screen		activer écran (VNC-over-WebSocket).
‑‑console		attacher console après boot.
‑‑vnc‑proxy		démarrer proxy VNC après boot.
‑‑listen ADDR		adresse d’écoute VNC (par défaut 127.0.0.1).
‑‑port N		port TCP VNC (par défaut 5901).
‑‑usb‑ports LISTE		lier des ports USB à la VM (liste séparée par des virgules).

Notes :

Lorsque --install ou --location est utilisé, l’image est téléchargée via le gestionnaire de téléchargements de la Freebox dans le répertoire par défaut /Disque 1/VMs/, avec suivi de progression, vérification de la somme de contrôle et nettoyage en cas d’erreur.
Pour les images cloud, le fichier téléchargé devient l’image disque de la VM.
Si --disk pointe vers un fichier inexistant, --disk-size doit être fourni afin que l’outil puisse créer l’image (le type qcow2/raw est déduit de l’extension).
Les disques peuvent être redimensionnés automatiquement s’ils sont plus petits que la taille indiquée par --disk-size.

Exemple :

Installer depuis un identifiant de distribution (cloud image), activer cloud-init et attacher la console

freeboxvm install -n Fedora-cloud --vcpus 1 --memory 512 --console   --cloud-init --cloud-init-hostname Fabulous   --cloud-init-userdata cloud-init-user-data.yaml   -i fedora41 --disk Fabulous.qcow2 --disk-size 10g

Installer depuis une URL d’ISO CDROM, attacher la console et lancer le proxy VNC

freeboxvm install -n Fedora-test --os fedora   --location https://download.fedoraproject.org/pub/fedora/linux/releases/41/Everything/aarch64/iso/Fedora-Everything-netinst-aarch64-41-1.4.iso   --disk "/Disque 1/VMs/test.qcow2" --disk-size 20g   --vcpus 2 --memory 2048 --console --vnc-proxy --enable-screen

Allumer une VM

freeboxvm poweron <id|name> [--console|-c] [--vnc-proxy|-v]
                   [--listen|-l ADDR] [--port|-p N]

Démarre la VM puis (optionnellement) attache la console et/ou lance le proxy VNC.

‑‑console	‑c	attacher une console interactive (détacher avec Ctrl-B D)
‑‑vnc‑proxy	‑v	exposer le VNC sur un port TCP local
‑‑listen ADDR	‑l ADDR	adresse d’écoute pour le proxy VNC (par défaut 127.0.0.1)
‑‑port N	‑p N	port TCP du proxy VNC (par défaut 5901)

Exemples :

Allume la VM et attache la console

freeboxvm poweron 12 --console

Allume la VM et démarre le proxy VNC sur 0.0.0.0:5902

freeboxvm poweron 12 --vnc-proxy -l 0.0.0.0 -p 5902

Allume la VM et démarre la console et le proxy VNC

freeboxvm poweron Debian-11 -c -v

Éteindre une VM

freeboxvm poweroff [-f|--force] <id|name>

Demande l’arrêt ACPI de la VM spécifiée.

‑‑force

‑f

Envoie un arrêt forcé (hard stop).

Exemples :

freeboxvm poweroff 0
freeboxvm poweroff --force Debian-11

Réinitialiser une VM

freeboxvm reset <id|name>

Exemples:

freeboxvm reset 0
freeboxvm reset Debian-11

Supprimer une VM

freeboxvm delete <id|name> [--disk|-d] [--force|-f]

Supprime la machine virtuelle spécifiée par son id numérique ou son nom. Si la suppression échoue, pensez à éteindre la VM au préalable.

‑‑disk	‑d	Supprimer également les disques et efivars
‑‑force	‑f	Supprimer une VM en cours d’exécution

Infos système Freebox

freeboxvm system

Affiche les ressources globales de la Freebox :

Mémoire totale et utilisée
Processeurs (CPUs) totaux et utilisés
État d’allocation des ports USB
Liste des ports USB disponibles
Chemin du répertoire VMs

Exemples:

$ freeboxvm system
Mémoire totale : 2048    Mémoire utilisée : 0    (0.0 %)
Nombre de CPU : 2    CPU utilisés : 0    (0.0 %)
USB externe alloué : Non
Liste des ports USB disponibles :
   usb-external-type-a
VMs directory path: /Disque 1/VMs

Lister distributions installables

freeboxvm os-list [options]

Liste les images de systèmes d’exploitation installables pour les VMs.

‑‑extra	‑e	Interroger des sources externes via libosinfo pour des images cloud-init (aarch64, qcow2/raw).
‑‑iso	‑i	Lister les ISOs installables au lieu des images cloud.
‑‑long	‑l	Afficher les informations détaillées (OS, distribution, URL, somme de contrôle, indicateur live).
‑‑check	‑c	Valider les URLs des images et des sommes de contrôle.
‑‑os	‑o	Filtrer les résultats par nom d’OS (ex. fedora, ubuntu).

Exemples:

Lister toutes les distributions disponibles

freeboxvm os-list

Afficher les informations détaillées

freeboxvm os-list --long

Valider les URLs

freeboxvm os-list --check --long

Lister les ISOs installables

freeboxvm os-list --iso

Filtrer par OS (ex. uniquement Fedora)

freeboxvm os-list --os fedora

Télécharger une image

freeboxvm download [options] [short-id]

Télécharge une image d’installation de VM (disque ou ISO) en utilisant le gestionnaire de téléchargements de la Freebox.

‑‑iso	‑i	Sélectionner une ISO d’installation plutôt qu’une image cloud/disque.
‑‑url URL	‑u URL	Fournir une URL directe au lieu d’un short-id.
‑‑hash HASH	‑a HASH	Fournir l’URL de la somme de contrôle lors de l’utilisation de --url.
‑‑filename F	‑f F	Nom de fichier sous lequel enregistrer.
‑‑directory D	‑d D	Répertoire Freebox où stocker le fichier (encodé automatiquement en base64).
‑‑background	‑b	Lancer le téléchargement en arrière-plan (progression non affichée ; vérifier dans la section "Téléchargements" de la Freebox).

Examples:

Télécharger une image Fedora cloud-init via short-id

freeboxvm download fedora40

Télécharger une ISO Ubuntu au lieu d’une image cloud

freeboxvm download --iso ubuntu24.04

Fournir une URL personnalisée et sa somme de contrôle

freeboxvm download --url https://cloud-images.ubuntu.com/.../disk.qcow2 \
                   --hash https://cloud-images.ubuntu.com/.../SHA256SUMS

Télécharger en mode arrière-plan

freeboxvm download --background fedora

Licence

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.

Name		Name	Last commit message	Last commit date
Latest commit History 39 Commits
.copr		.copr
man/man1		man/man1
src		src
LICENSE		LICENSE
MANIFEST.in		MANIFEST.in
README.en.md		README.en.md
README.md		README.md
freeboxvm		freeboxvm
freeboxvm.spec		freeboxvm.spec
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt

Folders and files

Latest commit

History

Repository files navigation

freeboxvm

Prérequis

Installation :

Authentification et fichier token

Utilisation

Lister les VMs

Exemples :

Vue courte

Vue longue avec ports USB

Détails disques et cloud-init

Afficher une VM

Exemples :

Se connecter à la console d’une VM

Exemples :

Exposer l’écran d’une VM via proxy VNC

Exemples :

Proxy VNC pour la VM 0 sur localhost:5901

Proxy pour la VM 12 sur toutes interfaces, port 5902

Proxy et console pour une VM par nom

Gestion des disques

Exemples :

Crée un disque qcow2 de 10 Gio

Redimensione un disque à 20 Gio

Force un redimensionnement destructif (réduction de la taille)

Affiche les informations relatives au disque

Supprime un disque

Installer une nouvelle VM

Notes :

Exemple :

Installer depuis un identifiant de distribution (cloud image), activer cloud-init et attacher la console

Installer depuis une URL d’ISO CDROM, attacher la console et lancer le proxy VNC

Allumer une VM

Exemples :

Allume la VM et attache la console

Allume la VM et démarre le proxy VNC sur 0.0.0.0:5902

Allume la VM et démarre la console et le proxy VNC

Éteindre une VM

Exemples :

Réinitialiser une VM

Exemples:

Supprimer une VM

Infos système Freebox

Exemples:

Lister distributions installables

Exemples:

Lister toutes les distributions disponibles

Afficher les informations détaillées

Valider les URLs

Lister les ISOs installables

Filtrer par OS (ex. uniquement Fedora)

Télécharger une image

Examples:

Télécharger une image Fedora cloud-init via short-id

Télécharger une ISO Ubuntu au lieu d’une image cloud

Fournir une URL personnalisée et sa somme de contrôle

Télécharger en mode arrière-plan

Licence

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages