A New ZFS Boot Environment Management Library & Tool For FreeBSD

A Summer of Code 2017 Project

Project description

The purpose of this project is to build a convenient framework for managing ZFS boot environments. Currently, boot environments are managed manually or with scripts such as beadm, but both approaches are shell based. The approach that this project will take is to first create a boot environment library, libbe to offer simplified boot environment interaction in C to userspace applications (for example, TrueOS’ SysAdm), and then write an application that provides users with a command, be, that retains all of the features of beadm, and adds some functionality. Among the new features are the ability to recursively create boot environments containing child datasets, the ability to activate an environment for the next boot only, and the ability to attach/detach a boot environment to a jail.

Approach to solving the problem

This library will use the functions in the libzfs* libraries to incrementally add heatures to both libbe and be concurrently. For instance, once the list features are completed in libbe, they will be leveraged to complete the be list subcommand, ensuring that implementation is correct before moving onto a new feature. When relevent, behavior will be tested against beadm, with the goal that once complete, beadm can be aliased or replaced to be without any breakage or incompatibility.


The final deliverable is be, a command with a superset of beadm features (illustrated below in the usage), and the libbe library, that provides the features to the command and userspace ecosystem.

$ be -h
usage: be command args ...
where 'command' is one of the following:

    activate [-t] <bootenv>
    create [-r] [-e nonActiveBe | -e bootenv@snapshot] <bootenv>
    create beName@snapshot
    destroy [-F] <bootenv|bootenv@snapshot> [bootenv|bootenv@snapshot]*
    list [-a] [-D] [-H] [-s]
    rename <bootenv> <bootenv>
    mount <bootenv> [mountpoint]
    unmount|umount [-f] <bootenv>
    jail <jailid|jailname> <bootenv>
    unjail <jailid|jailname> <bootenv>

Each bootenv is a name of a dataset in (or to be created in) $POOLNAME/bootenv/


End of SoC time frame edit: See "Remaining Work" for fine grained list of tasks that aren't reflected by this schedule

The Code



Before being polished enough to consider submitting a patch, some work remains. The majority of this work is related to cleanliness, removing redundancies, and polishing error reporting, however a few technical points remain:

NewZfsBootEnvMgmtLibAndTool (last edited 2017-11-05 09:02:06 by KyleKneitinger)