https://github.com/pgj/freebsd-wifibox

wifibox: Use Linux to drive your wireless card on FreeBSD
https://github.com/pgj/freebsd-wifibox

bhyve freebsd virtualization wifi wireless

Last synced: about 1 year ago
JSON representation

wifibox: Use Linux to drive your wireless card on FreeBSD

Host: GitHub
URL: https://github.com/pgj/freebsd-wifibox
Owner: pgj
License: bsd-2-clause
Created: 2021-07-17T21:12:25.000Z (almost 5 years ago)
Default Branch: main
Last Pushed: 2025-03-23T21:03:56.000Z (over 1 year ago)
Last Synced: 2025-03-23T22:19:34.417Z (over 1 year ago)
Topics: bhyve, freebsd, virtualization, wifi, wireless
Language: Shell
Homepage:
Size: 137 KB
Stars: 192
Watchers: 9
Forks: 13
Open Issues: 14
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

README

# Project FreeBSD Wifibox

Wifibox deploys a Linux guest to drive a wireless networking card on
the FreeBSD host system with the help of PCI pass-through. There have
been guides on the Internet to suggest the use of such techniques to
improve the wireless networking experience on FreeBSD, of which
Wifibox tries to implement as a single easy-to-use software package.

- [`bhyve`], a lightweight virtualization solution for FreeBSD, is
utilized to run the embedded Linux system. This helps to achieve
low resource footprint.

- Configuration files could be shared with the host system. For
example, the guest may either use `wpa_supplicant(8)` or
`hostapd(8)` and it is possible to import the host's
`wpa_supplicant.conf(5)` and `hostapd.conf(5)` files without any
changes.

- When configured by the guest, `wpa_supplicant(8)` or `hostapd(8)`
control sockets could be exposed, which enables use of related
utilities directly from the host, such as `wpa_cli(8)` or
`wpa_gui(8)` from the [`net/wpa_supplicant_gui`] FreeBSD package, or
`hostapd_cli(8)`.

- Everything is shipped in a single FreeBSD package that can be easily
installed and removed. It comes with an `rc(8)` system service that
automatically launches the guest on boot and stops it on shutdown.

- A workaround is supplied for laptops to support suspend/resume.

For more information on the background and the high-level overview of
Wifibox, please read the [article] in the November/December 2024
edition of the FreeBSD Journal on Virtualization.

## Warning

*This is a work-in-progress experimental software project without any
guarantees or warranties. It is shared in the hope that is going to
be useful and inspiring for others. By its nature, it is a workaround
and shall be deprecated once the FreeBSD wireless drivers and
networking stack are updated to catch up with Linux.*

*Wifibox does not necessarily offer a drop-in replacement for the
wireless networking stack of FreeBSD. This is entirely determined by
how the guest exposes network traffic for the host, which might happen
via Network Address Translation (NAT) or bridging, for example. Be
sure to consult the documentation of the guest itself before use.*

## Prerequisites

Before the installation, please check if those items are present on
the target computer otherwise running the software might not be
possible:

- A CPU that is supported by [`bhyve`] PCI pass-through (I/O MMU) with
~256 MB physical memory or less depending on the guest, and some
disk space available for the guest virtual disk image.

- A PCI wireless card that is known to be supported by the recent
Linux versions, but it is not performing well enough under FreeBSD.
Also, the Linux driver has to support [Message Signaled Interrupts]
(MSI) because that is required for the PCI pass-through to work.
USB wireless adapters are not supported.

- A supported FreeBSD/amd64 system: 13.5-RELEASE or 14.2-RELEASE.
Later versions will also probably work, but your mileage may vary.

- [`grub2-bhyve`] or the corresponding `sysutils/grub2-bhyve` FreeBSD
package, so the Linux guest could be booted via GRUB 2.

- [`socat`] or the respective `net/socat` FreeBSD package, through
which control sockets for `wpa_supplicant(8)` and `hostapd(8)` could
be published on the host. The presence of `socat` is required only
if this feature is activated, which depends on the guest
configuration.

## Installation

Use the `net/wifibox` FreeBSD port which is available at the
[`freebsd-wifibox-port`] repository and automatically takes care of all
the following details, installs a guest image, and offers proper
removal of the installed files, hence it is a more convenient way to
manage the whole installation process.

### Manual Installation

Alternatively, a `Makefile` is present in this repository that can be
used to install all the files, as described below. This workflow is
mostly recommended for development and testing.

```console
# make install \
PREFIX= \
LOCALBASE= \
GUEST_ROOT= \
GUEST_MAN= \
RECOVERY_METHOD= \
DEVD_FIX=
```

By default, `PREFIX` is set to `/usr/local`. In addition to that, it
is possible to set the `LOCALBASE` variable to tell if the prefix
under which the `grub-bhyve` and `socat` utilities were installed is
different.

The `GUEST_ROOT` variable should point to the directory that houses
the files related to the guest. Note that these are not part of the
repository and should be installed individually. For example, such
files could be installed from the [`freebsd-wifibox-alpine`]
repository.

- GRUB is going to be configured according to the contents of
`grub.cfg`, and then the system is booted from the virtual disk
image whose contents should be stored as `disk.img`.

- When needed, `device.map` could also be placed there to teach GRUB
about the virtual disk image.

The `RECOVERY_METHOD` variable can be used to tell in which way
Wifibox should be revived on a suspend/resume pair of events.

- The default value is `restart_vmm`, which means that guest will be
stopped, and the `vmm(4)` kernel module will be reloaded then the
guest will be restarted on resume.
- Another option is `suspend_guest`, which will stop the only guest on
suspend and then start it again on resume.
- Finally, there is `suspend_vmm`, which will stop both the guest and
unload the `vmm(4)` kernel module on suspend and implement the
reverse on resume.
- The recovery mechanism itself could be disabled by setting this
value to be empty.

The `DEVD_FIX` variable controls the deployment of a fix for handling
the ACPI suspend event. In older FreeBSD versions, suspend will not
automatically trigger a call for the `service wifibox suspend` command
so that has to be explicitly configured. This has been added for
FreeBSD 14.0 hence it is not required any more from that version
onwards. Set it to an empty value to disable this fix, otherwise the
default value is going to be determined based on the OS version where
the build is run.

## Documentation

There is a manual page installed that can be used to learn about the
basic usage and configuration.

```console
# man wifibox
```

## Compatibility

It has been reported working successfully on the following
configurations:

Feel free to submit a pull request or write an email to have your
configuration added here!

[`bhyve`]: https://wiki.freebsd.org/bhyve
[Message Signaled Interrupts]: https://www.kernel.org/doc/Documentation/PCI/MSI-HOWTO.txt
[`freebsd-wifibox-port`]: https://github.com/pgj/freebsd-wifibox-port
[`freebsd-wifibox-alpine`]: https://github.com/pgj/freebsd-wifibox-alpine
[`net/wpa_supplicant_gui`]: https://cgit.freebsd.org/ports/tree/net/wpa_supplicant_gui
[`grub2-bhyve`]: https://github.com/grehan-freebsd/grub2-bhyve
[`socat`]: http://www.dest-unreach.org/socat/
[article]: https://github.com/pgj/freebsd-wifibox/releases/download/freebsd-journal-2024-06/freebsd-journal-wifibox.pdf

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/pgj/freebsd-wifibox

Awesome Lists containing this project

README