Mininet-WiFi turns a Linux host into a wireless network emulator

A fork that only adds the wireless layer

Mininet-WiFi is described as a fork of Mininet that allows the use of both WiFi stations and access points, and the README makes the scope claim plainly: it only adds wifi features and you can work with it like you were working with Mininet.

That framing matters because Mininet is a known quantity. Mininet gives you process-based virtual hosts, switches and links that you script in Python, and Mininet-WiFi keeps that model and adds the radio dimension. The setup.py in the repository describes the project as a process-based SDN emulator whose long description says it uses lightweight virtualization to create virtual networks for rapid prototyping of Software-Defined Wireless Network designs using OpenFlow.

The authorship is the same pairing as upstream, Bob Lantz and Ramon Fontes, and the README attributes the project to the INTRIG group, Information and Networking Technologies Research and Innovation Group, at the University of Campinas in Brazil. The documentation site is mn-wifi.readthedocs.io.

So the target audience is clear. If your research question needs a station associating with an access point, a handover between cells, a mobility model driving a client's position, or an OpenFlow rule reacting to that, this is the tool that lets you reproduce the experiment tomorrow without hardware.

Installing on Ubuntu, with flags that pick the pieces you need

The installation is four steps, and the README recommends Ubuntu 16.04 or higher, warning that some new hostapd features might not work on Ubuntu 14.04.

step 1: $ sudo apt-get install git  
step 2: $ git clone https://github.com/intrig-unicamp/mininet-wifi  
step 3: $ cd mininet-wifi  
step 4: $ sudo util/install.sh -Wlnfv  

The install script takes a set of letters, and the README lists what each one pulls in. -W is the wireless dependencies, -n is the mininet-wifi dependencies, -f is OpenFlow, -v is OpenvSwitch and -l is wmediumd. Two more are optional, -P for the P4 dependencies and -6 for the wpan tools.

The command shown in the README uses -Wlnfv, so the default install brings in wireless support, mininet-wifi itself, OpenFlow, OpenvSwitch and wmediumd, but not the P4 toolchain or the wpan tools.

The wmediumd piece deserves a note, because it is the component that lets several virtual interfaces share one physical radio, which is what makes a multi-cell topology possible on a single host with a single adapter. And the OpenFlow and OpenvSwitch flags are what connect the wireless topology to the same control plane model you would use for a wired Mininet network.

The Docker route, and the privileges it requires

The README recommends Docker if you are using a different Linux distribution from the ones the installation script supports. The build and run are two commands.

The build is straightforward:

    docker build -t mn-wifi:v1 .

The run command is where the requirements become visible:

    docker run -it --rm --privileged --env="DISPLAY" --env="QT_X11_NO_MITSHM=1" -v /tmp/.X11-unix:/tmp/.X11-unix:rw --net host -v /sys/:/sys -v /lib/modules:/lib/modules -v /sys/kernel/debug:/sys/kernel/debug -v /var/run/netns:/var/run/netns mn-wifi:v1

The README states the reasons plainly: Mininet-WiFi relies on kernel modules from the host, requires elevated privilege, and the host network interface. That is why the container runs with --privileged, why the host network namespace and the kernel module directories are mounted, and why the X11 socket is passed through for the graphical editor.

The Dockerfile behind it uses python:3.9 as the base, installs sudo, git, make, help2man, pyflakes3, python3-pycodestyle, tcpdump, wpan-tools and inetutils-ping, then installs six, numpy, matplotlib and beautifulsoup4 with pip. It also patches util/install.sh to drop dependency names that are outdated, and runs util/install.sh -Wlnfv6 during the image build, with the final command being /bin/bash.

The one thing to weigh is that this is not a light container. It runs privileged, with the host's sysfs, debugfs, modules and network namespaces mounted, which is essentially the host underneath.

The example topologies are the documentation

The examples directory is the best guide to what the emulator can actually express, and the file names read as a feature list of wireless research.

There is active_scan.py and adhoc.py for the two fundamental wireless modes, authentication.py and associationControl.py for the association layer, and a family of mobility files: mobility.py and mobilityModel.py, plus gaussMarkov3D.py for a three dimensional Gauss-Markov model and flightRadar24.py for pulling positions from a flight tracking service. There are handover.py and handover_bgscan.py for cell handover, with the background scan variant handling the scanning behaviour during the transition.

