DEV Community

vast cow
vast cow

Posted on

How to Use NetworkManager's Checkpoint Feature (nmcli device checkpoint)

#linux #networking #cli

nmcli device checkpoint is a feature that allows you to create a "restore point" for safely testing changes to your NetworkManager configuration.

It's very useful when making network configuration changes on a remote server (e.g., via SSH connection) because if a configuration error causes the connection to be lost, it will automatically revert to the previous state.

Basic Mechanism

Normally, when you change a network configuration:

Current configuration
      │
      ▼
Apply new configuration
      │
      ├── Success → Use it
      │
      └── Failure → Connection lost
Enter fullscreen mode Exit fullscreen mode

With Checkpoint, the flow is:

Create Checkpoint
      │
      ▼
Apply new configuration
      │
      ├── Success
      │      │
      │      ▼
      │  Discard Checkpoint
      │
      └── Failure
             │
             ▼
      Automatically roll back after timeout
Enter fullscreen mode Exit fullscreen mode

Basic Syntax 

nmcli device checkpoint create [DEVICE...] --timeout seconds
Enter fullscreen mode Exit fullscreen mode

Example:

nmcli device checkpoint create eth0 --timeout 60
Enter fullscreen mode Exit fullscreen mode

This means:

  • Save the state of eth0
  • Revert to the previous state if not confirmed within 60 seconds

Practical Example

For example, if you want to change the IP address:

nmcli device checkpoint create eth0 --timeout 60
Enter fullscreen mode Exit fullscreen mode

A checkpoint will be created.

Then, execute:

nmcli con modify eth0 \
    ipv4.addresses 192.168.1.50/24 \
    ipv4.gateway 192.168.1.1 \
    ipv4.method manual

nmcli con up eth0
Enter fullscreen mode Exit fullscreen mode

Even if the SSH connection is lost,

After 60 seconds
Enter fullscreen mode Exit fullscreen mode

NetworkManager will automatically revert to:

Original IP
Original Gateway
Original Route
Enter fullscreen mode Exit fullscreen mode

Confirm and Commit on Success

If the changes are successful and you can communicate, execute:

nmcli device checkpoint destroy <checkpoint-id>
Enter fullscreen mode Exit fullscreen mode

This will:

Delete the checkpoint
= Do not roll back
Enter fullscreen mode Exit fullscreen mode

Manually Roll Back

If you determine that the changes failed, execute:

nmcli device checkpoint rollback <checkpoint-id>
Enter fullscreen mode Exit fullscreen mode

to immediately revert to the previous state.

Checkpoint List

You can check the current checkpoints with:

nmcli device checkpoint show
Enter fullscreen mode Exit fullscreen mode

Example:

ID   CREATED              TIMEOUT
3    2025-01-01 10:00     60
Enter fullscreen mode Exit fullscreen mode

Multiple Devices are Possible

For example:

nmcli device checkpoint create eth0 bond0 br0 --timeout 120
Enter fullscreen mode Exit fullscreen mode

This will:

eth0
bond0
br0
Enter fullscreen mode Exit fullscreen mode

Save all of them together.

This is often used with bridge and bonding configurations.

Meaning of --timeout

For example:

--timeout 30
Enter fullscreen mode Exit fullscreen mode

means:

Create Checkpoint
        │
0 seconds │
10 seconds │ Apply changes
20 seconds │ Verify via SSH
30 seconds │ Automatically revert if destroy is not executed
Enter fullscreen mode Exit fullscreen mode

Typical Example in Remote Operation

When trying to change the IP address via SSH, the following procedure is safe:

nmcli device checkpoint create eth0 --timeout 120

nmcli con modify ...

nmcli con up ...

# Verify that the SSH connection is still active

nmcli device checkpoint destroy <id>
Enter fullscreen mode Exit fullscreen mode

If the connection is lost, it will automatically revert after 120 seconds, eliminating the need for on-site recovery work.

Notes

  • It only applies to devices managed by NetworkManager.
  • It can only roll back network state changes made by NetworkManager. Changes made outside of NetworkManager (e.g., settings added directly with the ip command) are not affected.
  • Automatic rollback after the timeout requires the NetworkManager service to continue running.

Summary

nmcli device checkpoint is a useful feature that can be thought of as a "safety net" for network configuration changes.

  • create: Saves the current network state
  • show: Displays the checkpoint list
  • destroy: Confirms the changes (does not roll back)
  • rollback: Immediately reverts to the saved state
  • --timeout: Automatically rolls back if destroy is not executed within the specified time

It is very useful as an insurance policy against connection loss due to configuration errors when changing IP addresses, routing, bridges, and VLANs via SSH.

NetworkManagerのチェックポイント機能（nmcli device checkpoint）の使い方

