Lib.rs

› Operating systems
#zfs #freebsd #os #zol #open3

libzetta

libzetta is a stable interface for programmatic administration of ZFS

by Andrey Snow and 7 contributors

13 unstable releases (4 breaking)

0.5.0 May 13, 2023
0.4.3 May 12, 2023
0.4.2 Apr 1, 2023
0.3.1 Apr 17, 2022
0.1.2 Aug 12, 2019

#93 in Operating systems

Download history 20/week @ 2023-02-04 25/week @ 2023-02-11 43/week @ 2023-02-18 7/week @ 2023-02-25 11/week @ 2023-03-04 26/week @ 2023-03-11 13/week @ 2023-03-18 6/week @ 2023-03-25 74/week @ 2023-04-01 19/week @ 2023-04-08 21/week @ 2023-04-15 27/week @ 2023-04-22 26/week @ 2023-04-29 63/week @ 2023-05-06 93/week @ 2023-05-13 41/week @ 2023-05-20

223 downloads per month
Used in symo

BSD-2-Clause

260KB
5.5K SLoC

Build Status codecov Crates.io Cirrus CI - Base Branch Build Status docs.rs license

libzetta-rs is a stable interface for programmatic administration of ZFS

Installation

Not yet. It won't break your pool or kill your brother, but API might change. Wait until 1.0.0. I have a pretty decent roadmap to 1.0.0.

Usage

Public API for zpool stable. Public API for zfs might change after I actually get to use it in other projects. Consult the documention on usage.

FreeBSD

This library focused on FreeBSD support. This should work on any FreeBSD version since 9.2. No intention on supporting legacy versions. Supported versions:

  • 12.1
  • 13.0 (No CI setup for it)

NOTE: FreeBSD 13.0 borked libzfs_core dependencies. Until it's fixed solution is to use LD_PRELOAD to load libzfs_core from ports. NOTE: Since FreeBSD switched to OpenZFS, support for "legacy" will be dropped at first breakage.

Linux

Verified on what is avaiable for Ubuntu 20.04 at the time of writting it's 0.8.3.

How it works

ZFS doesn't have stable API at all.libzfs_core(lzc) fills some gaps, but not entirely. While lzc provides stable APi to some features of zfs, there is no such thing for zpool. This library resorts to zfs(8) and zpool(8) where lzc falls shorts.

Running tests

Vagrantfile has 3 VMS: ubuntu-20.04, FreeBSD 12 and FreeBSD 13 to use them:

  • Spin up either one of those
  • Install just
  • Run just test-ubuntu or just test-freebsd12 to run tests in the VM
  • To run a specific test run just test-ubuntu "-- easy_snapshot_and_bookmark"

NOTE: Integration tests must be run as a root. Zpools and datasets will be created/modified/destroyed. If it wipes your system datasets that's on you for running it outside of VM.

Nix

Project is nix-flake enabled, but it flake itself isn't enough: you need to provide libzfs_core and its dependencies yourself. This is on-purpose.

Current feature status

zpool

Create Destroy Get Properties Set Properties Scrub Export Import List Available Read Status Add vdev Replace Disk
open3 ✔ ✔ ✔ ✔ ✔ ✔ ✔ ✔ ✔¹ ✔ ✔
  1. Reads the status, but api isn't stable and does poor job at reporting scrubbing status.

zfs

Filesystem and ZVOL

Create Destroy List Get Properties Update Properties
open3 ❌ ❌ ✔ ✔ ❌
lzc ✔¹ ✔ ❌ ❌ ❌
  1. Might not have all properties available.

Snapshot and bookmark

Create Destroy List Get Properties Send Recv
open3 ❌ ❌ ✔ ✔ ❌ ❌
lzc ✔¹ ✔ ❌ ❌ ✔ ❌
  1. Might not have all properties available.

Alternatives

https://github.com/whamcloud/rust-libzfs

Unlike them LibZetta doesn't link against private libraries of ZFS. libzetta also has more documention.

https://github.com/jmesmon/rust-libzfs

LibZetta has zpool APIs. LibZetta shares -sys crates with this library. LibZetta also will delegate certain features of zfs(8) to open3 implementation.

LICENSE

BSD-2-Clause.

Dependencies

~7MB
~149K SLoC