Skip to content

Ethernet and Wi-Fi

Keep local console access available before changing the connection you use to manage the appliance. Sign in as an administrator, open System → Settings → Network, select an interface and choose Configure. Review DHCP or static IPv4 settings; for Wi-Fi, select or enter the network name and credentials. After applying, verify connectivity and choose Keep this network configuration within three minutes. Without confirmation the worker restores the old settings.

On a new installation using Ubuntu's default network backend, Magic Stick prepares unconfigured physical Ethernet ports for IPv4 DHCP. You can install over Wi-Fi and plug in Ethernet later without editing the port settings. The port does not delay boot while unplugged. It needs an available DHCP server, and its new route does not take priority over the connection already used for setup. Explicit DHCP, static or disabled configurations and existing appliances are not changed. Getting a second IP does not migrate Kubernetes' management address.

Configuration forms

Ethernet configuration form with automatic DHCP, route metric and optional DNS servers.

Unchanged Ethernet form, 24 September 2026. With DHCP selected, leaving DNS empty uses the automatically supplied values. Interface identifiers and addresses are outside the crop; no network change was submitted.

Wi-Fi configuration draft with empty SSID and password fields, WPA personal, hidden network, DHCP and route metric.

Unsubmitted Wi-Fi draft on the same test appliance, 24 September 2026. WPA personal was selected only to show its fields. No SSID or password was entered; the draft was cancelled without scanning, enabling the radio or connecting.

Supported configuration

The dashboard provides System → Settings → Network for administrators.

  1. Discover physical Ethernet/Wi-Fi interfaces through the host worker; show link state, addresses, gateway, MAC and current IPv4 settings.
  2. Edit DHCP or one static IPv4 address/prefix, gateway, DNS and route metric. Wi-Fi adds an explicit scan, manual/hidden SSID and open or WPA personal authentication. Lower metrics are preferred: Ethernet defaults to 100 and Wi-Fi to 600. IPv6 is displayed and preserved, not edited.
  3. Validate in API and root worker; bind requests to Node UID, boot and current configuration fingerprint, and require exact-host confirmation.
  4. Apply on trial with a supervised local service. Require Keep this network configuration within three minutes, otherwise restore the previous files.
  5. Verify authorization, credentials and rollback in isolated tests. Physical link changes require separate acceptance with local console access.

There is no second network manager, automatic Wi-Fi switching or privileged dashboard Pod. The current Netplan backend is retained. An explicit iw scan does not replace the connection but can briefly use radio airtime. Scanning requires an enabled Wi-Fi interface; it never enables a disabled radio as a side effect. Manual SSID entry remains available without a scan.

Address assignment and service reachability are separate. On an existing installation, both interfaces can have addresses even when the Kubernetes API and HTTPS gateway still depend on the interface that was active at startup. The managed single-node candidate gives that internal traffic a fixed reserved address, and announces the unchanged .local name with the physical IPv4 address on each active link. SSO origins, certificates, configured DHCP/static settings and interface priorities stay unchanged. mDNS remains link-local; it does not bridge VLANs or networks that block multicast.

The built-in installer selects this profile for new managed single-node installations only after the source includes the matching discovery and Dashboard API image pins. It does not silently migrate existing installations.

On an upgraded managed appliance, use a planned maintenance window with the models stopped, no active regression or host operation, and an independent local console. The local maintenance action checks the running image digests and restarts Kubernetes without editing Ethernet or Wi-Fi settings. It verifies the internal API, replacement load-balancer pods, and the trusted sign-in entry point. A failure during the change attempts to restore the previous path and verifies that restoration. A power cut or unfinished recovery leaves a local journal and blocks further host changes until reviewed.

An administrator runs the following on the qualified revision:

sudo python3 /usr/local/lib/magicstick/k3s/control_plane_maintenance.py apply NODE_UID

