iPhone USB Tethering on Fedora

README.md

iPhone USB Tethering Setup for Fedora

How it works

iPhone USB tethering uses the ipheth kernel module to create a virtual ethernet interface. The usbmuxd daemon handles the initial USB multiplexing protocol but is not involved in the tethering data path itself — tethering uses a dedicated USB interface as a virtual network device.

usbmuxd is started automatically by udev rules when an iPhone is plugged in (/usr/lib/udev/rules.d/39-usbmuxd.rules). The service unit is intentionally "static" (no [Install] section), so systemctl enable usbmuxd is not needed and will produce a warning — this is expected behavior.

Step 1: Install the required packages

sudo dnf install -y libimobiledevice-utils usbmuxd

The usbmuxd package creates a usbmuxd system user and installs the udev rules that auto-start the daemon when an Apple device is connected.

Step 2: Connect your iPhone via USB-C and pair it

Unlock your iPhone and connect it via USB-C. You should see a "Trust This Computer?" prompt on the iPhone — tap Trust and enter your passcode. Accept the corresponding trust prompt on your laptop as well. This completes pairing automatically.

To verify the pairing succeeded:

idevicepair validate

You should see SUCCESS: Validated pairing with device <UDID>.

Pairing records persist in /var/lib/lockdown/ — you only need to do this once per device.

Step 3: Enable Personal Hotspot on the iPhone

On your iPhone, go to Settings > Personal Hotspot and turn it ON.

The ipheth kernel module will auto-load and create an ethernet interface (typically named ethN or enpXsYuZ). NetworkManager will detect it and configure it via DHCP.

Step 4: Verify the connection

# Check that the network interface appeared
ip link show | grep eth

# Check NetworkManager sees the wired connection
nmcli device status

# Verify internet connectivity
ping -c3 8.8.8.8

Troubleshooting

systemctl enable usbmuxd warns about the unit file

This is expected. The usbmuxd service is "static" — it is started by udev when an Apple device is detected, not by systemd's enable/disable mechanism. You do not need to enable it.

No network interface appears after connecting

1. Check the iPhone is detected: lsusb | grep Apple
2. Check usbmuxd started: systemctl status usbmuxd
3. Check the ipheth module loaded: lsmod | grep ipheth
4. Manually load it if needed: sudo modprobe ipheth
5. Check kernel messages: sudo dmesg | grep -i ipheth
6. Make sure Personal Hotspot is turned ON on the iPhone

Pairing fails

• Make sure the iPhone is unlocked when you run idevicepair pair
• Check usbmuxd is running: systemctl status usbmuxd
• Check permissions on /var/lib/lockdown/: ls -la /var/lib/lockdown/ (should be owned by usbmuxd:usbmuxd)

idevicepair pair says "No devices found"

The phone may be detected by USB but failing the lockdownd SSL handshake. Run these diagnostics in order:

1. Confirm the phone is visible on USB:

   lsusb | grep Apple
   

   You should see a line like Apple, Inc. iPhone .... If not, try a different cable or port.

2. Check usbmuxd logs for lockdown errors:

   systemctl status usbmuxd
   

   Look for lockdown error -8 — this means usbmuxd connected to the device but the SSL/TLS pairing handshake failed (typically a stale pairing record).

3. Remove the stale pairing record:

   ls /var/lib/lockdown/
   sudo rm /var/lib/lockdown/<UDID>.plist
   

   Replace <UDID> with the device serial shown in the usbmuxd logs.

4. Restart usbmuxd:

   sudo systemctl restart usbmuxd
   

5. Unplug and replug the iPhone. Tap "Trust" when prompted and enter your passcode.

6. Pair again:

   idevicepair pair
   

idevicepair pair returns "unhandled error code -5"

If pair returns error -5 but the device was already trusted (you tapped "Trust" on the phone and the pairing record exists in /var/lib/lockdown/), the device is likely already paired. Verify with:

idevicepair validate

If validate returns SUCCESS, the pairing is fine — pair returns -5 because the device is already paired and rejects a redundant pairing request. You can safely proceed to enabling Personal Hotspot.