Networking

This page covers how the iOS Backup Machine connects to a network. WiFi is handled by the OS stack (netplan, systemd-networkd, wpa_supplicant), the device roams between the networks you save, and it prefers the iPhone USB hotspot while the phone is plugged in. Network access is optional: backups run fully offline, but a connection enables NTP sync, notifications, remote sync, and remote access.

WiFi stack

WiFi is managed through the OS’s existing netplan, systemd-networkd, and wpa_supplicant stack. The device has no NetworkManager. The iw and wireless-tools packages read the connected SSID, and iptables is used by the WireGuard full-tunnel routing exception.

When you save networks in the web UI, the appliance writes a managed netplan drop-in at /etc/netplan/90-iosbackup-wifi.yaml and applies it. The OS’s own netplan files are left untouched.

Note

Only the 90-iosbackup-wifi.yaml drop-in is owned by the appliance. Your base OS network configuration is never rewritten.

Multiple networks and roaming

You can configure several networks, each with an optional nickname. wpa_supplicant associates to whichever configured network is in range, so the device roams automatically as you move between them.

Networks are stored in config.yaml under wifi.networks:

wifi:
  enabled: false
  ssid: ""
  password: ""
  networks:
    - nickname: "Home"
      ssid: "HomeNetwork"
      password: "secret"
    - nickname: "Office"
      ssid: "CorpWiFi"
      password: "another-secret"

The legacy single ssid and password fields are the older single-network form. They are migrated into networks[0] automatically and kept mirrored for back-compat, so an existing single-network config keeps working.

iPhone-hotspot preference

The WiFi route is given a higher metric than the iPhone USB tether’s route. As a result, the iPhone hotspot is used when the phone is plugged in, and WiFi takes over automatically when the phone is unplugged. The WiFi connection is no longer dropped as the iPhone connects or disconnects.

This handover changes which addresses the device answers on, which matters if you have restricted webui.bind_interfaces to specific interfaces rather than all. The web UI re-checks the selection every 20 seconds and binds and unbinds as addresses appear and disappear, so a handover mid-sync does not strand it. See Web UI.

Scan and connect

The WiFi settings page has a Scan & connect button. It forces a rescan and connects to any saved network in range. Use it when the device is not associated to a network you expect to be reachable.

Status sources

The connected SSID and its nickname are shown in three places: the dashboard, the e-ink info screen (single-tap system info), and GET /api/status. These values are read via iw, iwgetid, and wpa_cli.

The /api/health and /api/status responses expose the active interface and WiFi details, for example:

"network": {
  "active_ip": "192.168.1.50",
  "interface": "wifi",
  "wifi_ssid": "HomeNetwork",
  "wifi_nickname": "Home",
  "internet": true
}

NTP time sync

When ntp.enabled is true, the appliance auto-syncs its clock whenever internet is available, over either WiFi or the USB iPhone hotspot. A correct clock matters beyond timestamps: the WireGuard peer rejects handshakes when the clock is not yet NTP-synced.

ntp:
  enabled: true
  servers:
    - "pool.ntp.org"
    - "time.google.com"

ntp-sync.service runs once at boot, which can easily land before any network is up. ntp-sync.timer covers that: it first fires two minutes into the boot and then retries every 15 minutes. The retry is cheap in the steady state, because ntp-sync.py exits early once timedatectl reports NTPSynchronized=yes. The installer both enables and starts the timer, so a fresh or changed timer does not wait for the next boot to begin running.

The clock also gates the quiet-device alert. A board with a dead RTC cell and no network boots reading 1970, so the alert refuses to write its first record until the clock reads at least 2026, and it ignores the first 15 minutes of a boot entirely. Anchoring the record to a 1970 clock would make the next check compute an age of decades and alert on a healthy device.

Related

• WireGuard VPN covers the VPN client and its WiFi and boot auto-connect triggers
• Remote sync covers restricting rsync to WiFi only, a specific SSID, or iPhone USB tethering