home | help 
LIBBE(3)		     Library Functions Manual			LIBBE(3)

NAME
     libbe  --	library for creating, destroying and modifying ZFS boot environ-
     ments

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  op-
     erations regarding ZFS boot environments including "deep" boot environments
     in which a boot environments 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 operations.  libbe
     may be configured to print the corresponding error message 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 other-
     wise 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 environment,
     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 environment
     that will be active on reboot.

     The be_nextboot_path() function returns the full path of the boot	environ-
     ment 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 NULL snap_name 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 final "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 returns	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 snapshot  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  recursive
     snapshot  will be made of the origin boot environment, and the new boot en-
     vironment will be created from that.

     The be_create_from_existing_snap() function creates a recursive boot  envi-
     ronment 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 configura-
     tion, 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 environ-
     ment.   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 snap-
     shot to this boot environment as well.

     The be_nicenum() function will format name in a traditional  ZFS  humanized
     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  /tmp using
     mkdtemp(3).  If result is not NULL, it should be large enough  to	accommo-
     date  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  populated
     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.  Setting
     the BE_MNT_FORCE flag will pass MNT_FORCE to the underlying 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  environment
     name  for both length restrictions as well as valid character restrictions.
     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 ex-
     ists and has a mountpoint of /.  This function does not  set  the	internal
     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 environment prior
     to export.

     The be_import() function will import the boot environment in the file spec-
     ified 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 specified
     dataset.  props is populated directly with a list of the properties as  re-
     turned 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
     libbe and its corresponding command,  bectl(8),  were  written  as  a  2017
     Google  Summer  of Code project with Allan Jude serving as a mentor.  Later
     work was done by Kyle Evans <kevans@FreeBSD.org>.

FreeBSD 13.0			 August 18, 2020			LIBBE(3)
home | help