FreeBSD USB Tethering Operations: Bring Up and Diagnose Phone Links

USB tethering turns a phone’s cellular connection into a network interface on FreeBSD. It is useful for temporary connectivity or a backup path, but the host-side setup depends on the phone’s USB protocol, the loaded driver, device trust and tethering settings, DHCP, route selection, and cellular availability.

Treat this as an interface bring-up procedure, not a guarantee that every phone or carrier behaves the same way. Do not assume the interface will always be named ue0, that the cellular connection has public reachability, or that a new default route should replace an existing one.

Identify the phone protocol and prepare the host

FreeBSD’s Handbook documents three common driver families: Android devices generally use urndis(4), Apple devices use ipheth(4), and older devices may use cdce(4). These are general patterns, not a complete compatibility matrix. Phone model, OS version, USB mode, and cable can all affect enumeration.

Before plugging in, save the existing routing and interface state:

ifconfig -a
netstat -rn
sysctl net.inet.ip.forwarding
dmesg | tail -100

On a personal workstation, IP forwarding normally does not need to be enabled just to use the phone’s connection locally. If the FreeBSD host is acting as a router for other machines, forwarding and NAT become a separate network design with firewall implications; do not enable them as part of basic tethering.

Enable USB tethering on the phone and use a known data-capable cable. Some devices require an unlock, trust confirmation, or a selected USB connection mode. If the device is managed, confirm policy before enabling tethering. A charging-only cable can power the phone without exposing a data interface.

Load only the likely driver

For a supported phone, load its matching driver module:

kldload if_urndis

For an Apple device, use:

kldload if_ipheth

For a device identified as CDC Ethernet, use:

kldload if_cdce

Do not load all three as a guessing ritual. Start with the documented protocol for the device and examine kernel output. Confirm the module and USB device:

kldstat
usbconfig list
dmesg | tail -100
ifconfig -a

The network interface name is assigned by enumeration and may differ. The Handbook gives ue0 as an example, but use the actual interface reported by ifconfig. Disconnecting and reconnecting devices can change unit numbers on some systems.

If tethering is used regularly, the Handbook documents loader.conf settings such as if_urndis_load=“YES”. Add only the appropriate module to /boot/loader.conf, then verify after a reboot. Module availability and whether a driver is built into a custom kernel can vary; inspect the installed kernel and do not add redundant assumptions.

Request an address and inspect routes

Once the interface exists, inspect it before requesting DHCP:

ifconfig ue0
dhclient ue0
ifconfig ue0
netstat -rn

Replace ue0 with the interface actually created. If the interface already has an address or another network manager is controlling it, do not start a second DHCP client blindly. Confirm that DHCP completed and inspect the lease and route changes.

A successful DHCP lease proves only that the phone assigned local configuration. Test the gateway and then a known destination using the site’s approved diagnostic policy. DNS may be configured separately by DHCP; inspect resolvers and query a hostname rather than assuming that raw IP connectivity implies DNS works.

If the host has Ethernet, Wi-Fi, VPN, or jail routes already, the new interface may not become the preferred default route. This is not necessarily a tethering failure. Compare route metrics and policy before changing them. Do not use a global default-route replacement on a remotely managed host without console or alternate access.

For a short-lived connection, a manual DHCP session is easier to reason about than persistent configuration. If the interface name is stable and the host should use tethering at boot, an rc.conf entry such as ifconfig_ue0=“DHCP” can be appropriate. Validate it against the actual interface name and test restart and disconnect behavior; avoid hard-coding ue0 if enumeration is not stable.

Diagnose by layer

If no network interface appears, check the phone’s tethering toggle, USB data mode, cable, port, module load, and kernel messages. Use usbconfig list to determine whether the USB bus sees the phone at all. If the device is absent from USB enumeration, changing IP configuration will not help.

If the USB device appears but no interface is created, compare the driver messages with the expected protocol and inspect whether the relevant module loaded successfully. Replug only after confirming the host is not using the interface. A different phone mode or OS update may change the exposed USB function.

Some Apple devices expose several USB configurations and may not select the Ethernet configuration automatically. The ipheth(4) manual documents how to inspect descriptors and select the correct configuration with usbconfig; some setups also require usbmuxd. Follow that device-specific procedure using the configuration shown by the phone rather than copying a numeric configuration index from another model.

If the interface exists but has no address, inspect dhclient output and the phone’s tethering state. Check that no stale address or lease from a previous connection remains. Do not assign a guessed static address unless the device’s documented setup requires it and you know its subnet.

If an address exists but traffic fails, inspect the route table, interface status, gateway, DNS resolver, packet filters, and carrier connectivity. Run narrow, reversible tests. A firewall can block host traffic independently of the USB device, and a VPN can divert traffic into a route that does not work over the tether. Avoid disabling the firewall wholesale as a diagnostic step.

If throughput is poor, collect repeated samples rather than one speed test. Phone signal, carrier policy, USB generation, cable quality, power management, and host routing can all affect results. Compare a wired device-level link indication only if the driver exposes one; do not translate cellular signal strength into a guaranteed FreeBSD interface rate.

Make the configuration reproducible

Keep a record of the phone model and OS version, USB protocol, driver module, interface name, DHCP result, route selection, DNS source, and test destination. This makes future driver regressions easier to distinguish from cellular outages.

If the interface must be loaded at boot, use the loader setting documented for the driver, then reboot during a maintenance window and verify the kernel module, interface, lease, and routes. If the device is not attached during boot, an interface-level DHCP entry may fail or delay service startup depending on rc behavior. Consider devd(8) or a manual bring-up procedure when hot-plug is the normal workflow.

Disconnect cleanly. Stop any DHCP client if the setup requires it, verify that the host route falls back to its intended primary path, and inspect the route table. Some phones disable tethering when unplugged or locked; test those transitions rather than relying on a single successful connect.

Basic tethering gives the FreeBSD host an upstream interface. It does not automatically share the phone connection with jails, VMs, or LAN clients. Sharing requires deliberate forwarding, routing, firewall/NAT rules, and policy controls. It also introduces a different security boundary and can expose internal clients to a metered or unstable link.

For a temporary field connection, keep the scope to the host and document any firewall or resolver changes. If sharing is required, design it as a separate router configuration, monitor client routes, and define how traffic is cut off when the phone disappears.

Acceptance and rollback

The connection is ready when the expected USB driver attaches, the intended interface has a valid address, route selection is understood, DNS and application reachability tests pass, and the primary network path remains recoverable. Capture before-and-after route tables.

Rollback means stopping the client on that interface if necessary, removing temporary routing changes, unloading a module only when it is unused, and verifying that the original interface and resolver configuration still work. Do not remove persistent settings until checking whether other devices depend on them.

Related:

Sources: