diff --git a/README.md b/README.md index aa1dd9e..6a0ff90 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,17 @@ # vwifi: A Simple Virtual Wireless Driver for Linux -`vwifi` implements a minimal interface to achieve basic functionalities, -such as scanning dummy Wi-Fi networks, connecting, and disconnecting from them. -It is based on the [cfg80211 subsystem](https://www.kernel.org/doc/html/latest/driver-api/80211/cfg80211.html), -which works together with FullMAC drivers. -Currently, vwifi supports both Station Mode and Host AP Mode, and is well-equipped with WPA/WPA2 security facilities. This enables users to set up a wireless environment using vwifi, hostapd (in HostAP mode interface), and wpa_supplicant (in station mode interface). +`vwifi` implements a minimal interface to provide essential functionalities, +such as scanning for dummy Wi-Fi networks, establishing connections, and +disconnecting from them. -Furthermore, when running on hypervisors like Qemu, `vwifi` becomes a `virtio-net` driver and has the capability to do inter-guest communication. To test `vwifi` with the virtio feature, [click here](#Testing-environment-(virtio)) to jump to the virtio section below. +It is built upon the [cfg80211 subsystem](https://www.kernel.org/doc/html/latest/driver-api/80211/cfg80211.html), +which collaborates with FullMAC drivers. Currently, `vwifi` supports both +Station Mode and Host AP Mode and is equipped with robust WPA/WPA2 security +features. This enables users to configure a wireless environment using `vwifi`, +`hostapd` (in HostAP mode interface), and `wpa_supplicant` (in station mode interface). + +Moreover, when running on hypervisors like QEMU, `vwifi` functions as a virtio-net +driver, allowing for inter-guest communication. ## Prerequisite @@ -219,7 +224,7 @@ $ sudo ip netns exec ns2 ip addr add 10.0.0.3/24 dev owl2 ### Running hostapd on the HostAP Mode Interface Prepare the following script `hostapd.conf` (you can modify the script based on your needs): -```shell +``` interface=owl0 driver=nl80211 debug=1 @@ -238,7 +243,7 @@ Run `hostapd` on the interface `owl0`: $ sudo ip netns exec ns0 hostapd -i owl0 -B hostapd.conf ``` -### Running wpa_supplicant on the Station Mode Interfaces +### Running `wpa_supplicant` on the Station Mode Interfaces Prepare the following script `wpa_supplicant.conf` (you can modify the script based on your needs): ```shell network={ @@ -249,10 +254,10 @@ network={ Then run the `wpa_supplicant` on the interface `ns1` and `ns2`: ```shell -sudo ip netns exec ns1 \ -wpa_supplicant -i owl1 -B -c wpa_supplicant.conf -sudo ip netns exec ns2 \ -wpa_supplicant -i owl2 -B -c wpa_supplicant.conf +$ sudo ip netns exec ns1 \ + wpa_supplicant -i owl1 -B -c wpa_supplicant.conf +$ sudo ip netns exec ns2 \ + wpa_supplicant -i owl2 -B -c wpa_supplicant.conf ``` ### Validating the Connection @@ -281,7 +286,7 @@ sudo ip netns exec ns0 iw dev owl0 station dump ``` The output may seem like this: -```shell +``` Station 00:6f:77:6c:31:00 (on owl0) inactive time: 5588 ms rx bytes: 5366 @@ -301,6 +306,7 @@ Station 00:6f:77:6c:32:00 (on owl0) signal: -57 dBm current time: 1689679337171 ms ``` + ### Transmission/Receivement test Finally, we can do the ping test: 1. To perform a ping test between two STAs (`owl1` and `owl2`), use the following command: @@ -342,12 +348,21 @@ rtt min/avg/max/mdev = 0.054/0.141/0.342/0.117 ms ## Testing environment (virtio) Below is our testing environment with virtio feature: -
+ + +`vwifi` utilizes the virtio-net device, the Linux tap device, and the Linux +bridge device to enable inter-guest communication. + +In our testing environment, on the host side, we create three tap devices and +one bridge device. Then, we attach each tap device to the bridge device. We also +create three VMs using QEMU, configuring each with a virtio-net device and +specifying that each virtio-net device connects to a corresponding tap device on +the host. + +In VM1, the network interface created by `vwifi` operates in HostAP mode, with +the user program hostapd running on top of it. In VM2 and VM3, we have STA mode +interfaces with `wpa_supplicant` running on top of them. -vwifi makes use of the `virtio-net` device, Linux tap device, and Linux bridge device to fulfill inter-guest communication. -In our testing environment, on the host side, we create three `tap` devices and one `bridge` device, then attach each `tap` device to the `bridge` device. And we create three VMs by `Qemu` with the `virtio-net` devices and specify that every `virtio-net` device connects to a `tap` device in the host. -In VM1, the network interface created by `vwifi` will be in HostAP mode, with the user program `hostapd` running on top of it. -In VM2 and VM3, we have an STA mode interface and `wpa_supplicant` running on top of it. ## Build and Run (virtio) Below describes how to build a minimal workable VM environment. ### Build Linux kernel @@ -355,15 +370,15 @@ Download Linux kernel source from [kernel.org](https://kernel.org/). Enter the top directory of the Linux kernel source and use the following command to generate the configuration file: ```shell -make menuconfig +$ make menuconfig ``` The default kernel cofiguration will work for our testing environment, so just click `save` and we get `.config` on the top directory. Before building the kernel, please ensure that all the needed packges or libraries have been installed in your machine. Then Build the kernel: -``` -make -j