Skip to content

alan-sun-dev/iPhone-USB-Gateway

BranchesTags

Repository files navigation

iPhone USB Gateway v11.0 - Production Grade

Transform your Raspberry Pi into a robust network gateway using iPhone USB tethering.

🎯 What's New in v11.0

✅ Major Improvements

  1. NFT Rollback Mechanism 🛡️

    • Automatic backup before applying new rules
    • Automatic rollback on failure
    • Keeps last 5 backups for troubleshooting
    • Never leaves your LAN broken

  2. Atomic Status Writes ⚛️

    • No more torn reads in Web UI
    • Thread-safe status file updates
    • Prevents race conditions between timer and udev

  3. Enhanced Validation ✓

    • Empty rules detection
    • Input parameter validation (IP, CIDR, ports)
    • Interface existence checks
    • Configuration file support

  4. File Locking 🔒

    • Prevents concurrent script execution
    • Uses flock for reliable locking
    • Clean lock release on exit

  5. Better Error Messages 💬

    • Actionable troubleshooting hints
    • Detailed status notes in Web UI
    • Comprehensive logging

  6. Dry-Run Mode 🧪

    • Test configuration without changes
    • Validate settings before deployment

📋 Architecture

┌─────────────┐
│   iPhone    │ USB Cable
│  (Hotspot)  │────────┐
└─────────────┘        │
                       ▼
              ┌─────────────────┐
              │  Raspberry Pi   │
              │                 │
              │  WAN: usb0/eth1 │ ← Auto-detected
              │  LAN: eth0      │ ← 192.168.88.1/24
              │                 │
              │  [NAT/Firewall] │
              │  [DHCP Server]  │
              │  [Web UI:8080]  │
              └─────────────────┘
                       │
        ┌──────────────┼──────────────┐
        ▼              ▼              ▼
    ┌──────┐      ┌──────┐      ┌──────┐
    │ PC 1 │      │ PC 2 │      │ ...  │
    └──────┘      └──────┘      └──────┘
     .50-.200      DHCP           LAN Clients

🚀 Quick Start

Prerequisites

  • Raspberry Pi (3/4/5 or Zero 2 W)
  • Raspberry Pi OS (Debian/Ubuntu-based)
  • iPhone with Personal Hotspot enabled
  • USB cable (Lightning or USB-C)
  • Root access (sudo)

Installation

# Download the installer
wget https://example.com/iphone-gw-install-v11.sh
chmod +x iphone-gw-install-v11.sh

# Run installation (default config)
sudo ./iphone-gw-install-v11.sh

# Or with custom configuration
sudo cp iphone-gw.conf.example /etc/iphone-gw.conf
sudo nano /etc/iphone-gw.conf
sudo ./iphone-gw-install-v11.sh --config /etc/iphone-gw.conf

First Connection

  1. Connect iPhone via USB
  2. Trust Computer (tap "Trust" on iPhone)
  3. Enable Personal Hotspot (Settings → Personal Hotspot)
  4. Check Status 
    cat /run/iphone-gw.status
  5. Open Web UI: http://192.168.88.1:8080/

📊 Monitoring & Management

Web Dashboard

  • URL: http://192.168.88.1:8080/
  • Features:
    • Real-time WAN/LAN status
    • Link state (operstate, carrier)
    • Traffic statistics (RX/TX)
    • Service health indicators
    • Auto-refresh every 5 seconds

JSON API

# Get full status in JSON
curl http://192.168.88.1:8080/api/status | jq

# Example output:
{
  "wan_interface": "usb0",
  "wan_ip": "172.20.10.2",
  "wan_ready": true,
  "wan_operstate": "up",
  "wan_carrier": "1",
  "rx_bytes": 1234567890,
  "tx_bytes": 987654321,
  "services": {
    "dnsmasq": true,
    "nftables": true,
    "gateway": true
  }
}

Prometheus Metrics

# Scrape metrics (for Grafana/Prometheus)
curl http://192.168.88.1:8080/metrics

