zfskit drives the zfs(8) / zpool(8) command-line tools from async Rust.
It is the ZFS layer behind
arctern (a ZFS replication daemon)
and grew out of an Arch Linux ZFS installer — so both the replication
surface (send/recv, holds, bookmarks, resume tokens) and the provisioning
surface (pool create/import, dataset trees, encryption keys) are exercised
by real consumers.
Design
- CLI-only, no FFI. No
libzfs/libzfs_corebindings: using the command-line interface avoids an unstable library ABI, needs no C toolchain or kernel-matched headers, and supports the sameCommandRunnerAPI locally and over SSH. - JSON output, not tab-splitting. Structured
-joutput (OpenZFS ≥ 2.3) is parsed into serde models; version-tolerant where field sets drift between ZFS releases. - Async-only and cancellation-safe. Processes are spawned via
tokio::process; buffered commands are killed when their future is dropped, while typed send/receive processes expose explicitfinish()andcancel(). - Every operation is testable without ZFS.
Zfsaccepts a customCommandRunner;RealRunnerexecutes locally,SshCommandRunnerexecutes on a remote host, andRecordingRunnerreplays captured fixtures in unit tests. The runner remains available as an advanced escape hatch. - Errors are classified, not stringly:
ZfsErrordistinguishes dataset-not-found, snapshot-held, permission, busy-pool and friends by parsing stderr, so callers can branch on the failure mode.
What's covered
| Area | Operations |
|---|---|
| Datasets | list / get / set / create / destroy / mount / snapshot / rollback / clone / rename (datasets and snapshots) / promote |
| Pools | list / status (vdev tree, scan state) / create / destroy / import (name or GUID, properties, search sources, key loading) / export / discover (default, directories/devices, cachefile) / scrub (start·pause·resume·stop) / get / set |
| Replication | zfs send (raw/embedded/compressed/large-blocks, incremental from snapshot or bookmark, resume tokens) · zfs recv (-s/-u/-F, -o/-x property control) · dry-run size estimation · resume-token parsing and validation · recv -A partial-state abort |
| Protection | holds (idempotent hold/release, batch inspection) · bookmarks (GUID-anchored create/list/destroy) |
| Encryption | load-key / unload-key / property inspection / non-mutating passphrase verification |
| System | ARC statistics from /proc/spl/kstat/zfs/arcstats |
Example
use Zfs;
use ListOptions;
use DatasetType;
async
Snapshot clones and dataset moves use entity handles:
use Zfs;
use ;
async
Rename consumes the old handle and returns the new name. Other copies of the
handle, and handles for descendants or snapshots, must be reacquired after a
rename. Snapshot::rename(tag, &SnapshotRenameOptions) keeps snapshot recursion
separate from dataset rename. Dataset -p (create parents) and -u (keep existing
mounts) are mutually exclusive and rejected before execution.
Clones have the source dataset's type and must stay in the same pool. Clone
-p also succeeds when the destination already exists; it does not verify that
existing dataset's origin or apply the requested properties. There is no clone
-u flag: control mounting through properties such as mountpoint=none or
canmount=off. Promotion reverses the origin dependency and transfers ownership
of the origin snapshot and earlier snapshots; conflicting snapshot names must
be resolved by the caller.
Discovery and import share the same search-source model. Importing the returned pool uses its unsigned 64-bit GUID, so duplicate exported pool names are safe:
use Zfs;
use ;
async
PoolSearchSource::CacheFile(path) uses a saved configuration instead of device
search; the enum prevents mixing -c and -d. Discovery retains the original
DiscoveredPool.id string; guid() validates it as a u64 before import. The
low-level pool::import_by_guid accepts a u64 directly. Existing name-based
Pool::import and default discovery remain available. Search sources must be
passed to import again; they are not stored in discovery results.
ImportOptions::load_keys() passes -l for keys of datasets being mounted;
-l and -N are incompatible and rejected before execution. It supplies no passphrase or terminal handling.
Use the explicit dataset key-loading APIs to control input, particularly for
keylocation=prompt. -R sets both the alternate root and cachefile=none;
explicit import properties can override that cachefile setting.
Advanced import recovery is deliberately deferred: transaction rewind (-F,
-n, -X, -T), checkpoint rewind, missing-log import (-m), damaged-metadata
import, and destroyed-pool recovery need a separate explicit policy API.
Replication is the same primitives with the stream left to you:
use AsyncWriteExt;
use SendArgs;
use RecvArgs;
let zfs = new;
let mut src = zfs.send.await?;
let mut dst = zfs.receive.await?;
let mut stdout = src.take_stdout.expect;
let mut stdin = dst.take_stdin.expect;
copy.await?;
stdin.shutdown.await?;
drop;
src.finish.await?;
dst.finish.await?;
The SSH runner is intended for development and integration tests against a disposable remote ZFS host. Production applications should run zfskit on the ZFS host or provide a transport with explicit remote lifecycle guarantees:
use ;
// or SshCommandRunner::from_env() reading ZFSKIT_SSH_TARGET / ZFSKIT_SSH_PASSWORD
let runner = new;
let zfs = with_runner;
Testing
Unit tests replay captured JSON fixtures through RecordingRunner — they
never touch a real pool. The integration feature enables end-to-end tests
against a disposable ZFS host over SSH (ZFSKIT_SSH_TARGET=user@host:port);
the repo's justfile boots a QEMU VM for that. Run just vm-up, then
just test-integration, and finally just vm-down. With a VM already running,
all feature checks can be run with:
ZFSKIT_SSH_TARGET=root@localhost:2226 ZFSKIT_SSH_PASSWORD=''
The lifecycle integration tests cover clone properties/parents, dataset and snapshot rename, promotion origin reversal, captured error classification, export/discovery, GUID imports without mounting, readonly import, cachefile search, and file-based key loading. Each test uses an isolated sparse-file pool and the existing cleanup helper.
Requirements
- Rust 1.85 or newer (the crate uses the Rust 2024 edition).
- OpenZFS ≥ 2.3 (JSON output) on the host that runs the commands — local or at the far end of the SSH runner.
- Linux. The ARC-stats module reads
/proc/spl/kstat; everything else is CLI-portable in principle, but only Linux is tested.
License
Licensed under either of Apache License, Version 2.0 or MIT license at your option.