FreeBSD Manual Pages
LIBBE(3) Library Functions Manual LIBBE(3) NAME libbe -- library for creating, destroying and modifying ZFS boot envi- ronments LIBRARY library "libbe" SYNOPSIS #include <be.h> libbe_handle_t *hdl libbe_init(const char *be_root); void libbe_close(libbe_handle_t *hdl); const char * be_active_name(libbe_handle_t *hdl); const char * be_active_path(libbe_handle_t *hdl); const char * be_nextboot_name(libbe_handle_t *hdl); const char * be_nextboot_path(libbe_handle_t *hdl); const char * be_root_path(libbe_handle_t *hdl); int be_snapshot(libbe_handle_t *hdl, const char *be_name, const char *snap_name, bool recursive, char *result); bool be_is_auto_snapshot_name(libbe_handle_t *hdl, const char *snap); int be_create(libbe_handle_t *hdl, const char *be_name); int be_create_depth(libbe_handle_t *hdl, const char *be_name, const char *snap, int depth); int be_create_from_existing(libbe_handle_t *hdl, const char *be_name, const char *be_origin); int be_create_from_existing_snap(libbe_handle_t *hdl, const char *be_name, const char *snap); int be_rename(libbe_handle_t *hdl, const char *be_old, const char *be_new); int be_activate(libbe_handle_t *hdl, const char *be_name, bool temporary); int be_deactivate(libbe_handle_t *hdl, const char *be_name, bool temporary); int be_destroy(libbe_handle_t *hdl, const char *be_name, int options); void be_nicenum(uint64_t num, char *buf, size_t bufsz); int be_mount(libbe_handle_t *hdl, const char *be_name, const char *mntpoint, int flags, char *result); int be_mounted_at(libbe_handle_t *hdl, const char *path, nvlist_t *details); int be_unmount(libbe_handle_t *hdl, const char *be_name, int flags); int libbe_errno(libbe_handle_t *hdl); const char * libbe_error_description(libbe_handle_t *hdl); void libbe_print_on_error(libbe_handle_t *hdl, bool doprint); int be_root_concat(libbe_handle_t *hdl, const char *be_name, char *result); int be_validate_name(libbe_handle_t *hdl, const char *be_name); int be_validate_snap(libbe_handle_t *hdl, const char *snap); int be_exists(libbe_handle_t *hdl, const char *be_name); int be_export(libbe_handle_t *hdl, const char *be_name, int fd); int be_import(libbe_handle_t *hdl, const char *be_name, int fd); int be_prop_list_alloc(nvlist_t **prop_list); int be_get_bootenv_props(libbe_handle_t *hdl, nvlist_t *be_list); int be_get_dataset_props(libbe_handle_t *hdl, const char *ds_name, nvlist_t *props); int be_get_dataset_snapshots(libbe_handle_t *hdl, const char *ds_name, nvlist_t *snap_list); void be_prop_list_free(nvlist_t *prop_list); DESCRIPTION libbe interfaces with libzfs to provide a set of functions for various operations regarding ZFS boot environments, including "deep" boot envi- ronments in which a boot environment has child datasets. A context structure is passed to each function, allowing for a small amount of state to be retained, such as errors from previous opera- tions. libbe may be configured to print the corresponding error mes- sage to stderr when an error is encountered with libbe_print_on_error(). All functions returning an int return 0 on success, or a libbe errno otherwise as described in "DIAGNOSTICS". The libbe_init() function takes an optional BE root and initializes libbe, returning a libbe_handle_t * on success, or NULL on error. If a BE root is supplied, libbe will only operate out of that pool and BE root. An error may occur if: • /boot and / are not on the same filesystem and device, • libzfs fails to initialize, • The system has not been properly booted with a ZFS boot environ- ment, • libbe fails to open the zpool the active boot environment resides on, or • libbe fails to locate the boot environment that is currently mounted. The libbe_close() function frees all resources previously acquired in libbe_init(), invalidating the handle in the process. The be_active_name() function returns the name of the currently booted boot environment. This boot environment may not belong to the same BE root as the root libbe is operating on! The be_active_path() function returns the full path of the currently booted boot environment. This boot environment may not belong to the same BE root as the root libbe is operating on! The be_nextboot_name() function returns the name of the boot environ- ment that will be active on reboot. The be_nextboot_path() function returns the full path of the boot envi- ronment that will be active on reboot. The be_root_path() function returns the boot environment root path. The be_snapshot() function creates a snapshot of be_name named snap_name. A value of NULL may be used, indicating that be_snaphot() should derive the snapshot name from the current date and time. If recursive is set, then be_snapshot() will recursively snapshot the dataset. If result is not NULL, then it will be populated with the fi- nal "be_name@snap_name". The be_is_auto_snapshot_name() function is used to determine if the given snapshot name matches the format that the be_snapshot() function will use by default if it is not given a snapshot name to use. It re- turns true if the name matches the format, and false if it does not. The be_create() function creates a boot environment with the given name. The new boot environment will be created from a recursive snap- shot of the currently booted boot environment. The be_create_depth() function creates a boot environment with the given name from an existing snapshot. The depth parameter specifies the depth of recursion that will be cloned from the existing snapshot. A depth of '0' is no recursion and '-1' is unlimited (i.e., a recursive boot environment). The be_create_from_existing() function creates a boot environment with the given name from the name of an existing boot environment. A recur- sive snapshot will be made of the origin boot environment, and the new boot environment will be created from that. The be_create_from_existing_snap() function creates a recursive boot environment with the given name from an existing snapshot. The be_rename() function renames a boot environment without unmounting it, as if renamed with the -u argument were passed to zfs rename The be_activate() function makes a boot environment active on the next boot. If the temporary flag is set, then it will be active for the next boot only, as done by zfsbootcfg(8). The be_deactivate() function deactivates a boot environment. If the temporary flag is set, then it will cause removal of boot once configu- ration, set by be_activate() function or by zfsbootcfg(8). If the temporary flag is not set, be_deactivate() function will set zfs canmount property to noauto. The be_destroy() function will recursively destroy the given boot envi- ronment. It will not destroy a mounted boot environment unless the BE_DESTROY_FORCE option is set in options. If the BE_DESTROY_ORIGIN option is set in options, the be_destroy() function will destroy the origin snapshot to this boot environment as well. The be_nicenum() function will format name in a traditional ZFS human- ized format, similar to humanize_number(3). This function effectively proxies zfs_nicenum() from libzfs. The be_mount() function will mount the given boot environment. If mountpoint is NULL, a mount point will be generated in TMPDIR or, if TMPDIR is not set, /tmp using mkdtemp(3). If result is not NULL, it should be large enough to accommodate BE_MAXPATHLEN including the null terminator. the final mount point will be copied into it. Setting the BE_MNT_FORCE flag will pass MNT_FORCE to the underlying mount(2) call. The be_mounted_at() function will check if there is a boot environment mounted at the given path. If details is not NULL, it will be popu- lated with a list of the mounted dataset's properties. This list of properties matches the properties collected by be_get_bootenv_props(). The be_unmount() function will unmount the given boot environment. If the mount point looks like it was created by be_mount(), then be_unmount() will attempt to rmdir(2) the mountpoint after a successful unmount. Setting the BE_MNT_FORCE flag will pass MNT_FORCE to the un- derlying mount(2) call. The libbe_errno() function returns the libbe errno. The libbe_error_description() function returns a string description of the currently set libbe errno. The libbe_print_on_error() function will change whether or not libbe prints the description of any encountered error to stderr, based on doprint. The be_root_concat() function will concatenate the boot environment root and the given boot environment name into result. The be_validate_name() function will validate the given boot environ- ment name for both length restrictions as well as valid character re- strictions. This function does not set the internal library error state. The be_validate_snap() function will validate the given snapshot name. The snapshot must have a valid name, exist, and have a mountpoint of /. This function does not set the internal library error state. The be_exists() function will check whether the given boot environment exists and has a mountpoint of /. This function does not set the in- ternal library error state, but will return the appropriate error. The be_export() function will export the given boot environment to the file specified by fd. A snapshot will be created of the boot environ- ment prior to export. The be_import() function will import the boot environment in the file specified by fd, and give it the name be_name. The be_prop_list_alloc() function allocates a property list suitable for passing to be_get_bootenv_props(), be_get_dataset_props(), or be_get_dataset_snapshots(). It should be freed later by be_prop_list_free. The be_get_bootenv_props() function will populate be_list with nvpair_t of boot environment names paired with an nvlist_t of their properties. The following properties are currently collected as appropriate: Returned name Description dataset - name Boot environment name mounted Current mount point mountpoint "mountpoint" property origin "origin" property creation "creation" property active Currently booted environment used Literal "used" property usedds Literal "usedds" property usedsnap Literal "usedrefreserv" property referenced Literal "referenced" property nextboot Active on next boot Only the "dataset", "name", "active", and "nextboot" returned values will always be present. All other properties may be omitted if not available. The be_get_dataset_props() function will get properties of the speci- fied dataset. props is populated directly with a list of the proper- ties as returned by be_get_bootenv_props(). The be_get_dataset_snapshots() function will retrieve all snapshots of the given dataset. snap_list will be populated with a list of nvpair_t exactly as specified by be_get_bootenv_props(). The be_prop_list_free() function will free the property list. DIAGNOSTICS Upon error, one of the following values will be returned: • BE_ERR_SUCCESS • BE_ERR_INVALIDNAME • BE_ERR_EXISTS • BE_ERR_NOENT • BE_ERR_PERMS • BE_ERR_DESTROYACT • BE_ERR_DESTROYMNT • BE_ERR_BADPATH • BE_ERR_PATHBUSY • BE_ERR_PATHLEN • BE_ERR_BADMOUNT • BE_ERR_NOORIGIN • BE_ERR_MOUNTED • BE_ERR_NOMOUNT • BE_ERR_ZFSOPEN • BE_ERR_ZFSCLONE • BE_ERR_IO • BE_ERR_NOPOOL • BE_ERR_NOMEM • BE_ERR_UNKNOWN • BE_ERR_INVORIGIN SEE ALSO bectl(8) HISTORY bectl(8) and libbe were written by Kyle Kneitinger (kneitinger) <kyle@kneit.in> as a 2017 Google Summer of Code project, with Allan Jude (allanjude) <allanjude@freebsd.org> as mentor. AUTHORS Kyle Kneitinger, mentored as above. Post-GSoC changes were written by Kyle Evans (kevans) <kevans@freebsd.org>. FreeBSD 15.0 April 20, 2025 LIBBE(3)
NAME | LIBRARY | SYNOPSIS | DESCRIPTION | DIAGNOSTICS | SEE ALSO | HISTORY | AUTHORS
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=libbe&sektion=3&manpath=FreeBSD+15.0-RELEASE+and+Ports>