# Example metrics:
iphone_gw_uptime_seconds 3600
iphone_gw_wan_link_ready 1
iphone_gw_wan_rx_bytes{iface="usb0"} 1234567890
iphone_gw_wan_tx_bytes{iface="usb0"} 987654321
iphone_gw_service_active{service="dnsmasq"} 1

Log Files

# Traffic log (updated every 60s)
tail -f /var/log/iphone-gw.log

# System logs
journalctl -u iphone-gw -f
journalctl -u iphone-gw-web -f

# View backups
ls -lh /var/backups/iphone-gw/

🔧 Systemd Services

Main Services

Service Description Status
iphone-gw.service Gateway activation systemctl status iphone-gw
iphone-gw.timer Health check (60s) systemctl status iphone-gw.timer
iphone-gw-web.service Web UI server systemctl status iphone-gw-web
iphone-gw-log.timer Traffic logger (60s) systemctl status iphone-gw-log.timer

Manual Operations

# Restart gateway (redetect WAN)
sudo systemctl restart iphone-gw

# Restart Web UI
sudo systemctl restart iphone-gw-web

# Stop all services
sudo systemctl stop iphone-gw iphone-gw.timer iphone-gw-web iphone-gw-log.timer

# Disable on boot
sudo systemctl disable iphone-gw iphone-gw.timer

🛠️ Troubleshooting

iPhone Not Detected

Symptoms: No WAN interface found

Solutions:

  1. Check USB cable connection
  2. Trust computer on iPhone (Settings → General → Reset → Reset Network Settings if needed)
  3. Check USB drivers: 
    lsusb | grep -i apple
dmesg | grep -i usb
ip link show
  4. Manually trigger detection: 
    sudo systemctl restart iphone-gw

WAN Link Not Ready

Symptoms: operstate != up or carrier != 1

Solutions:

  1. Enable Personal Hotspot on iPhone
  2. Check iPhone has cellular/WiFi connection
  3. Replug USB cable
  4. View detailed status: 
    cat /run/iphone-gw.status
cat /sys/class/net/usb0/operstate
cat /sys/class/net/usb0/carrier

NFT Rules Failed

Symptoms: "ERROR: nft apply failed"

Check:

# View status
cat /run/iphone-gw.status

# Check if rollback occurred
ls -lt /var/backups/iphone-gw/

# Manually validate rules
sudo nft -f /etc/nftables.d/iphone-gw.nft

# Check generated rules
cat /etc/nftables.d/iphone-gw.nft

Recovery:

# Restore from backup
sudo nft flush ruleset
sudo nft -f /var/backups/iphone-gw/nft.backup.TIMESTAMP.nft

# Regenerate rules
sudo /usr/local/sbin/iphone-gw-up

No Internet on LAN Clients

Checklist:

  1. Verify IP forwarding: 
    cat /proc/sys/net/ipv4/ip_forward  # Should be 1
  2. Check NAT rules: 
    sudo nft list table ip iphone_gw_nat
  3. Test from Pi itself: 
    ping -I usb0 8.8.8.8
  4. Check client DHCP: 
    sudo systemctl status dnsmasq
sudo journalctl -u dnsmasq -n 50

Web UI Not Accessible

Solutions:

# Check service
sudo systemctl status iphone-gw-web

# Check port binding
sudo ss -tlnp | grep 8080

# Check firewall (should allow from LAN)
sudo nft list table inet iphone_gw_input

# Restart Web UI
sudo systemctl restart iphone-gw-web

🔒 Security Considerations

Firewall Rules

  • Only LAN (eth0) can access Web UI
  • Only LAN can forward through gateway
  • WAN interface is protected

Hardening (Optional)

# Add basic auth to Web UI (requires modification)
# See: https://example.com/docs/web-ui-auth

# Restrict DHCP to specific MAC addresses
sudo nano /etc/dnsmasq.d/iphone-gw.conf
# Add: dhcp-host=AA:BB:CC:DD:EE:FF,192.168.88.10