nmcli device checkpoint は、NetworkManager の設定変更を安全に試すための「復元ポイント（チェックポイント）」機能です。

リモートサーバー（SSH接続中など）でネットワーク設定を変更する際に、設定ミスで通信が切断されても、自動的に元の状態へ戻せるため非常に便利です。

基本的な仕組み

通常、ネットワーク設定を変更すると、

現在の設定
      │
      ▼
新しい設定を適用
      │
      ├──成功 → そのまま使う
      │
      └──失敗 → 通信断
Enter fullscreen mode Exit fullscreen mode

となります。

Checkpointを使うと、

Checkpoint作成
      │
      ▼
新しい設定を適用
      │
      ├──成功
      │      │
      │      ▼
      │  Checkpointを破棄
      │
      └──失敗
             │
             ▼
      タイムアウト後に自動ロールバック
Enter fullscreen mode Exit fullscreen mode

という流れになります。

基本構文 

nmcli device checkpoint create [DEVICE...] --timeout 秒
Enter fullscreen mode Exit fullscreen mode

例

nmcli device checkpoint create eth0 --timeout 60
Enter fullscreen mode Exit fullscreen mode

これは

  • eth0 の状態を保存
  • 60秒以内に確定しなければ元へ戻す

という意味です。

実際の利用例

例えばIPアドレスを変更したい場合

nmcli device checkpoint create eth0 --timeout 60
Enter fullscreen mode Exit fullscreen mode

Checkpointが作成されます。

続いて

nmcli con modify eth0 \
    ipv4.addresses 192.168.1.50/24 \
    ipv4.gateway 192.168.1.1 \
    ipv4.method manual

nmcli con up eth0
Enter fullscreen mode Exit fullscreen mode

を実行します。

もしSSHが切れてしまっても、

60秒後
Enter fullscreen mode Exit fullscreen mode

NetworkManager が自動で

元のIP
元のGateway
元のRoute
Enter fullscreen mode Exit fullscreen mode

へ戻します。

成功したら確定する

変更が成功し通信できることを確認したら

nmcli device checkpoint destroy <checkpoint-id>
Enter fullscreen mode Exit fullscreen mode

を実行します。

すると

チェックポイント削除
＝ロールバックしない
Enter fullscreen mode Exit fullscreen mode

となります。

手動でロールバック

途中で失敗したと判断したら

nmcli device checkpoint rollback <checkpoint-id>
Enter fullscreen mode Exit fullscreen mode

で即座に元へ戻せます。

チェックポイント一覧

現在のCheckpointは

nmcli device checkpoint show
Enter fullscreen mode Exit fullscreen mode

で確認できます。

例

ID   CREATED              TIMEOUT
3    2025-01-01 10:00     60
Enter fullscreen mode Exit fullscreen mode

複数デバイスも可能

例えば

nmcli device checkpoint create eth0 bond0 br0 --timeout 120
Enter fullscreen mode Exit fullscreen mode

のようにすると

eth0
bond0
br0
Enter fullscreen mode Exit fullscreen mode

すべてまとめて保存されます。

ブリッジやボンディング構成ではよく利用されます。

--timeout の意味

例えば

--timeout 30
Enter fullscreen mode Exit fullscreen mode

なら

Checkpoint作成
        │
0秒     │
10秒    │ 設定変更
20秒    │ SSH確認
30秒    │ destroyしなければ自動復元
Enter fullscreen mode Exit fullscreen mode

となります。

リモート運用での典型例

SSHで接続中にIP変更を試す場合は、次のような手順が安全です。

nmcli device checkpoint create eth0 --timeout 120

nmcli con modify ...

nmcli con up ...

# SSHが継続していることを確認

nmcli device checkpoint destroy <id>
Enter fullscreen mode Exit fullscreen mode

もし接続できなくなれば、120秒後に自動で元へ戻るため、現地での復旧作業が不要になることがあります。

注意点

  • NetworkManagerが管理しているデバイスのみが対象です。
  • ロールバックできるのは、NetworkManager が変更したネットワーク状態です。NetworkManagerの管理外で行った変更（例えば ip コマンドで直接追加した設定など）は対象外です。
  • タイムアウト後の自動復元は、NetworkManagerサービスが動作し続けていることが前提です。

まとめ

nmcli device checkpoint は、ネットワーク設定変更時の「セーフティネット」と考えると分かりやすい機能です。

  • create：現在のネットワーク状態を保存
  • show：チェックポイント一覧を表示
  • destroy：変更を確定（ロールバックしない）
  • rollback：即座に保存時点の状態へ戻す
  • --timeout：指定時間内に destroy されなければ自動でロールバック

SSH経由でIPアドレス、ルーティング、ブリッジ、VLANなどを変更する運用では、設定ミスによる通信断への保険として非常に有用です。

Top comments (0)