Ivan Oliinychenko

Disclaimer Using Wi-Fi for your Unraid server is rarely an optimal solution. If internet connection stability and bandwidth are critical for you, it’s recommended to look into using a wired connection. If you absolutely want to use Wi-Fi as a network source, consider using an external router in bridge mode first. It requires much less configuration and most of the time should be just “plug and play.” There are few use cases where using a passthrough Wi-Fi card could be justified. For example, the lack of a router that supports bridge mode and the existence of a spare PCIe Wi-Fi card, or lower power consumption compared to an external router. This guide requires some knowledge of Linux and networking. If you don’t feel confident in any of the steps, using a router in bridge mode will be a better option for you. This guide is focused solely on using OpenWrt as a VM. While it’s possible to use other OSes like pfSense, DD-WRT, or even Windows, this guide might not be the best source of information for that. It’s recommended to refer to the documentation of these OSes for passthrough configuration. Lastly, everyone's network configuration is different, so naturally, some of your configuration settings will differ from the ones in this guide. Tested on Unraid 6.12.10 and OpenWrt 23.05.3. Prerequisites Wi-Fi card supported by OpenWrt firmware (more on this later). Basic knowledge of networking, Linux, and the Vim text editor. On a Note of Theory As of the time of writing this guide, Unraid doesn’t support Wi-Fi. If your Unraid server has Wi-Fi and you want to use it as the main network source, you will either need to use an external router in bridge mode or a VM that can handle a Wi-Fi card (also known as device passthrough) and use a virtual bridge. In other words, the typical network topology for an Unraid server looks like this: Internet source -> Server hardware Ethernet network card -> Unraid OS We are trying to achieve the following: Internet source -> Server hardware Wi-Fi network card -> OpenWrt VM -> Unraid OS On a Note of OpenWrt “OpenWrt (from open wireless router) is an open-source project for embedded operating systems based on Linux, primarily used on embedded devices to route network traffic.” Wikipedia The guide 1. Download OpenWrt image. If your Unraid system is x86-x64 download generic-ext4-combined.img.gz, read more. 2. Unzip .gz file. gzip -d image_name.gz 3. Convert image to QEMU qcow2 format. qemu-img convert -O qcow2 image_name.img image_name.qcow2 4. Move image to Unraid domains folder. mv image_name.qcow2 /mnt/user/domains/ 5. Enable hardware passthrough from Unraid to VMs. In Unraid go to Tools -> System Devices, select your network device and apply configuration by clicking on “Bind selected to VFIO at Boot”. 6. Create an OpenWrt VM. In Unraid go to VMs and add a generic Linux VM. Recommended VM settings: Linux Logical CPU: 1 Core Initial Memory: 128 MB Machine: i440fx-7.1 BIOS: SeaBIOS Primary vDisk Bus: IDE Primary vDisk Location (Manual): /mnt/user/domains/image_name.qcow2 Network Source: br0 Network Model: virtio-net Select your network device that was shared in Step 5. Add a second network interface for access to WAN from the VM (could be removed after installing additional OpenWrt packages). Network Source: virbr0 Network Model: virtio-net All other settings can be left as default. Create and start VM. 7. Configure OpenWrt VM. 7.1 Connect to OpenWrt VM via console (VNC) and press ENTER. 7.2 Use Vim text editor to edit OpenWrt network configuration file. vi /etc/config/network 7.3 Find option ipaddr under config interface 'lan' and modify IP address to be in the same subnet as the Unraid server. option ipaddr '192.168.1.111' 7.3. If 'wan' interface doesn't exists add it otherwise modify it to be: config interface 'wan' option device 'eth1' option proto 'dhcp' 7.4 Restart OpenWrt network. /etc/init.d/network restart At this point OpenWrt GUI should be available via the IP address chosen in step 7.2. If OpenWrt GUI is not available via browser, restart the VM. If the GUI is still not accessible, start troubleshooting. 8. Install Wi-Fi firmware for your network device and Wi-Fi software layer. 8.1 Find what Wi-Fi card is used in your network device. For example, the PCIe Wi-Fi card - ASUS PCE-AC55BT uses Intel AC8260 Wi-Fi adapter. 8.2 In OpenWrt GUI go to System -> Software. 8.3 Update package list and make sure OpenWrt has access to the internet. 8.4 Find and install iwlwifi-firmware for your network device. For example, iwlwifi-firmware-iwl8260c for Intel AC8260. Refer to OpenWrt for the list of supported firmware. 8.5 Install the wpa-supplicant package. 8.6 Install the kmod-iwlwifi package. It’s recommended to install kmod-iwlwifi via the command line. In Unraid open VM’s Console (VMC) and execute the following commands: opkg update opkg install kmod-iwlwifi At this point the passthrough Wi-Fi card should be available in OpenWrt GUI. Make sure radio0 is available in Network -> Wireless. If radio0 is not available, start troubleshooting. 9. Follow OpenWRT guide to configure OpenWrt Wi-Fi Extender/Repeater. Note that in the guide it’s recommended to use a different subnet for LAN interface configuration, try using the same subnet if using a different subnet causes problems. 10. Make Unraid GUI accessible. In OpenWrt GUI go to Network -> Firewall -> General Settings. Change Input, Output and Forward settings to "accept". At this point Unraid should have internet access and be available via Wi-Fi, if it’s not, start troubleshooting. 11. Optional. Make OpenWRT VM autostart after Unraid reboot, power loss or crash. In Unraid go to VMs -> Left mouse click on OpenWrt VM -> Edit -> Toggle autostart. Note that VM autostart only works after first boot to prevent a crash boot loop. That means that disk stats must be cleared after each reboot. 11.1 Clear disk stats. In Unraid go to Main -> Array Operation -> Clear Stats. 12. Make sure Unraid works as expected before moving the server to its permanent location.