Remote Wi-Fi Reconfiguration with NetworkManager Checkpoints: Define Rollback Ownership

Before changing the Wi-Fi connection carrying a remote management session, create a finite rollback checkpoint in the local NetworkManager daemon. Confirm the new path only after testing it, then destroy that exact checkpoint. The safety mechanism must survive the management client’s disappearance; a timer inside the disconnected remote shell is the wrong owner.

This procedure targets NetworkManager 1.50.0 and its D-Bus checkpoint API. It concerns a running daemon and explicitly selected managed devices. It is not a crash-safe configuration transaction, a backup of every system file, or a guarantee that an unavailable AP can be restored. No network settings were changed for this article.

Define what the checkpoint actually covers

CheckpointCreate takes device paths, a rollback timeout in seconds and creation flags. An empty device list means all devices; a zero timeout means no automatic timeout. Those defaults can broaden scope or remove the intended safety deadline, so a remote-change controller should supply both deliberately. The returned object path identifies the checkpoint. NetworkManager 1.50.0, D-Bus introspection contract

Inventory every device affected by the proposed change: the Wi-Fi interface, a dependent bridge or VLAN, and any managed route-bearing interface whose configuration will change. Separately identify external switch settings, AP configuration, firewall rules and application files. Do not promise to restore those external resources through a NetworkManager checkpoint.

Creation flags are consequential policy choices. In 1.50.0, DELETE_NEW_CONNECTIONS deletes newly added connection profiles on rollback, while DISCONNECT_NEW_DEVICES disconnects devices that appeared after creation. These are broader than “undo my one new profile.” Global DNS changes made through D-Bus require the separate TRACK_INTERNAL_GLOBAL_DNS flag; configuration-file global DNS is outside that flag. Review the exact scope before enabling any of them. The 1.50.0 creation implementation rejects DISCONNECT_NEW_DEVICES with a nonempty device list: that flag requires all-device scope and cannot accompany this guide’s explicitly selected-device workflow. NetworkManager 1.50.0 checkpoint creation implementation NetworkManager 1.50.0, NMCheckpointCreateFlags

Give one local owner the confirmation decision

Use a controller that serializes changes and records an operation identity, the daemon instance, checkpoint path, affected devices, requested profile revision and deadline. A remote confirmation must refer to that exact operation. An old browser tab or retried request must not confirm a later change merely because the same interface name appears.

Avoid overlapping checkpoints unless the product intentionally implements their semantics. By default, overlapping devices make creation fail. The opt-in overlapping mode allows an older rollback to invalidate younger overlapping checkpoints. Likewise, creating with DESTROY_ALL can remove someone else’s protection. A busy result should lead to ownership reconciliation, not automatic destruction of unknown checkpoints. NetworkManager 1.50.0 checkpoint flags

Checkpoint objects and timers belong to the running daemon’s checkpoint manager. Treat daemon restart, reboot and loss of the local controller’s state as separate recovery cases, not as a promised continuation of this timer. Keep an approved out-of-band or on-site recovery method for failures that the checkpoint cannot repair. Use short maintenance windows: the implementation caps each scheduled timer interval at G_MAXUINT32 milliseconds, so the API’s unsigned seconds field is not an arbitrary full-range duration guarantee. NetworkManager 1.50.0 checkpoint timer implementation

Use a confirmation window with observable endpoints

1. Verify the rollback destination first. Record the current managed connection and prove the old AP and management service are reachable. Preserve necessary credentials through the product’s approved secret handling; never include them in the operation log.
2. Create and read back the checkpoint. Require successful creation before applying the disruptive change. Record its path, device scope and finite expiration. If creation is rejected or its outcome is uncertain, reconcile the daemon’s checkpoint list before proceeding.
3. Apply only the reviewed change. Bind the candidate revision to the operation. Prevent another management worker from changing the same devices while the confirmation window is open.
4. Reconnect through the intended path. Establish a fresh authenticated management exchange and verify the actual active profile, route and relevant DNS behavior. A still-open session using another interface is not proof that the new Wi-Fi path works.
5. Confirm before the local cutoff. The controller verifies the operation identity and current state, then destroys the exact checkpoint. Record the method outcome and read back state. Keep enough margin for control-path delays rather than treating the last displayed second as safe.
6. Otherwise allow or request rollback. A disconnected client need not send a final command for the armed timeout to act. An explicit rollback can be used earlier by the authorized owner, followed by device and service recovery checks.

CheckpointAdjustRollbackTimeout sets the expiration a specified number of seconds from now, not from creation or the previous expiration. Zero disables the timeout. If extension is an approved feature, bound the total maintenance window and record each extension. An automatic heartbeat that indefinitely extends a broken change defeats the rollback policy. The exported timeout property has approximately one-second precision. NetworkManager 1.50.0 timeout-adjustment contract

Do not confuse rollback initiation with restored access

The rollback method returns a per-device result dictionary. Inspect every entry rather than accepting a single generic success label. In the pinned implementation, restoration can initiate connection activation; the method result does not prove that association, addressing, DNS and the management service have all completed successfully. Observe those later boundaries separately. NetworkManager 1.50.0, nm_checkpoint_rollback() and restore_and_activate_connection()

A lost destroy response is also ambiguous. If the checkpoint is subsequently absent, it may have been destroyed by confirmation or consumed by rollback. Reconcile the active configuration and the local operation record before reporting committed or restored. Do not replay the change blindly. Likewise, the old AP disappearing during the window can make a correctly initiated rollback unable to recover service.

Exercise the races in an isolated qualification setup

Test a working candidate with timely confirmation, a wrong test credential with silence, a client process exit, a late confirmation, a lost confirmation response, a missing original AP and a daemon restart. Include a second concurrent change request and verify that it cannot steal the first operation’s checkpoint. Record the chosen rollback deadline, actual rollback initiation and eventual management recovery separately.

For a hypothetical deployment, a checkpoint starts at time zero with a 120-second window. An approved adjustment at 40 seconds requests 30 seconds from now, so expiration becomes 70 seconds, not 150 seconds. A confirmation arriving at 75 seconds must not be accepted as though the original window still applied. These are synthetic timeline values, not measured NetworkManager timing.

A Python 3.12.14 host policy model exercised this deadline arithmetic, silent expiry, timely confirmation, stale-operation rejection and refusal to confirm an expired operation. It did not call D-Bus, run NetworkManager or modify a network. Target qualification must establish actual timer handling, activation results and recovery.

The final release artifact is a bounded local rollback owner, an operation-specific confirmation protocol, a declared checkpoint scope and a tested recovery path. That is a defensible remote-change contract even when the management session itself vanishes.