Session roaming: how Qeli moves a session

The session is separate from its physical connection

Since Qeli 0.8.0, session roaming preserves one logical VPN session when the physical path changes: Wi-Fi gives way to cellular, the outer address changes, NAT rebinding occurs, or another A/AAAA endpoint becomes usable. The new carrier is validated inside the existing authenticated contract, so the server does not allocate a second lease or create another user session.

Prepare → validate → commit

1. The platform adapter observes a network change and prepares an exact candidate path: temporary host route, kill-switch rules and a separate socket bound to the intended interface.
2. The shared core binds the candidate to the current generation/epoch and validates it with authenticated control. Wrong CID, token, direction or stale epoch is rejected.
3. The old path stays active until validation completes. After commit, the new carrier becomes current and temporary candidate state moves to the normal session owner.
4. An error before commit rolls back only the candidate. An ambiguous result past the commit point terminates the generation and performs a clean reconnect instead of leaving a live-looking black hole.

The same mechanism can move an outer IPv4 path to IPv6 and back when endpoint, listener and platform support both. The inner TUN family is independent from the outer carrier family.

roaming = off | auto | required

Enablement and resource bounds

roaming.enabled = true
roaming.grace_secs = 30
roaming.max_orphaned = 256
roaming.max_orphan_bytes = 67108864

# client.conf · [qeli]
roaming = auto

New installer profiles enable bounded roaming. Replacing the binary does not rewrite an existing server.conf: add the keys explicitly, run qeli check-config, then restart the profile.

Transports, platforms and routes

• Ordinary TCP: plain, fake-tls, obfs, reality and reality-tls.
• UDP camouflage: udp-fake-tls, udp-quic, udp-obfs and obfs-awg through one state machine.
• Android and iOS report physical network changes; Windows, macOS and Linux use the same fail-closed candidate/commit result. An old native core means reconnect in auto.
• Explicit exclude rules and carrier host routes retain priority, preventing the endpoint from being routed into its own tunnel.
• Startup and live PMTU use an authenticated 128-bit challenge; a new network can establish a different safe packet size.

Mobile recovery follows actual network availability

• Android and iOS do not spend reconnect backoff while no usable Wi-Fi or cellular carrier exists. They resume immediately when connectivity returns.
• Android preserves the fail-closed TUN across native-core restarts when NetworkPlan is unchanged. Manual Disconnect remains authoritative.
• iOS avoids reapplying identical NetworkExtension settings and transfers only the bounded queue of uplink packets not yet accepted by the previous core generation.
• TCP multipath uses stable logical slot IDs: losing or restoring one bonded carrier does not remap healthy flows.
• Android retains up to 1,000 recent events, capped at 512 KiB, in private no-backup storage. Clear removes the history; secrets and the complete profile are never stored there.

Confirming that roaming actually committed

$ sudo qeli check-config --config /etc/qeli/server.conf
$ sudo journalctl -u qeli -f

1. Connect with roaming=auto, start continuous ping and a long transfer.
2. Switch Wi-Fi to cellular or change the usable uplink without disconnecting the profile.
3. Verify that the inner lease/TUN was not recreated. Panel/statistics attempts and commits should rise, and candidate should return to zero.
4. If failures or reconnect fallbacks rise, check the server feature gate, native-core version, explicit local/lport, both carrier firewalls and PMTU.

0.8.1 contract and implementation