The network architecture is covered by multipleWlan.py for several radios in one host, mesh.py and meshAP.py for mesh topologies, forwardingBySSID.py for forwarding rules keyed on the network name, coherenceModel.py for signal coherence, battery.py for battery state, ieee80211p.py for the vehicular extension, 6LoWPan.py for the low pan personal area network extension, and a p4/ directory for programmable data plane work.

The examples also include authentication files in an eap-tls/ directory, and the setup.py package data lists eap_users and the certificate authority scripts under eap-tls/CA.

For a beginner who does not know Python, the README points to MiniEdit, which provides a GUI to generate Python scripts for a customised topology. The example file is examples/miniedit.py, and the Makefile explicitly excludes miniedit.py from the pep8 check for that reason.

Test targets, the mnexec helper and a compiled piece

The Makefile shows how the project is built and checked, and one detail is unusual for a Python project.

The default target is all: codecheck test. The codecheck target runs util/versioncheck.py, then pyflakes over the sources, then pylint with the.pylintrc configuration, and finally pep8 with a list of ignored codes, excluding miniedit.py from that check. There is also an errcheck target that runs pyflakes and pylint in error-only mode.

The test target runs the two test modules directly:

	mn_wifi/test/test_nets.py
	mn_wifi/test/test_hifi.py

And a slowtest target runs the walkthrough tests and the example runner with verbose output.

The mnexec target is the piece that stands out. It compiles mnexec.c with cc, passing the version string derived from running the Python code, and produces a native binary. The install target installs mnexec and the man pages and then runs setup.py install, while the develop target does the same with setup.py develop. Man pages are generated with help2man from the mn script.

The reason for a C helper is not spelled out in the README, but the source of the project lineage is: it inherits the same pattern from Mininet, where a small compiled helper exists alongside the Python emulator. The practical effect for you is that the install is not pure Python, so a compiler toolchain is part of the setup, and the Dockerfile confirms that by installing make and a C compiler.

The repository also carries custom/, demos/, doc/, examples/, hostap/, mn_wifi/, util/ and the mnexec.c file at the root, plus a debian/ directory for packaging and a.travis.yml for continuous integration.

Where it breaks, and the prebuilt VM that avoids the setup

The README has a short section on things to keep in mind, and it is the most useful part of the document for anyone about to spend an evening on this.

You can use any wireless network tools, for example iw, iwconfig and wpa_supplicant, which is a freedom rather than a restriction. You are asked to consider standard network troubleshooting steps before asking on the mailing list, and the two examples given are whether the station is associated with the access point and whether the OpenFlow rule is working correctly. Questions to the mailing list should include as much information as possible, and the list is at groups.google.com for mininet-wifi-discuss.

The known environment problem is Network Manager. Mininet-WiFi should work fine in any Ubuntu distribution from 14.04, but in some cases, only if you have problems when starting it, you have to stop Network Manager with either `sudo systemctl stop network-manager` or `sudo service network-manager stop`.

That is a real constraint, because Network Manager manages the wireless adapter on a typical laptop, and the emulator needs that adapter in monitor mode.

For people who would rather not deal with any of it, the project ships pre-built VM images in .ova format that should be usable with any modern x64 virtualization system. The listed image is a 4.6GB Lubuntu 20.04 x64 with the password wifi, which is about as fast a way to get a working environment as exists.

There is also a book, published in printed and e-book versions and available in English and Portuguese, along with a separate GitHub repository holding all the use cases presented in it, and a use cases catalogue spreadsheet for people doing research who are asked to let the project know.

Editorial conclusion

Adopt Mininet-WiFi if you are prototyping software defined wireless network designs and need repeatable topologies with stations, access points, mobility models and OpenFlow rules on one machine, since it keeps the Mininet workflow and only adds the wireless layer. Do not adopt it on a laptop with no spare wireless adapter, since the access points need real hostapd support and a monitor mode capable interface, and do not expect it to model real radio behaviour, since it is a network emulator rather than a channel simulator. Before you commit, check that your distribution is one the install script supports, read the known issues around Network Manager, and note the maintenance picture, with the last push on 2026-10-21 and no GitHub releases published.

Frequently asked questions

Official sources

1. intrig-unicamp/mininet-wifi on GitHub
2. Issues
3. Project website
4. README