Replace NODE_UID with the independently verified node identity. Check the normal hostname, HTTPS and sign-in on both individual links, then run the same command with confirm in place of apply. Until confirmation, run it with recover from the independent console to restore the recorded configuration. Do not remove a pending journal or try to migrate the protected address from the Network form. Selecting software that lacks the matching network support is not a substitute for a planned return to the previous network.

User flow and limitations

Select Configure, review settings and type the exact host name. WPA personal accepts 8–63 printable ASCII characters or a 64-digit hexadecimal key. An empty password retains the saved key only for the same SSID. The selected SSID replaces that interface's access-point list. Enterprise Wi-Fi, bridges, bonds, VLANs, wildcard matching, multiple static IPv4 addresses and custom IPv4 routes require local administration.

The interface carrying Kubernetes' InternalIP cannot migrate to another static address or Wi-Fi network here. DHCP can be retained or converted to the same static address. Control-plane migration also affects K3s advertisement, certificates and kubeconfigs. Interfaces are never silently disabled to prefer another connection.

The browser never automatically confirms a successful API request. Verify the link before selecting Keep this network configuration. If disconnected, wait for rollback rather than resubmitting. Confirmation requires IPv4 on the chosen interface and preserved management addresses; it does not test Internet, DNS, VPN or application routing.

Safety and persistence

  • HostOperation adds scan-wifi and configure-network; its spec stays immutable. The API patches only confirmation metadata, never execution status or Nodes. Concurrent host operations cannot replace one another.
  • Credentials travel through immutable, per-request Secrets in the separate host-management namespace. The dashboard has no Secret list/update rights there and gains no Secret access in ai-system. The worker consumes Secrets; expired orphan requests are removed after ten minutes when it is available. Kubernetes Secrets are not inherently encrypted at rest. Protect cluster administration and enable storage encryption where required.
  • Status uses a field allowlist: no password or raw Netplan document is returned. Command output is excluded from API errors. SSIDs/IPs are inventory, not secrets.
  • A root-only approved request starts magicstick-network-apply.service. It shares the maintenance lock with Ansible/host actions, snapshots /etc/netplan/*.yaml, then writes consolidated /etc/netplan/90-magicstick-network.yaml with mode 0600. Other interfaces, matching rules and IPv6 remain intact. Inspection never rewrites saved settings.
  • Generation is checked before application. The local deadline works without API/browser connectivity. ExecStopPost restores unconfirmed trials on service failure. magicstick-network-recovery.service restores files and regenerates backend configuration before network services start after an interrupted boot.
  • Apply and recovery let the network backend read its generated profiles. The saved Netplan YAML, Wi-Fi credentials and worker state stay private.
  • Confirmation removes credential-bearing backups. Recovery state remains until restoration succeeds. Concurrent externally created files stop recovery rather than being deleted. Rollback cannot guarantee recovery from failed hardware, changed access points or external edits. Retain local console access.

Do not rely solely on netplan try, which documents rollback caveats: see the Netplan try manual and configuration examples.

Operations and acceptance

sudo systemctl status magicstick-network-apply.service
sudo journalctl -u magicstick-network-apply -u magicstick-network-recovery
kubectl -n ai-system get hostoperations

Never publish Netplan files, request Secrets or local approved/rollback JSON; they can contain passwords. Do not delete active requests to bypass recovery. Progress: Applying → AwaitingConfirmation → Succeeded. RolledBack confirms restored files, not external reachability. Failed/interrupted recovery needs local review.

For physical acceptance, retain an independent console; check Ethernet DHCP and static IPv4, scan/connect Wi-Fi, let a trial expire, and verify rollback with the browser/API unavailable and after a restart during a trial. These disruptive checks never run merely from opening the page or publishing source. Unit tests use temporary files and fake host commands; they do not prove driver behavior. For the link-independent candidate additionally check a fresh boot, both interfaces, Ethernet-only, Wi-Fi-only and reconnect after a changed lease. Verify the ordinary .local name, a trusted HTTPS response, normal SSO, and continued readiness of the control plane and installed workloads on each path. Packet and virtual-machine tests complement these checks but do not establish physical appliance acceptance.