Hello everyone!
This summer as part of GSOC 2025 I’ve worked on Adding Wi-Fi Support to QEMU Simulations in Libremesh. This project consisted in “bridging” virtual machine running LibreMesh firmware using their Wi-Fi interfaces inside QEMU, in order for it to become part of the development loop of the LibreMesh.
This is my final write up for this project, and a conclusion of an enriching journey. You can also explore my first and second blogposts for Freifunk.
This project led me to learn a lot about virtualization, OpenWrt, and open source in general !
Simulating Wi-Fi within a Virtual Machine
Testing wireless communications is a tricky problem for many reasons : the medium through which the messages are being sent around being literally made out of thin air, observability is subpar and repeatability is complicated, involving hardware heavy setup.
Thankfully, mac80211_hwsim solves (most) of the issues for us.
In simple terms, this module simulates Wi-Fi hardware inside the Linux Kernel, and allows us full control of it – as many Wi-Fi radios as one would want within a single machine and with complete control over it, with each of the radios able to talk to the other radios created by this module.
kmod-mac80211-hwsim
OpenWrt being based on the Linux Kernel, we should have access to this module.Even better : it’s a package ! That’s good news since now integrating this solution to our future testing will require minimal intervention : it’s a simple package to add to our build configuration.
LibreMesh virtual Wi-Fi capable firmware
So following LibreMesh instructions for building our own firmware, and by simply adding kmod-mac80211-hwsim to our configuration, we end up with exactly what we are looking for : a virtual Wi-Fi capable LibreMesh firmware.
Unfortunately, mac80211_hwsim limitless possibilities bring us some issues : LibreMesh firmware have never been tested against 6G capable router, and ends up wrongly configuring the virtual radios, preventing us from obversing the expected behaviors. This led me to dig about Wi-Fi bands and their specifications, especially 802.11ax which brings a whole set of restrictions (and confusions) especially in the upper range of the spectrum.
All in all this was beneficial to the project since I was able to provide a patch to fix the unexpected behaviors, which in the end should speed up the (future) integration of LibreMesh to 6G capable routers.
Once the fix provided, LibreMesh firmware was working as expected when run inside a QEMU virtual machine – I was able to replicate the classic AP-STA set up within the virtual machine, as is usually showcased when demonstrating the capabilities of mac80211_hwsim.
Connecting multiple virtual machines through Wi-Fi interfaces
Now that we were able to have a working virtual machine with Wi-Fi capabilities, the goal was to have multiple of these virtual machines, and to connect them to each other through their Wi-Fi interfaces, create a “virtual mesh”.
Connecting multiple QEMU virtual machines through their virtual ethernet interfaces have been a solved issue since many years (even though there is still active development in that area) due to the critical nature of the problem for the big cloud services provider, connecting multiple virtual machines through their Wi-Fi interfaces have mostly remained an afterthought, an academic project at most.
vwifi
vwifi is a project enabling simulation of Wi-Fi across multiple Linux QEMU virtual machines, relying on the mac80211_hwsim driver and finally, with specific support for OpenWrt
It basically relays Wi-Fi frames across the virtual machines : a server is running on the Host machine and each vms are connected to it. Inside each virtual machine, each radios are managed by the vwifi-client : each frame is passed to the server.
A schematic is provided for easier understanding of the setup.
Compilation of this project for OpenWrt is a bit finicky, but manageable. A package for easier integration with OpenWrt is under development by my mentor Javier Jorge.
Virtual Mesh in LibreMesh !
Now that we have a way to create Wi-Fi frames inside a virtual machine and have it relayed to an other machine, let’s piece everything together and create our LibreMesh mesh !
Meaning that new development of features for LibreMesh such as the shared-states packages relying on heavy and cumbersome infrastructure to test and iterate will be possible by simply cloning this set of scripts inside your OpenWrt build directory, and simply running them will provide a lightweight, reliable and quick to set up testbed.
Automation of testing in LibreMesh
Last piece of this puzzle is the automation of the testing in LibreMesh.
So far, testing in LibreMesh was provided by unit testing using a docker image and mockups of the expected behavior, and manual testing using real hardware. QEMU only occured during development and wasn’t fully integrated in the development process, since it was easier and more reliable to just upload the firmware to an adjacent router and observe the behavior. But now that we proved that it was possible to set up true and reliable Wi-Fi mesh network, the next obvious step is to provide automated testing and completely integrate it in the LibreMesh development loop.
OpenWrt-test
OpenWrt-test is a labgrid test based framework aiming at providing worldwide testing for OpenWrt across multiple devices. I’ve had the opportunity to meet up with the main developer of this project apacar during BattleMeshv17 and with my mentor and the LibreMesh community we decided to based our future QEMU based testing on this framework, since it is tightly integrated with OpenWrt and also based on the convenience when wanting to run the tests across different devices.
To use it, OpenWrt-test have to be cloned inside the OpenWrt build directory, and then a Makefile will handle the rest of the setup.
make tests/qemu-x86-64 V=s
will allow you to run the different tests (specific to OpenWrt) located inside the tests/ directory of the project.
The project have been forked in order to provide specific test to LibreMesh : despite being based on OpenWrt, LibreMesh still show some specific differences.
And finally, after a lot of struggle, I was finally able to integrate LibreMesh inside this framework with the rest of my work.
The setup consists in :
- starting the virtual LibreMesh mesh and setting up each of the VM,
- Running the labgrid test
Labgrid will then spin up its own virtual machine based on the latest build present in bin/target/x86/64 and then be able to connect to the virtual Wi-Fi mesh, and run automated test against the infrastructure. This allows to run repeatable tests in a controlled manner, orchestrate 4 different machines and quickly iterate when developing new feature requiring some specific Wi-Fi setup.
Future Work
This project managed to showcase the repeatability and convenience of Labgrid for automated tested, which coupled with the ability to create virtual Wi-Fi meshes brings a whole new worlds of possibilities for LibreMesh development, as well as any Wi-Fi mesh features : lightweight infrastructure, quick setup and fully repeatable.
Future work will concentrate on bringing better coverage for LibreMesh testing using the new tools that are now proven to be effective from this GSOC project. So far testing covers part of the shared-state packages, but different packages could be targeted, and not only the ones relying on a Wi-Fi mesh network but also general configurations.
Lastly, vwifi document way to introduce packet loss as well as nodes mobility : this could allow for different scenario of testing and bring a whole new set of robutness to the LibreMesh project.
Conclusion
This Google Summer of Code provided me the opportunity to discover many new things : I broaden my understanding of Wi-Fi and even discovered new use cases for it, tinkered with it in the Linux Kernel, learned about OpenWrt and LibreMesh and more importantly met with incredible and very passionate people.
I’m very thankful to have been able to work on such a project during this summer, and would like to thank very fondly my mentor Javier Jorge for his support throughout this adventure.
Thank you also to Freifunk for allowing this to happen, it’s really a fantastic opportunity for everyone involved.
I will definitely continue to contribute to LibreMesh and OpenWrt and hope to meet with you in person at BattleMeshv18!