1.\" 2.\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD 3.\" 4.\" Copyright (c) 2017 Kyle Kneitinger 5.\" All rights reserved. 6.\" Copyright (c) 2018 Kyle Evans <kevans@FreeBSD.org> 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" notice, this list of conditions and the following disclaimer in the 15.\" documentation and/or other materials provided with the distribution. 16.\" 17.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 18.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 19.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 20.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 21.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 22.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 23.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 24.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 25.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 26.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 27.\" SUCH DAMAGE. 28.\" 29.\" $FreeBSD$ 30.\" 31.Dd August 31, 2018 32.Dt LIBBE 3 33.Os 34.Sh NAME 35.Nm libbe 36.Nd library for creating, destroying and modifying ZFS boot environments 37.Sh LIBRARY 38.Lb libbe 39.Sh SYNOPSIS 40.In be.h 41.Ft "libbe_handle_t *hdl" Ns 42.Fn libbe_init void 43.Pp 44.Ft void 45.Fn libbe_close "libbe_handle_t *hdl" 46.Pp 47.Ft const char * Ns 48.Fn be_active_name "libbe_handle_t *hdl" 49.Pp 50.Ft const char * Ns 51.Fn be_active_path "libbe_handle_t *hdl" 52.Pp 53.Ft const char * Ns 54.Fn be_nextboot_name "libbe_handle_t *hdl" 55.Pp 56.Ft const char * Ns 57.Fn be_nextboot_path "libbe_handle_t *hdl" 58.Pp 59.Ft const char * Ns 60.Fn be_root_path "libbe_handle_t *hdl" 61.Pp 62.Ft int 63.Fn be_create "libbe_handle_t *hdl" "const char *be_name" 64.Pp 65.Ft int 66.Fn be_create_from_existing "libbe_handle_t *hdl" "const char *be_name" "const char *be_origin" 67.Pp 68.Ft int 69.Fn be_create_from_existing_snap "libbe_handle_t *hdl" "const char *be_name" "const char *snap" 70.Pp 71.Ft int 72.Fn be_rename "libbe_handle_t *hdl" "const char *be_old" "const char *be_new" 73.Pp 74.Ft int 75.Fn be_activate "libbe_handle_t *hdl" "const char *be_name" "bool temporary" 76.Ft int 77.Fn be_destroy "libbe_handle_t *hdl" "const char *be_name" "int options" 78.Pp 79.Ft void 80.Fn be_nicenum "uint64_t num" "char *buf" "size_t bufsz" 81.Pp 82.\" TODO: Write up of mount options 83.\" typedef enum { 84.\" BE_MNT_FORCE = 1 << 0, 85.\" BE_MNT_DEEP = 1 << 1, 86.\" } be_mount_opt_t 87.Ft int 88.Fn be_mount "libbe_handle_t *hdl" "char *be_name" "char *mntpoint" "int flags" "char *result" 89.Pp 90.Ft int 91.Fn be_mounted_at "libbe_handle_t *hdl" "const char *path" "nvlist_t *details" 92.Pp 93.Ft int 94.Fn be_unmount "libbe_handle_t *hdl" "char *be_name" "int flags" 95.Pp 96.Ft int 97.Fn libbe_errno "libbe_handle_t *hdl" 98.Pp 99.Ft const char * Ns 100.Fn libbe_error_description "libbe_handle_t *hdl" 101.Pp 102.Ft void 103.Fn libbe_print_on_error "libbe_handle_t *hdl" "bool doprint" 104.Pp 105.Ft int 106.Fn be_root_concat "libbe_handle_t *hdl" "const char *be_name" "char *result" 107.Pp 108.Ft int 109.Fn be_validate_name "libbe_handle_t *hdl" "const char *be_name" 110.Pp 111.Ft int 112.Fn be_validate_snap "libbe_handle_t *hdl" "const char *snap" 113.Pp 114.Ft int 115.Fn be_exists "libbe_handle_t *hdl" "char *be_name" 116.Pp 117.Ft int 118.Fn be_export "libbe_handle_t *hdl" "const char *be_name" "int fd" 119.Pp 120.Ft int 121.Fn be_import "libbe_handle_t *hdl" "const char *be_name" "int fd" 122.Pp 123.Ft int 124.Fn be_prop_list_alloc "nvlist_t **prop_list" 125.Pp 126.Ft int 127.Fn be_get_bootenv_props "libbe_handle_t *hdl" "nvlist_t *be_list" 128.Pp 129.Ft int 130.Fn be_get_dataset_props "libbe_handle_t *hdl" "const char *ds_name" "nvlist_t *props" 131.Pp 132.Ft int 133.Fn be_get_dataset_snapshots "libbe_handle_t *hdl" "const char *ds_name" "nvlist_t *snap_list" 134.Pp 135.Ft void 136.Fn be_prop_list_free "nvlist_t *prop_list" 137.Sh DESCRIPTION 138.Nm 139interfaces with libzfs to provide a set of functions for various operations 140regarding ZFS boot environments including "deep" boot environments in which 141a boot environments has child datasets. 142.Pp 143A context structure is passed to each function, allowing for a small amount 144of state to be retained, such as errors from previous operations. 145.Nm 146may be configured to print the corresponding error message to 147.Dv stderr 148when an error is encountered with 149.Fn libbe_print_on_error . 150.Pp 151All functions returning an 152.Vt int 153return 0 on success, or a 154.Nm 155errno otherwise as described in 156.Sx DIAGNOSTICS . 157.Pp 158The 159.Fn libbe_init 160function initializes 161.Nm , 162returning a 163.Vt "libbe_handle_t *" 164on success, or 165.Dv NULL 166on error. 167An error may occur if: 168.Bl -column 169.It /boot and / are not on the same filesystem and device, 170.It libzfs fails to initialize, 171.It The system has not been properly booted with a ZFS boot 172environment, 173.It Nm 174fails to open the zpool the active boot environment resides on, or 175.It Nm 176fails to locate the boot environment that is currently mounted. 177.El 178.Pp 179The 180.Fn libbe_close 181function frees all resources previously acquired in 182.Fn libbe_init , 183invalidating the handle in the process. 184.Pp 185The 186.Fn be_active_name 187function returns the name of the currently booted boot environment, 188.Pp 189The 190.Fn be_active_path 191function returns the full path of the currently booted boot environment. 192.Pp 193The 194.Fn be_nextboot_name 195function returns the name of the boot environment that will be active on reboot. 196.Pp 197The 198.Fn be_nextboot_path 199function returns the full path of the boot environment that will be 200active on reboot. 201.Pp 202The 203.Fn be_root_path 204function returns the boot environment root path. 205.Pp 206The 207.Fn be_create 208function creates a boot environment with the given name. 209It will be created from a snapshot of the currently booted boot environment. 210.Pp 211The 212.Fn be_create_from_existing 213function creates a boot environment with the given name from the name of an 214existing boot environment. 215A snapshot will be made of the base boot environment, and the new boot 216environment will be created from that. 217.Pp 218The 219.Fn be_create_from_existing_snap 220function creates a boot environment with the given name from an existing 221snapshot. 222.Pp 223The 224.Fn be_rename 225function renames a boot environment without unmounting it, as if renamed with 226the 227.Fl u 228argument were passed to 229.Nm zfs 230.Cm rename 231.Pp 232The 233.Fn be_activate 234function makes a boot environment active on the next boot. 235If the 236.Fa temporary 237flag is set, then it will be active for the next boot only, as done by 238.Xr zfsbootcfg 8 . 239Next boot functionality is currently only available when booting in x86 BIOS 240mode. 241.Pp 242The 243.Fn be_destroy 244function will recursively destroy the given boot environment. 245It will not destroy a mounted boot environment unless the 246.Dv BE_DESTROY_FORCE 247option is set in 248.Fa options . 249.Pp 250The 251.Fn be_nicenum 252function will format 253.Fa name 254in a traditional ZFS humanized format, similar to 255.Xr humanize_number 3 . 256This function effectively proxies 257.Fn zfs_nicenum 258from libzfs. 259.Pp 260The 261.Fn be_mount 262function will mount the given boot environment. 263If 264.Fa mountpoint 265is 266.Dv NULL , 267a mount point will be generated in 268.Pa /tmp 269using 270.Xr mkdtemp 3 . 271If 272.Fa result 273is not 274.Dv NULL , 275it should be large enough to accommodate 276.Dv BE_MAXPATHLEN 277including the null terminator. 278the final mount point will be copied into it. 279Setting the 280.Dv BE_MNT_FORCE 281flag will pass 282.Dv MNT_FORCE 283to the underlying 284.Xr mount 2 285call. 286.Pp 287The 288.Fn be_mounted_at 289function will check if there is a boot environment mounted at the given 290.Fa path . 291If 292.Fa details 293is not 294.Dv NULL , 295it will be populated with a list of the mounted dataset's properties. 296This list of properties matches the properties collected by 297.Fn be_get_bootenv_props . 298.Pp 299The 300.Fn be_unmount 301function will unmount the given boot environment. 302Setting the 303.Dv BE_MNT_FORCE 304flag will pass 305.Dv MNT_FORCE 306to the underlying 307.Xr mount 2 308call. 309.Pp 310The 311.Fn libbe_errno 312function returns the 313.Nm 314errno. 315.Pp 316The 317.Fn libbe_error_description 318function returns a string description of the currently set 319.Nm 320errno. 321.Pp 322The 323.Fn libbe_print_on_error 324function will change whether or not 325.Nm 326prints the description of any encountered error to 327.Dv stderr , 328based on 329.Fa doprint . 330.Pp 331The 332.Fn be_root_concat 333function will concatenate the boot environment root and the given boot 334environment name into 335.Fa result . 336.Pp 337The 338.Fn be_validate_name 339function will validate the given boot environment name for both length 340restrictions as well as valid character restrictions. 341This function does not set the internal library error state. 342.Pp 343The 344.Fn be_validate_snap 345function will validate the given snapshot name. 346The snapshot must have a valid name, exist, and have a mountpoint of 347.Pa / . 348This function does not set the internal library error state. 349.Pp 350The 351.Fn be_exists 352function will check whether the given boot environment exists and has a 353mountpoint of 354.Pa / . 355This function does not set the internal library error state, but will return 356the appropriate error. 357.Pp 358The 359.Fn be_export 360function will export the given boot environment to the file specified by 361.Fa fd . 362A snapshot will be created of the boot environment prior to export. 363.Pp 364The 365.Fn be_import 366function will import the boot environment in the file specified by 367.Fa fd , 368and give it the name 369.Fa be_name . 370.Pp 371The 372.Fn be_prop_list_alloc 373function allocates a property list suitable for passing to 374.Fn be_get_bootenv_props , 375.Fn be_get_dataset_props , 376or 377.Fn be_get_dataset_snapshots . 378It should be freed later by 379.Fa be_prop_list_free . 380.Pp 381The 382.Fn be_get_bootenv_props 383function will populate 384.Fa be_list 385with 386.Vt nvpair_t 387of boot environment names paired with an 388.Vt nvlist_t 389of their properties. 390The following properties are currently collected as appropriate: 391.Bl -column "Returned name" 392.It Sy Returned name Ta Sy Description 393.It dataset Ta - 394.It name Ta Boot environment name 395.It mounted Ta Current mount point 396.It mountpoint Ta Do mountpoint Dc property 397.It origin Ta Do origin Dc property 398.It creation Ta Do creation Dc property 399.It active Ta Currently booted environment 400.It used Ta Literal Do used Dc property 401.It usedds Ta Literal Do usedds Dc property 402.It usedsnap Ta Literal Do usedrefreserv Dc property 403.It referenced Ta Literal Do referenced Dc property 404.It nextboot Ta Active on next boot 405.El 406.Pp 407Only the 408.Dq dataset , 409.Dq name , 410.Dq active , 411and 412.Dq nextboot 413returned values will always be present. 414All other properties may be omitted if not available. 415.Pp 416The 417.Fn be_get_dataset_props 418function will get properties of the specified dataset. 419.Fa props 420is populated directly with a list of the properties as returned by 421.Fn be_get_bootenv_props . 422.Pp 423The 424.Fn be_get_dataset_snapshots 425function will retrieve all snapshots of the given dataset. 426.Fa snap_list 427will be populated with a list of 428.Vt nvpair_t 429exactly as specified by 430.Fn be_get_bootenv_props . 431.Pp 432The 433.Fn be_prop_list_free 434function will free the property list. 435.Sh DIAGNOSTICS 436Upon error, one of the following values will be returned. 437.\" TODO: make each entry on its own line. 438.Bd -ragged -offset indent 439BE_ERR_SUCCESS, 440BE_ERR_INVALIDNAME, 441BE_ERR_EXISTS, 442BE_ERR_NOENT, 443BE_ERR_PERMS, 444BE_ERR_DESTROYACT, 445BE_ERR_DESTROYMNT, 446BE_ERR_BADPATH, 447BE_ERR_PATHBUSY, 448BE_ERR_PATHLEN, 449BE_ERR_BADMOUNT, 450BE_ERR_NOORIGIN, 451BE_ERR_MOUNTED, 452BE_ERR_NOMOUNT, 453BE_ERR_ZFSOPEN, 454BE_ERR_ZFSCLONE, 455BE_ERR_IO, 456BE_ERR_NOPOOL, 457BE_ERR_NOMEM, 458BE_ERR_UNKNOWN 459.Ed 460.Sh SEE ALSO 461.Xr be 1 462.Sh HISTORY 463.Nm 464and its corresponding command, 465.Xr bectl 8 , 466were written as a 2017 Google Summer of Code project with Allan Jude serving 467as a mentor. 468Later work was done by 469.An Kyle Evans Aq Mt kevans@FreeBSD.org . 470