client mode added (#888)

* client mode added * Prevent OTA daemons dmclient and upgrade from running and phoning home to Verizon * Fix workflow * WIFI changes to support moxee. May need to rebase as delivering refactoring under other PR. * code changes for rust based wifi client mode docs next * Doc changes & security fixes * Added watchdog and recover if crash occurs for wifi. * Remove changes which were from device UI work (seperate feature which snuck into this branch) * Add missing wifi and firewall module declarations * cleaning up the code a bit * Gate wpa_suplicant in installer and workflow to avoid building binary every push * fix to check diskspace * Improved support for subnet colisions, and attempts to rejoin network. * Add WiFi client support and S01iptables to T-Mobile and Wingtech installers Both installers now deploy wpa_supplicant, wpa_cli, udhcpc-hook.sh, and the S01iptables boot-time firewall script. Config generation uses the shared install_config/install_wifi_creds helpers instead of manual string replacement. * Revert "Add WiFi client support and S01iptables to T-Mobile and Wingtech installers" This reverts commit 944b369c4f. * Fix build: ignore unused wifi_ssid/wifi_password fields in T-Mobile and Wingtech installers * Moved to a wifi crate * Add host route and arp_filter to prevent subnet collisions * add wakelock so kernel doesn't shut down wifi on battery when wifi is enabled * Move wifi to external wifi-station crate, remove wifi from installer, extract OTA blocking * fixed outdated info, moved udhcpc hook to wifi-station crate. * Update to new version of wifi-station * Address PR review feedback: replace Docker wpa build, add iw, remove OTA, revert unrelated changes - Replace Docker-based wpa_supplicant build with shell script (scripts/build-wpa-supplicant.sh) - Add iw cross-compilation and deployment to Orbic installer - Skip wifi tool install if binary already exists on device - Remove OTA daemon blocker (extracted for separate PR) - Revert unrelated UZ801 and T-Mobile installer changes - Remove connection.rs test scaffolding - Rewrite S01iptables init script to read config.toml directly - Pin url crate to 2.5.4 to fix MSRV * Fix build script: use bash for parameter substitution The ${VAR//pattern/replacement} syntax is a bash extension that doesn't work in dash (Ubuntu's /bin/sh). * Fix iw build: export PKG_CONFIG_LIBDIR as env var Passing PKG_CONFIG_LIBDIR as a make variable doesn't export it to $(shell pkg-config ...) calls. Set it as an environment variable so pkg-config finds the cross-compiled libnl. * Point wifi-station to GitHub rev 97c579a * add comment * Update daemon/src/config.rs Add decorators Co-authored-by: Andrej Walilko <walilkoa@gmail.com> * Update daemon/src/server.rs add utopia doc support Co-authored-by: Andrej Walilko <walilkoa@gmail.com> * Update daemon/src/server.rs add utopia doc support Co-authored-by: Andrej Walilko <walilkoa@gmail.com> * Update to wifi-station with utoipa doc strings * add utoipa to wifi-station * added WPA3 support * fix firewall port detection, update wifi-station to c267d37 fix ntfy port_or_known_default, comment out ntfy_url in config template, update wifi-station with resolv.conf bind mount fallback, udhcpc_bin config, and module path fix for UZ801 * show wifi UI for tmobile and wingtech, add udhcpc_bin config both devices have wifi hardware and backend support. wingtech verified on hardware (QCA6174 via PCIe). uz801 excluded for now due to driver scan limitations with hostapd active. * install wifi tools from orbic-usb installer, fix DNS default to Quad9, bump wifi-station rev * fix Modal scroll listener leak, correct file transfer timeout math, document firewall fail-open, clarify UZ801 wifi status * build-dev.sh: build wifi tools so install-dev works for orbic-family devices * update Cargo.lock for wifi-station e8ec5b4 * fix setup_timeout_server crypto provider install, apply rustfmt * Update installer/src/connection.rs Co-authored-by: Cooper Quintin <cooperq@users.noreply.github.com> * Update installer/src/orbic.rs Co-authored-by: Cooper Quintin <cooperq@users.noreply.github.com> * apply rustfmt to AdbConnection::run_command --------- Co-authored-by: Andrej Walilko <walilkoa@gmail.com> Co-authored-by: Cooper Quintin <cooperq@users.noreply.github.com>
2026-07-23 15:58:10 -07:00 · 2026-04-22 10:02:48 -07:00
parent 416f03159a
commit 3455adbf95
32 changed files with 982 additions and 26 deletions
@@ -21,4 +21,38 @@ Through web UI you can set:
  - *Low Battery*, which will alert when the device's battery is low. Notifications may not be supported for all devices—you can check if your device is supported by looking at whether the battery level indicator is functioning on the System Information section of the Rayhunter UI.
 - With **Analyzer Heuristic Settings** you can switch on or off built-in [Rayhunter heuristics](heuristics.md). Some heuristics are experimental or can trigger a lot of false positive warnings in some networks (our tests have shown that some heuristics have different behavior in US or European networks). In that case you can decide whether you would like to have the heuristics that trigger a lot of false positives on or off. Please note that we are constantly improving and adding new heuristics, so a new release may reduce false positives in existing heuristics as well.

+## WiFi Client Mode
+
+On the **Orbic**, **Moxee**, **UZ801**, **TMOHS1**, and **Wingtech**, Rayhunter can connect the device to an existing WiFi network while keeping the hotspot running. This gives the device internet access for [notifications](https://docs.ntfy.sh/) and lets you reach the web UI from any device on that network.
+
+- **Enable WiFi** turns WiFi client mode on or off. Disabling it does not erase saved credentials.
+- **Scan** searches for nearby networks. Select one from the dropdown, or type an SSID manually.
+- **Password** is required for WPA/WPA2 networks. The password is stored separately from `config.toml` (in `wpa_sta.conf` on the device) and is never exposed through the API.
+- **DNS Servers** lets you override the DNS servers used when connected. Defaults to `9.9.9.9` and `149.112.112.112` (Quad9) if not set.
+
+After saving, the connection status will show **connecting**, **connected** (with the assigned IP address), or **failed** (with an error message). If the connection fails, check that the SSID and password are correct and that the network is in range.
+
+### Crash Recovery
+
+The WiFi kernel module (`wlan.ko`) can occasionally crash or unload, taking both the hotspot and client interfaces down with it. Rayhunter includes a watchdog that detects this and automatically reloads the module, restarts the hotspot, and reconnects to the configured network. During recovery the WiFi status will show **recovering**.
+
+On the first detection of a crash, a diagnostic snapshot is saved to `/data/rayhunter/crash-logs/` on the device. You can pull these logs with `adb pull /data/rayhunter/crash-logs/` and inspect them to understand what went wrong. Each log contains:
+
+- **dmesg** output (kernel messages). Look for backtraces, `BUG:`/`Oops:` lines, or `wlan`/`wcnss` errors. The kernel ring buffer is small and gets overwritten quickly, so crash details may already be gone if the crash happened well before detection.
+- **/proc/modules** snapshot. If `wlan` is absent, the module fully unloaded. If present but interfaces are gone, the driver is stuck.
+- **ip addr** output confirming which network interfaces existed at snapshot time.
+- **ps** output showing which WiFi-related processes (`hostapd`, `wpa_supplicant`, `wland`) were still running.
+
+If recovery fails after 5 attempts, the status will change to **failed**. A reboot of the device will reset WiFi.
+
+You can also configure WiFi during installation:
+
+```sh
+./installer orbic --admin-password 'mypassword' --wifi-ssid 'MyNetwork' --wifi-password 'networkpass'
+```
+
+## Device Security
+
+- **Restrict outbound traffic** limits what the device can send over the network. When enabled, only DNS, DHCP, and HTTPS traffic is allowed; everything else is blocked. This is enabled by default and prevents the device from phoning home to the carrier over cellular. If you need to allow additional ports (for example, port 80 for HTTP or port 22 for SSH), add them to the **Additional allowed ports** list.
+
 If you prefer editing `config.toml` file, you need to obtain a shell on your [Orbic](./orbic.md#obtaining-a-shell) or [TP-Link](./tplink-m7350.md#obtaining-a-shell) device and edit the file manually. You can view the [default configuration file on GitHub](https://github.com/EFForg/rayhunter/blob/main/dist/config.toml.in).
@@ -50,6 +50,14 @@ reboot
 See `/data/usb/boot_hsusb_composition` for a list of USB modes and Android USB gadget settings.


+### How do I connect my device to an existing WiFi network?
+
+The Orbic, Moxee, UZ801, and TMOHS1 can connect to a nearby WiFi network while still running their own hotspot. This gives the device internet access for ntfy notifications and lets you reach the web UI from your home network. See [WiFi Client Mode](./configuration.md#wifi-client-mode) in the configuration guide for setup instructions.
+
+### WiFi client mode is connected but I can't reach the internet
+
+Check that the **DNS Servers** field in the config has valid entries (the default is `9.9.9.9` and `149.112.112.112`). If your home network and the device hotspot use the same subnet (for example, both are on `192.168.1.x`), try restarting the daemon by saving the config again from the web UI.
+
 ### How do I disable the WiFi hotspot on the Orbic RC400L?

 To disable both WiFi bands, [first obtain a shell](./orbic.md#shell), then:
@@ -44,6 +44,9 @@ Make sure you've got one of Rayhunter's [supported devices](./supported-devices.
   # Note: the arguments --admin-username 'myusername' and --admin-ip 'mydeviceip'
   #       may be required if different from the default.

+   # Optionally configure WiFi client mode during install (Orbic and Moxee only):
+   ./installer orbic --admin-password 'mypassword' --wifi-ssid 'MyNetwork' --wifi-password 'networkpass'
+
   # Or install over USB if you want ADB and a root shell (not recommended for most users)
   ./installer orbic-usb

@@ -22,6 +22,10 @@ pay more than 30 USD for such a device (without shipping).
 | Wifi 5Ghz | a/ac/ax |
 | Wifi 6 | 🮱 |

+## WiFi client mode
+
+The Orbic's QCA6174 radio supports running the hotspot and connecting to an external WiFi network at the same time. See [WiFi Client Mode](./configuration.md#wifi-client-mode) for setup.
+
 ## Two kinds of installers

 The orbic's installation routine underwent many different changes:
@@ -36,6 +36,10 @@ According to FCC ID 2APXW-TMOHS1 Test Report No. I20Z61602-WMD02 ([part 1](https
 |   66 | 1700 MHz (E-AWS) |
 |   71 | 600 MHz (USDD)   |

+## WiFi client mode
+
+The TMOHS1 supports WiFi client mode, allowing Rayhunter to connect to an existing WiFi network while keeping the hotspot running. See [WiFi Client Mode](./configuration.md#wifi-client-mode) for setup.
+
 ## Installing
 Connect to the TMOHS1's network over WiFi or USB tethering.

@@ -19,6 +19,8 @@ You can access this UI in one of two ways:
  On the **Orbic**, you can find the WiFi network password by going to the Orbic's menu > 2.4 GHz WIFI Info > Enter > find the 8-character password next to the lock 🔒 icon.
  On the **TP-Link**, you can find the WiFi network password by going to the TP-Link's menu > Advanced > Wireless > Basic Settings.

+  If [WiFi client mode](./configuration.md#wifi-client-mode) is enabled, you can also reach the web UI from any device on that network at `http://<device-ip>:8080`.
+
 * **Connect over USB (Orbic):** Connect your device to your laptop via USB. Run `adb forward tcp:8080 tcp:8080`, then visit <http://localhost:8080>.
    * For this you will need to install the Android Debug Bridge (ADB) on your computer, you can copy the version that was downloaded inside the `releases/platform-tools/` folder to somewhere else in your path or you can install it manually.
    * You can find instructions for doing so on your platform [here](https://www.xda-developers.com/install-adb-windows-macos-linux/#how-to-set-up-adb-on-your-computer), (don't worry about instructions for installing it on a phone/device yet).
@@ -36,6 +36,12 @@ With the device fully booted (i.e. beaming a WiFi network, blue LED, etc.) and p

 Note: The default IP for UZ801 is typically `192.168.100.1`; if yours differs, use the `--admin-ip` argument to specify it.

+## WiFi client mode
+
+The UZ801's WCN36xx (PRONTO) radio supports concurrent AP+STA mode. The daemon has backend support for WiFi client mode on the UZ801, but this has not yet been successfully exercised end-to-end and the web UI currently does not expose the configuration surface on this device. Treat UZ801 WiFi client mode as not yet supported. See [WiFi Client Mode](./configuration.md#wifi-client-mode) for the intended setup on supported devices.
+
+The interface creation method differs from the Orbic (which uses `iw`): the UZ801 creates a P2P_CLIENT virtual interface via nl80211 and converts it to a managed STATION interface. This is handled by the daemon when the feature is enabled.
+
 ## LED modes
 | Rayhunter state  | LED indicator       |
 | ---------------- | ------------------- |
@@ -28,6 +28,10 @@ Wingtechs are abundant on ebay and can also be found on Amazon:
 - <https://www.ebay.com/itm/127147132518>
 - <https://www.amazon.com/AT-Turbo-Hotspot-256-Black/dp/B09YWLXVWT>

+## WiFi client mode
+
+The Wingtech supports WiFi client mode, allowing Rayhunter to connect to an existing WiFi network while keeping the hotspot running. See [WiFi Client Mode](./configuration.md#wifi-client-mode) for setup.
+
 ## Installing
 Connect to the Wingtech's network over WiFi or USB tethering, then run the installer: