103 lines
3.8 KiB
Markdown
103 lines
3.8 KiB
Markdown
# omatether
|
|
|
|
**Use your iPhone's internet on Omarchy / Arch over a USB cable.**
|
|
|
|
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.
|
|
|
|
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
|
|
git clone https://github.com/28allday/omatether.git
|
|
cd omatether
|
|
./omatether.sh install
|
|
```
|
|
|
|
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
|
|
|
|
Everything is scriptable without the TUI:
|
|
|
|
| Command | What it does |
|
|
|---|---|
|
|
| `install` | Packages, networkd profile, Walker launcher + windowrule |
|
|
| `pair` / `unpair` | Manage the Trust pairing |
|
|
| `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 profile, launcher and windowrule |
|
|
|
|
## How it works
|
|
|
|
- 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)
|