# Change default LAN network
sudo nano /etc/iphone-gw.conf
# Modify: LAN_CIDR="10.10.10.1/24"
sudo ./iphone-gw-install-v11.sh --config /etc/iphone-gw.conf

📚 Advanced Configuration

Custom Network Range

# Edit config
sudo nano /etc/iphone-gw.conf

# Change to:
LAN_CIDR="10.0.0.1/24"
LAN_IP="10.0.0.1"
LAN_NET="10.0.0.0/24"
DHCP_RANGE_START="10.0.0.100"
DHCP_RANGE_END="10.0.0.200"

# Reinstall
sudo ./iphone-gw-install-v11.sh --config /etc/iphone-gw.conf

Multiple WAN Interfaces

For failover or load balancing, you'll need to modify the scripts:

# Future feature: Coming in v12.0
# Will support automatic failover between:
# - iPhone USB (primary)
# - USB 4G modem (secondary)
# - Ethernet WAN (tertiary)

Static DHCP Reservations

sudo nano /etc/dnsmasq.d/iphone-gw.conf

# Add reservations:
dhcp-host=aa:bb:cc:dd:ee:ff,192.168.88.10,laptop
dhcp-host=11:22:33:44:55:66,192.168.88.20,desktop

sudo systemctl restart dnsmasq

📦 Backup & Restore

Backup Configuration

# Backup everything
sudo tar czf iphone-gw-backup.tar.gz \
  /etc/iphone-gw.conf \
  /etc/dnsmasq.d/iphone-gw.conf \
  /etc/nftables.d/iphone-gw.nft \
  /etc/systemd/system/iphone-gw* \
  /usr/local/sbin/iphone-gw* \
  /var/backups/iphone-gw/

Restore Configuration

# Extract backup
sudo tar xzf iphone-gw-backup.tar.gz -C /

# Reload systemd
sudo systemctl daemon-reload

# Restart services
sudo systemctl restart iphone-gw iphone-gw-web

🔄 Uninstallation

# Stop and disable services
sudo systemctl stop iphone-gw iphone-gw.timer iphone-gw-web iphone-gw-log.timer
sudo systemctl disable iphone-gw iphone-gw.timer iphone-gw-web iphone-gw-log.timer

# Remove systemd units
sudo rm /etc/systemd/system/iphone-gw*

# Remove scripts
sudo rm /usr/local/sbin/iphone-gw*

# Remove configs
sudo rm /etc/nftables.d/iphone-gw.nft
sudo rm /etc/dnsmasq.d/iphone-gw.conf
sudo rm /etc/udev/rules.d/99-iphone-tether.rules

# Remove sysctl
sudo rm /etc/sysctl.d/99-iphone-gw.conf

# Reload
sudo systemctl daemon-reload
sudo udevadm control --reload-rules
sudo sysctl -p

📝 Changelog

v11.0 (2024-02-03)

  • ✅ NFT rollback mechanism with automatic recovery
  • ✅ Atomic status file writes (no torn reads)
  • ✅ Empty rules validation
  • ✅ File locking (flock) for concurrency safety
  • ✅ Input validation for all config parameters
  • ✅ Backup rotation (keep last 5)
  • ✅ Enhanced error messages with troubleshooting hints
  • ✅ Dry-run mode for testing
  • ✅ Configuration file support
  • ✅ Improved Web UI with better styling
  • ✅ Comprehensive documentation

v10.1 (Previous)

  • Removed 'enp' from WAN regex
  • Enhanced idempotency checks
  • Explicit NAT table verification

🤝 Contributing

Found a bug? Have a feature request?

  1. Check /var/log/iphone-gw.log
  2. Check journalctl -u iphone-gw -n 100
  3. Report with full logs and cat /run/iphone-gw.status

📄 License

MIT License - Feel free to modify and distribute

🙏 Acknowledgments

  • Built with best practices from production systems
  • Inspired by community feedback and real-world usage
  • Special thanks to all contributors

Made with ❤️ for Raspberry Pi + iPhone users

About

Transform your Raspberry Pi into a robust network gateway using iPhone USB tethering.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages