From 98dea3dca64d91823803f12ea6fa049f1c07d811 Mon Sep 17 00:00:00 2001 From: 28allday Date: Fri, 3 Jul 2026 20:15:10 +0100 Subject: [PATCH] Add MIT license and public README Co-Authored-By: Claude Fable 5 --- LICENSE | 21 +++++++++ README.md | 133 +++++++++++++++++++++++++++++++++--------------------- 2 files changed, 103 insertions(+), 51 deletions(-) create mode 100644 LICENSE diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..5acd172 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Gavin Nugent + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md index c2dee0f..d0c4512 100644 --- a/README.md +++ b/README.md @@ -1,53 +1,66 @@ # omatether -iPhone USB tethering for **Omarchy / Arch** (systemd-networkd + iwd stack), -with a gum TUI. Plug an iPhone in over USB and use its internet connection — -the phone's Wi-Fi if it's on one, cellular otherwise. Works headless too. +**Use your iPhone's internet on Omarchy / Arch over a USB cable.** -## TUI +Plug the phone in, tap Trust once, and its connection — the phone's Wi-Fi if +it's on one, cellular otherwise — becomes a network interface on your machine. +After setup it's zero-touch: plug in and the connection comes up by itself, +sitting quietly as a fallback until you need it (or flip a switch to route +everything through the phone). Works headless over SSH too. -Run `omatether.sh` with no arguments (or launch **iPhone Tether** from Walker — -it opens as a small floating window). The dashboard shows phone / tether / route -state live and offers only the actions that make sense right now: - -``` -╭───────────────────────╮ -│ OMATETHER │ -│ iPhone USB internet │ -╰───────────────────────╯ - Cowboy Bebop — paired -󰛳 Tether up: eth0 172.20.10.11/28 -󰈀 Internet via enp6s0 (phone is fallback) - -> Switch internet → iPhone - Status (full check) - Refresh - Quit -``` - -- **Connect phone** — waits for USB, walks you through unlock + Trust, brings - the connection up (shown only when not yet connected) -- **Switch internet → iPhone** — routes all traffic via the phone -- **Switch back → ethernet/wifi** — back to normal (tether stays as fallback) - -## How it works - -- `usbmuxd` handles the iOS pairing/trust handshake (udev-activated, no service to enable) -- the kernel's `ipheth` driver exposes the phone as a normal network interface -- a `systemd-networkd` profile (`10-iphone-tether.network`) matches by - `Driver=ipheth` and DHCPs it, at **fallback priority** (route metric 750) - so it never hijacks ethernet (100) or Wi-Fi (600); "Switch → iPhone" - rewrites the metric to 50 and reloads networkd +Built for the Omarchy network stack (systemd-networkd + iwd). No GUI +dependencies beyond [gum](https://github.com/charmbracelet/gum) for the TUI, +which the installer pulls in. ## Install ```bash -./omatether.sh install # packages + networkd profile + Walker launcher -./omatether.sh # TUI: pick "Connect phone", unlock, tap Trust +git clone https://github.com/28allday/omatether.git +cd omatether +./omatether.sh install ``` -Then on the phone: **Settings → Personal Hotspot → Allow Others to Join: ON**. -After that it's zero-touch — plug in and the connection comes up by itself. +The installer: + +- installs `usbmuxd` + `libimobiledevice` (pacman; usbmuxd is udev-activated, + nothing to enable) +- writes a systemd-networkd profile for the phone's interface +- adds an **iPhone Tether** entry to Walker that opens the TUI in a small + centered floating window (Hyprland windowrule, marker-delimited in + `~/.config/hypr/windows.conf`, cleanly removed on uninstall) + +Then plug the phone in and run `./omatether.sh` — pick **Connect phone**, +unlock the phone, tap **Trust**. On the phone make sure +**Settings → Personal Hotspot → Allow Others to Join** is on. + +## The TUI + +Run with no arguments (or launch **iPhone Tether** from Walker). The dashboard +shows phone / tether / route state live and only offers actions that make +sense right now: + +``` + ╭───────────────────────╮ + │ OMATETHER │ + │ iPhone USB internet │ + ╰───────────────────────╯ + Cowboy Bebop — paired + 󰛳 Tether up: eth0 172.20.10.11/28 + 󰈀 Internet via enp6s0 (phone is fallback) + + What do you want to do? + > Switch internet → iPhone + Status (full check) + Refresh + Quit +``` + +- **Connect phone** — waits for USB, walks you through unlock + Trust, brings + the connection up and live-tests it +- **Switch internet → iPhone** — routes *all* traffic via the phone, even + with ethernet plugged in +- **Switch back → ethernet/wifi** — normal routing; the tether stays + connected as a fallback ## CLI @@ -55,18 +68,36 @@ Everything is scriptable without the TUI: | Command | What it does | |---|---| -| `install` | Install packages, networkd profile, Walker launcher | +| `install` | Packages, networkd profile, Walker launcher + windowrule | | `pair` / `unpair` | Manage the Trust pairing | -| `status` | Device, interface, IP, route, live connectivity test | -| `priority high` | Route all traffic via the phone even when ethernet is up | +| `status` | Device, pairing, interface, IP, route, live connectivity test | +| `priority high` | Route all traffic via the phone (survives reinstall) | | `priority low` | Back to fallback-only (default) | -| `uninstall` | Remove the networkd profile + launcher | +| `uninstall` | Remove the profile, launcher and windowrule | -## Notes +## How it works -- iOS shares whatever uplink it has: on Wi-Fi it shares the Wi-Fi; otherwise cellular. -- The tether interface usually appears as `eth0`; the profile matches by driver, not name. -- `RequiredForOnline=no` — an unplugged phone never blocks boot. -- DNS follows the Omarchy convention (`UseDNS=no`; global resolvers via systemd-resolved). -- If the phone was plugged in before usbmuxd existed it can show as unresponsive — - the tool restarts usbmuxd automatically to rescan. +- the kernel's `ipheth` driver exposes the phone as a normal network + interface as soon as iOS trusts the machine (`usbmuxd` handles that + handshake) +- a networkd profile matches the interface **by driver** (`Driver=ipheth`, + not by name — it usually appears as `eth0`) and DHCPs it at route metric + **750**, so it never hijacks ethernet (100) or Wi-Fi (600); `priority high` + rewrites the metric to 50 +- `RequiredForOnline=no` — an unplugged phone never blocks boot +- DNS needs no wiring: Omarchy resolves via global resolvers in + systemd-resolved + +## Troubleshooting + +- **Phone shows "not responding"** — usbmuxd lost it (typically when the + phone was plugged in before usbmuxd was installed). The tool restarts + usbmuxd automatically during Connect; manually: `sudo systemctl restart usbmuxd`. +- **Interface up but no IP** — Personal Hotspot's *Allow Others to Join* is + off on the phone. +- **Pairing fails with a passcode error** — the phone is locked; unlock it + and retry. + +## License + +[MIT](LICENSE)