28allday
52c21e2467
Context-aware menu: Connect phone (USB wait + Trust walkthrough), Switch internet → iPhone / back, live status header. install now writes a TUI.float .desktop entry and restarts elephant. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
72 lines
2.8 KiB
Markdown
72 lines
2.8 KiB
Markdown
# 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.
|
|
|
|
## TUI
|
|
|
|
Run `omatether.sh` with no arguments (or launch **iPhone Tether** from Walker —
|
|
it opens as a 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
|
|
|
|
## Install
|
|
|
|
```bash
|
|
./omatether.sh install # packages + networkd profile + Walker launcher
|
|
./omatether.sh # TUI: pick "Connect phone", unlock, tap Trust
|
|
```
|
|
|
|
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.
|
|
|
|
## CLI
|
|
|
|
Everything is scriptable without the TUI:
|
|
|
|
| Command | What it does |
|
|
|---|---|
|
|
| `install` | Install packages, networkd profile, Walker launcher |
|
|
| `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 |
|
|
| `priority low` | Back to fallback-only (default) |
|
|
| `uninstall` | Remove the networkd profile + launcher |
|
|
|
|
## Notes
|
|
|
|
- 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.
|