{"id":27355466,"url":"https://github.com/pgj/freebsd-wifibox","last_synced_at":"2025-04-12T22:01:38.235Z","repository":{"id":40259582,"uuid":"387037568","full_name":"pgj/freebsd-wifibox","owner":"pgj","description":"wifibox: Use Linux to drive your wireless card on FreeBSD","archived":false,"fork":false,"pushed_at":"2025-03-23T21:03:56.000Z","size":140,"stargazers_count":192,"open_issues_count":14,"forks_count":13,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-03-23T22:19:34.417Z","etag":null,"topics":["bhyve","freebsd","virtualization","wifi","wireless"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pgj.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-07-17T21:12:25.000Z","updated_at":"2025-03-23T21:03:57.000Z","dependencies_parsed_at":"2024-02-07T09:33:51.077Z","dependency_job_id":"40b19b72-6929-4d4a-a7ca-be633c3735d0","html_url":"https://github.com/pgj/freebsd-wifibox","commit_stats":null,"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pgj%2Ffreebsd-wifibox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pgj%2Ffreebsd-wifibox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pgj%2Ffreebsd-wifibox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pgj%2Ffreebsd-wifibox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pgj","download_url":"https://codeload.github.com/pgj/freebsd-wifibox/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248637780,"owners_count":21137538,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bhyve","freebsd","virtualization","wifi","wireless"],"created_at":"2025-04-12T22:01:29.033Z","updated_at":"2025-04-12T22:01:38.223Z","avatar_url":"https://github.com/pgj.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Project FreeBSD Wifibox\n\nWifibox deploys a Linux guest to drive a wireless networking card on\nthe FreeBSD host system with the help of PCI pass-through.  There have\nbeen guides on the Internet to suggest the use of such techniques to\nimprove the wireless networking experience on FreeBSD, of which\nWifibox tries to implement as a single easy-to-use software package.\n\n- [`bhyve`], a lightweight virtualization solution for FreeBSD, is\n  utilized to run the embedded Linux system.  This helps to achieve\n  low resource footprint.\n\n- Configuration files could be shared with the host system.  For\n  example, the guest may either use `wpa_supplicant(8)` or\n  `hostapd(8)` and it is possible to import the host's\n  `wpa_supplicant.conf(5)` and `hostapd.conf(5)` files without any\n  changes.\n\n- When configured by the guest, `wpa_supplicant(8)` or `hostapd(8)`\n  control sockets could be exposed, which enables use of related\n  utilities directly from the host, such as `wpa_cli(8)` or\n  `wpa_gui(8)` from the [`net/wpa_supplicant_gui`] FreeBSD package, or\n  `hostapd_cli(8)`.\n\n- Everything is shipped in a single FreeBSD package that can be easily\n  installed and removed.  It comes with an `rc(8)` system service that\n  automatically launches the guest on boot and stops it on shutdown.\n\n- A workaround is supplied for laptops to support suspend/resume.\n\nFor more information on the background and the high-level overview of\nWifibox, please read the [article] in the November/December 2024\nedition of the FreeBSD Journal on Virtualization.\n\n## Warning\n\n*This is a work-in-progress experimental software project without any\nguarantees or warranties.  It is shared in the hope that is going to\nbe useful and inspiring for others.  By its nature, it is a workaround\nand shall be deprecated once the FreeBSD wireless drivers and\nnetworking stack are updated to catch up with Linux.*\n\n*Wifibox does not necessarily offer a drop-in replacement for the\nwireless networking stack of FreeBSD.  This is entirely determined by\nhow the guest exposes network traffic for the host, which might happen\nvia Network Address Translation (NAT) or bridging, for example.  Be\nsure to consult the documentation of the guest itself before use.*\n\n## Prerequisites\n\nBefore the installation, please check if those items are present on\nthe target computer otherwise running the software might not be\npossible:\n\n- A CPU that is supported by [`bhyve`] PCI pass-through (I/O MMU) with\n  ~256 MB physical memory or less depending on the guest, and some\n  disk space available for the guest virtual disk image.\n\n- A PCI wireless card that is known to be supported by the recent\n  Linux versions, but it is not performing well enough under FreeBSD.\n  Also, the Linux driver has to support [Message Signaled Interrupts]\n  (MSI) because that is required for the PCI pass-through to work.\n  USB wireless adapters are not supported.\n\n- A supported FreeBSD/amd64 system: 13.5-RELEASE or 14.2-RELEASE.\n  Later versions will also probably work, but your mileage may vary.\n\n- [`grub2-bhyve`] or the corresponding `sysutils/grub2-bhyve` FreeBSD\n  package, so the Linux guest could be booted via GRUB 2.\n\n- [`socat`] or the respective `net/socat` FreeBSD package, through\n  which control sockets for `wpa_supplicant(8)` and `hostapd(8)` could\n  be published on the host.  The presence of `socat` is required only\n  if this feature is activated, which depends on the guest\n  configuration.\n\n## Installation\n\nUse the `net/wifibox` FreeBSD port which is available at the\n[`freebsd-wifibox-port`] repository and automatically takes care of all\nthe following details, installs a guest image, and offers proper\nremoval of the installed files, hence it is a more convenient way to\nmanage the whole installation process.\n\n### Manual Installation\n\nAlternatively, a `Makefile` is present in this repository that can be\nused to install all the files, as described below.  This workflow is\nmostly recommended for development and testing.\n\n```console\n# make install \\\n    PREFIX=\u003cprefix\u003e \\\n    LOCALBASE=\u003cprefix of the grub2-bhyve and socat packages\u003e \\\n    GUEST_ROOT=\u003cguest disk image location\u003e \\\n    GUEST_MAN=\u003cguest manual page location\u003e \\\n    RECOVERY_METHOD=\u003cmethod to use on suspend and resume\u003e \\\n    DEVD_FIX=\u003cadd extra devd.conf(5) configuration to handle suspend\u003e\n```\n\nBy default, `PREFIX` is set to `/usr/local`.  In addition to that, it\nis possible to set the `LOCALBASE` variable to tell if the prefix\nunder which the `grub-bhyve` and `socat` utilities were installed is\ndifferent.\n\nThe `GUEST_ROOT` variable should point to the directory that houses\nthe files related to the guest.  Note that these are not part of the\nrepository and should be installed individually.  For example, such\nfiles could be installed from the [`freebsd-wifibox-alpine`]\nrepository.\n\n- GRUB is going to be configured according to the contents of\n  `grub.cfg`, and then the system is booted from the virtual disk\n  image whose contents should be stored as `disk.img`.\n\n- When needed, `device.map` could also be placed there to teach GRUB\n  about the virtual disk image.\n\nThe `RECOVERY_METHOD` variable can be used to tell in which way\nWifibox should be revived on a suspend/resume pair of events.\n\n- The default value is `restart_vmm`, which means that guest will be\n  stopped, and the `vmm(4)` kernel module will be reloaded then the\n  guest will be restarted on resume.\n- Another option is `suspend_guest`, which will stop the only guest on\n  suspend and then start it again on resume.\n- Finally, there is `suspend_vmm`, which will stop both the guest and\n  unload the `vmm(4)` kernel module on suspend and implement the\n  reverse on resume.\n- The recovery mechanism itself could be disabled by setting this\n  value to be empty.\n\nThe `DEVD_FIX` variable controls the deployment of a fix for handling\nthe ACPI suspend event.  In older FreeBSD versions, suspend will not\nautomatically trigger a call for the `service wifibox suspend` command\nso that has to be explicitly configured.  This has been added for\nFreeBSD 14.0 hence it is not required any more from that version\nonwards.  Set it to an empty value to disable this fix, otherwise the\ndefault value is going to be determined based on the OS version where\nthe build is run.\n\n## Documentation\n\nThere is a manual page installed that can be used to learn about the\nbasic usage and configuration.\n\n```console\n# man wifibox\n```\n\n## Compatibility\n\nIt has been reported working successfully on the following\nconfigurations:\n\n| CPU | Wireless NIC | Model | FreeBSD |\n| :-- | :----------- | :---- | :------ |\n| AMD A6-9225 | Realtek RTL8821CE | Lenovo IdeaPad 330-15AST | 13.1-RELEASE, 14-CURRENT |\n| AMD Ryzen 3 5300U | Realtek RTL8852CE | HP HP Laptop 15s-eq2xxx | 14.1-RELEASE |\n| AMD Ryzen 5 5600G | Intel Wi-Fi 6 AX-200 | ASUS ROG STRIX B550-I GAMING | 13-STABLE, 14-CURRENT |\n| AMD Ryzen 5 5600G | AMD RZ608 Wi-Fi 6E (MediaTek MT7921K) | ASUS ROG STRIX B550-I GAMING | 13-STABLE, 14-CURRENT |\n| AMD Ryzen 5 PRO 8540U | AMD RZ616 Wi-Fi 6E 802.11ax (MediaTek MT7922) | HP EliteBook 845 G11 (8R632AV) | GhostBSD 24.10.1 |\n| AMD Ryzen 7 5700U | Realtek RTL8852AE | HP 255 G8 | 13.2-RELEASE |\n| AMD Ryzen 7 5700X | Intel Wi-Fi 6 AX-200 | GigaByte X570S | 13-STABLE, 14-CURRENT |\n| AMD Ryzen 7 5700X | AMD RZ608 Wi-Fi 6E (MediaTek MT7921K) | GigaByte X570S | 13-STABLE, 14-CURRENT |\n| AMD Ryzen 7 5825U | Realtek RTL8852BE | HP Laptop 15s-eq3636nz | 13.2-RC3 |\n| AMD Ryzen 9 9950X | Intel Wi-Fi 6E AX210 | Minisforum MS-A1-N0CPUR | 14.2-RELEASE |\n| Intel Core i5-3210M | Broadcom BCM4331 | Apple MacBook Pro A1278 | 13.2-RELEASE |\n| Intel Core i5-5300U | Intel Wireless 7265 | Lenovo ThinkPad T450 | 13.1-RELEASE |\n| Intel Core i5-6300U | Intel Dual Band Wireless AC 8260 | Lenovo ThinkPad X270 | 13.5-RELEASE, 14.2-RELEASE, 15-CURRENT (snapshot `20250321-5d02f17e8253-276037`) |\n| Intel Core i5-10210U | Intel Dual Band Wireless AC 9500 | System 76 Lemur Pro 'LEMP9' | 13.0-RELEASE |\n| Intel Core i5-8250U | Realtek RTL8822BE | Lenovo YOGA 730 | 13.2-RELEASE |\n| Intel Core i7-4600M | Intel Centrino Advanced-N 6235 | Dell Latitude E6440 | 13.0-RELEASE |\n| Intel Core i7-4870HQ | Broadcom BCM43602 | Apple MacBook Pro 11.4 | 13.3-RELEASE |\n| Intel Core i7-6600U | Intel(R) Dual Band Wireless AC 8260 | Lenovo ThinkPad T470 | 14.1-RELEASE |\n| Intel Core i7-7500U | Intel(R) Dual Band Wireless AC 8265 | Lenovo ThinkPad X1 Carbon Gen5 | 13.2-RELEASE |\n| Intel Core i7-7700K | Intel(R) Dual Band Wireless AC 3168 | Desktop HP 820 NL | 13.2-RELEASE |\n| Intel Core i7-7820HQ | Intel(R) Wi-Fi 6E AX210/AX1675 | Dell Precision 7720 | 13.3-RELEASE, 14.1-RELEASE  |\n| Intel Core i7-8565U | Qualcomm Atheros QCA6174 | Dell XPS 9380 | 13-STABLE |\n| Intel Core i7-8650U | Intel(R) Dual Band Wireless AC 8265 | Lenovo ThinkPad T480 | 13.1-RELEASE |\n| Intel Core i7-8665U | Intel(R) Dual Band Wireless AC 9560 | Lenovo ThinkPad X1 Carbon | GhostBSD 24.01.1 |\n| Intel Core i7-10850H | Intel(R) Wi-Fi 6 AX201 | Dell Precision 7550 | 14.2-STABLE |\n| Intel Core i7-1185G7 | Intel(R) Wi-Fi 6 AX201 | Lenovo ThinkPad X1 Carbon Gen9 | 14.2-RELEASE |\n\nFeel free to submit a pull request or write an email to have your\nconfiguration added here!\n\n[`bhyve`]: https://wiki.freebsd.org/bhyve\n[Message Signaled Interrupts]: https://www.kernel.org/doc/Documentation/PCI/MSI-HOWTO.txt\n[`freebsd-wifibox-port`]: https://github.com/pgj/freebsd-wifibox-port\n[`freebsd-wifibox-alpine`]: https://github.com/pgj/freebsd-wifibox-alpine\n[`net/wpa_supplicant_gui`]: https://cgit.freebsd.org/ports/tree/net/wpa_supplicant_gui\n[`grub2-bhyve`]: https://github.com/grehan-freebsd/grub2-bhyve\n[`socat`]: http://www.dest-unreach.org/socat/\n[article]: https://github.com/pgj/freebsd-wifibox/releases/download/freebsd-journal-2024-06/freebsd-journal-wifibox.pdf\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpgj%2Ffreebsd-wifibox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpgj%2Ffreebsd-wifibox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpgj%2Ffreebsd-wifibox/lists"}