Add MIT license and public README
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
parent
b420072cba
commit
98dea3dca6
2 changed files with 103 additions and 51 deletions
21
LICENSE
Normal file
21
LICENSE
Normal file
|
|
@ -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.
|
||||
133
README.md
133
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)
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue