Contexte et objectifs

Le projet vd_agent est un fork communautaire du dépôt abandonné spice/win32/vd_agent de freedesktop.org. Il vise à conserver la compilation et la distribution de l'agent Windows pour SPICE, indispensable aux machines virtuelles (VM) Windows 11 exécutées sous Linux (QEMU/KVM + SPICE). Le fork assure la continuité des fonctionnalités suivantes : mode souris client sans capture du pointeur, adaptation dynamique de la résolution du bureau, partage du presse‑papier (texte et images), transfert de fichiers vers l’invité, et un service Windows (spice-agent) qui lance startsvdagent.exe dans chaque session utilisateur.

Red Hat ne maintient plus l’amont de SPICE, ce qui rend ce fork crucial pour les environnements qui dépendent encore de l’agent Windows, notamment les déploiements d’entreprise qui utilisent des GPU pass‑through.

Architecture et processus de construction

Le code source s’appuie sur une chaîne de compilation hybride : Autotools + MinGW‑w64 UCRT64 constitue le chemin recommandé pour produire le MSI, tandis que CMake + MSVC reste disponible pour le développement local mais ne génère pas d’installeur. Le script d’installation automatisé (msys2/install.sh) récupère les dépendances (autotools, autoconf‑archive, toolchain UCRT64, msitools via wixl, ImageMagick) et prépare l’environnement MSYS2.

git clone --recursive https://github.com/nefarius/vd_agent.git
cd vd_agent
bash msys2/install.sh
autoreconf -i
bash msys2/build.sh builducrt64
bash msys2/package.sh builducrt64

Le processus de versionnage utilise git describe via build-aux/git-version-gen. Les balises doivent suivre le schéma v0.11.0; les builds non balisés ajoutent le nombre de commits depuis la dernière balise (ex. 0.11.0.83‑). Un dépassement de 256 dans le compteur + --with-buildid déclenche un échec de configuration pour éviter les collisions avec le prochain micro‑version.

Mécanismes fonctionnels et correctifs

Le correctif multi‑GPU (d7405ee) intégré dans vdagent/desktop_layout.cpp empêche la perte de mouvement du pointeur lorsqu’un GPU physique est passé en passthrough aux côtés du dispositif d’affichage SPICE. Ce correctif repose sur la détection du dispositif QXL ou QXL‑WDDM‑DOD et la mise à jour du mapping de coordonnées du pointeur.

Le partage du presse‑papier s’appuie sur le composant Windows Imaging Component (WIC) présent depuis Windows Vista, permettant la conversion PNG des images avant leur transmission. Le service spice-agent assure le lancement de vdagent.exe dans chaque session, garantissant que les fonctions de résolution dynamique et de transfert de fichiers restent actives même après une mise à jour du MSI.

Gestion de la chaîne de production et de la signature

Les artefacts sont construits via GitHub Actions (.github/workflows/build.yml) sur un runner windows‑2022. La signature Authenticode utilise le composite action SignRelay, dont le commit est figé à 39ccbe0cef16a383237130380a5aef8db040d5d0. Le certificat de signature réside sur un serveur dédié ; le workflow signe d’abord les exécutables (vdagent.exe, vdservice.exe), puis le MSI, et vérifie la validité avec Get‑AuthenticodeSignature. Un fichier .sha256 est généré et joint à la release GitHub.

Le processus de publication impose la création d’une balise annotée (git tag -a v0.11.0 -m "vdagent‑win 0.11.0") puis le push vers le dépôt distant. En cas d’échec après le démarrage de la signature, le correctif consiste à pousser une nouvelle balise ou à incrémenter le numéro mineur, tout en conservant l’immuabilité des MSI déjà diffusés. Les builds x86 ne sont plus produits, la pipeline se concentre sur les artefacts x64, ce qui simplifie la maintenance tout en couvrant la majorité des déploiements modernes.