Checkpoints

A checkpoint names a durable filesystem state that can later be opened read-only. Checkpoints are persistent: they remain until explicitly deleted.

Create a Checkpoint

Checkpoint commands use the admin RPC endpoint of a running read-write ZeroFS process. The configuration passed to the command must contain the same [servers.rpc] settings as that process:

[servers.rpc]
addresses = ["127.0.0.1:7000"]
unix_socket = "/tmp/zerofs.rpc.sock"

The configuration generated by zerofs init already enables the RPC server on loopback and a local Unix socket.

Create a checkpoint with a unique, non-empty name:

zerofs checkpoint create -c zerofs.toml before-migration

Before recording the checkpoint, ZeroFS seals and uploads the open data segment and flushes the metadata memtable. The checkpoint therefore refers only to data that passed the filesystem's durability barrier.

List and Inspect Checkpoints

zerofs checkpoint list -c zerofs.toml
zerofs checkpoint info -c zerofs.toml before-migration

Both commands contact the running RPC server. The output includes each checkpoint's name, internal UUID, and creation time.

Open a Checkpoint

Pass the checkpoint name when starting a server:

zerofs run -c snapshot.toml --checkpoint before-migration

A checkpoint server is always read-only. Mount or connect to one of the endpoints in snapshot.toml, then inspect or copy files through that endpoint.

If the read-write server is still running, give the checkpoint server its own NFS, 9P, NBD, Web UI, metrics, and RPC listeners. Reusing a configuration with the same addresses or Unix-socket paths causes listener conflicts. A copied configuration can point to the same storage backend after its listener settings have been changed.

There is no in-place restore command. To recover selected data, open the checkpoint and copy it to a writable filesystem. Keep the checkpoint until that copy has been verified.

Delete a Checkpoint

zerofs checkpoint delete -c zerofs.toml before-migration

Persistent checkpoints pin the storage objects needed to read their state. While any persistent checkpoint exists, segment deletion and segment compaction pause; metadata reclamation is pinned as well. Delete checkpoints that are no longer needed so garbage collection can resume reclaiming space.

Deleting a checkpoint removes the reference, not current filesystem data. A checkpoint server using that reference should be stopped before deletion.