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: the CLI is the only interface OpenZFS actually stabilises, it needs no C toolchain or kernel-matched headers, and azfsbinary over SSH works exactly like a local one. - 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 |
| Pools | list / status (vdev tree, scan state) / create / destroy / import / export / discover / 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
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.
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.