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 October 16, 2019 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 "const char *be_root" 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 bool Ns 63.Fn be_is_auto_snapshot_name "libbe_handle_t *hdl" "const char *snap" 64.Pp 65.Ft int 66.Fn be_create "libbe_handle_t *hdl" "const char *be_name" 67.Pp 68.Ft int 69.Fn be_create_depth "libbe_handle_t *hdl" "const char *be_name" "const char *snap" "int depth" 70.Pp 71.Ft int 72.Fn be_create_from_existing "libbe_handle_t *hdl" "const char *be_name" "const char *be_origin" 73.Pp 74.Ft int 75.Fn be_create_from_existing_snap "libbe_handle_t *hdl" "const char *be_name" "const char *snap" 76.Pp 77.Ft int 78.Fn be_rename "libbe_handle_t *hdl" "const char *be_old" "const char *be_new" 79.Pp 80.Ft int 81.Fn be_activate "libbe_handle_t *hdl" "const char *be_name" "bool temporary" 82.Ft int 83.Fn be_destroy "libbe_handle_t *hdl" "const char *be_name" "int options" 84.Pp 85.Ft void 86.Fn be_nicenum "uint64_t num" "char *buf" "size_t bufsz" 87.Pp 88.\" TODO: Write up of mount options 89.\" typedef enum { 90.\" BE_MNT_FORCE = 1 << 0, 91.\" BE_MNT_DEEP = 1 << 1, 92.\" } be_mount_opt_t 93.Ft int 94.Fn be_mount "libbe_handle_t *hdl" "char *be_name" "char *mntpoint" "int flags" "char *result" 95.Pp 96.Ft int 97.Fn be_mounted_at "libbe_handle_t *hdl" "const char *path" "nvlist_t *details" 98.Pp 99.Ft int 100.Fn be_unmount "libbe_handle_t *hdl" "char *be_name" "int flags" 101.Pp 102.Ft int 103.Fn libbe_errno "libbe_handle_t *hdl" 104.Pp 105.Ft const char * Ns 106.Fn libbe_error_description "libbe_handle_t *hdl" 107.Pp 108.Ft void 109.Fn libbe_print_on_error "libbe_handle_t *hdl" "bool doprint" 110.Pp 111.Ft int 112.Fn be_root_concat "libbe_handle_t *hdl" "const char *be_name" "char *result" 113.Pp 114.Ft int 115.Fn be_validate_name "libbe_handle_t *hdl" "const char *be_name" 116.Pp 117.Ft int 118.Fn be_validate_snap "libbe_handle_t *hdl" "const char *snap" 119.Pp 120.Ft int 121.Fn be_exists "libbe_handle_t *hdl" "char *be_name" 122.Pp 123.Ft int 124.Fn be_export "libbe_handle_t *hdl" "const char *be_name" "int fd" 125.Pp 126.Ft int 127.Fn be_import "libbe_handle_t *hdl" "const char *be_name" "int fd" 128.Pp 129.Ft int 130.Fn be_prop_list_alloc "nvlist_t **prop_list" 131.Pp 132.Ft int 133.Fn be_get_bootenv_props "libbe_handle_t *hdl" "nvlist_t *be_list" 134.Pp 135.Ft int 136.Fn be_get_dataset_props "libbe_handle_t *hdl" "const char *ds_name" "nvlist_t *props" 137.Pp 138.Ft int 139.Fn be_get_dataset_snapshots "libbe_handle_t *hdl" "const char *ds_name" "nvlist_t *snap_list" 140.Pp 141.Ft void 142.Fn be_prop_list_free "nvlist_t *prop_list" 143.Sh DESCRIPTION 144.Nm 145interfaces with libzfs to provide a set of functions for various operations 146regarding ZFS boot environments including "deep" boot environments in which 147a boot environments has child datasets. 148.Pp 149A context structure is passed to each function, allowing for a small amount 150of state to be retained, such as errors from previous operations. 151.Nm 152may be configured to print the corresponding error message to 153.Dv stderr 154when an error is encountered with 155.Fn libbe_print_on_error . 156.Pp 157All functions returning an 158.Vt int 159return 0 on success, or a 160.Nm 161errno otherwise as described in 162.Sx DIAGNOSTICS . 163.Pp 164The 165.Fn libbe_init 166function takes an optional BE root and initializes 167.Nm , 168returning a 169.Vt "libbe_handle_t *" 170on success, or 171.Dv NULL 172on error. 173If a BE root is supplied, 174.Nm 175will only operate out of that pool and BE root. 176An error may occur if: 177.Bl -column 178.It /boot and / are not on the same filesystem and device, 179.It libzfs fails to initialize, 180.It The system has not been properly booted with a ZFS boot 181environment, 182.It Nm 183fails to open the zpool the active boot environment resides on, or 184.It Nm 185fails to locate the boot environment that is currently mounted. 186.El 187.Pp 188The 189.Fn libbe_close 190function frees all resources previously acquired in 191.Fn libbe_init , 192invalidating the handle in the process. 193.Pp 194The 195.Fn be_active_name 196function returns the name of the currently booted boot environment. 197This boot environment may not belong to the same BE root as the root libbe 198is operating on! 199.Pp 200The 201.Fn be_active_path 202function returns the full path of the currently booted boot environment. 203This boot environment may not belong to the same BE root as the root libbe 204is operating on! 205.Pp 206The 207.Fn be_nextboot_name 208function returns the name of the boot environment that will be active on reboot. 209.Pp 210The 211.Fn be_nextboot_path 212function returns the full path of the boot environment that will be 213active on reboot. 214.Pp 215The 216.Fn be_root_path 217function returns the boot environment root path. 218.Pp 219The 220.Fn be_is_auto_snapshot_name 221function is used to determine if the given snapshot name matches the format that 222the 223.Fn be_snapshot 224function will use by default if it is not given a snapshot name to use. 225It returns 226.Dv true 227if the name matches the format, and 228.Dv false 229if it does not. 230.Pp 231The 232.Fn be_create 233function creates a boot environment with the given name. 234The new boot environment will be created from a recursive snapshot of the 235currently booted boot environment. 236.Pp 237The 238.Fn be_create_depth 239function creates a boot environment with the given name from an existing 240snapshot. 241The depth parameter specifies the depth of recursion that will be cloned from 242the existing snapshot. 243A depth of '0' is no recursion and '-1' is unlimited (i.e., a recursive boot 244environment). 245.Pp 246The 247.Fn be_create_from_existing 248function creates a boot environment with the given name from the name of an 249existing boot environment. 250A recursive snapshot will be made of the origin boot environment, and the new 251boot environment will be created from that. 252.Pp 253The 254.Fn be_create_from_existing_snap 255function creates a recursive boot environment with the given name from an 256existing snapshot. 257.Pp 258The 259.Fn be_rename 260function renames a boot environment without unmounting it, as if renamed with 261the 262.Fl u 263argument were passed to 264.Nm zfs 265.Cm rename 266.Pp 267The 268.Fn be_activate 269function makes a boot environment active on the next boot. 270If the 271.Fa temporary 272flag is set, then it will be active for the next boot only, as done by 273.Xr zfsbootcfg 8 . 274Next boot functionality is currently only available when booting in x86 BIOS 275mode. 276.Pp 277The 278.Fn be_destroy 279function will recursively destroy the given boot environment. 280It will not destroy a mounted boot environment unless the 281.Dv BE_DESTROY_FORCE 282option is set in 283.Fa options . 284If the 285.Dv BE_DESTROY_ORIGIN 286option is set in 287.Fa options , 288the 289.Fn be_destroy 290function will destroy the origin snapshot to this boot environment as well. 291.Pp 292The 293.Fn be_nicenum 294function will format 295.Fa name 296in a traditional ZFS humanized format, similar to 297.Xr humanize_number 3 . 298This function effectively proxies 299.Fn zfs_nicenum 300from libzfs. 301.Pp 302The 303.Fn be_mount 304function will mount the given boot environment. 305If 306.Fa mountpoint 307is 308.Dv NULL , 309a mount point will be generated in 310.Pa /tmp 311using 312.Xr mkdtemp 3 . 313If 314.Fa result 315is not 316.Dv NULL , 317it should be large enough to accommodate 318.Dv BE_MAXPATHLEN 319including the null terminator. 320the final mount point will be copied into it. 321Setting the 322.Dv BE_MNT_FORCE 323flag will pass 324.Dv MNT_FORCE 325to the underlying 326.Xr mount 2 327call. 328.Pp 329The 330.Fn be_mounted_at 331function will check if there is a boot environment mounted at the given 332.Fa path . 333If 334.Fa details 335is not 336.Dv NULL , 337it will be populated with a list of the mounted dataset's properties. 338This list of properties matches the properties collected by 339.Fn be_get_bootenv_props . 340.Pp 341The 342.Fn be_unmount 343function will unmount the given boot environment. 344Setting the 345.Dv BE_MNT_FORCE 346flag will pass 347.Dv MNT_FORCE 348to the underlying 349.Xr mount 2 350call. 351.Pp 352The 353.Fn libbe_errno 354function returns the 355.Nm 356errno. 357.Pp 358The 359.Fn libbe_error_description 360function returns a string description of the currently set 361.Nm 362errno. 363.Pp 364The 365.Fn libbe_print_on_error 366function will change whether or not 367.Nm 368prints the description of any encountered error to 369.Dv stderr , 370based on 371.Fa doprint . 372.Pp 373The 374.Fn be_root_concat 375function will concatenate the boot environment root and the given boot 376environment name into 377.Fa result . 378.Pp 379The 380.Fn be_validate_name 381function will validate the given boot environment name for both length 382restrictions as well as valid character restrictions. 383This function does not set the internal library error state. 384.Pp 385The 386.Fn be_validate_snap 387function will validate the given snapshot name. 388The snapshot must have a valid name, exist, and have a mountpoint of 389.Pa / . 390This function does not set the internal library error state. 391.Pp 392The 393.Fn be_exists 394function will check whether the given boot environment exists and has a 395mountpoint of 396.Pa / . 397This function does not set the internal library error state, but will return 398the appropriate error. 399.Pp 400The 401.Fn be_export 402function will export the given boot environment to the file specified by 403.Fa fd . 404A snapshot will be created of the boot environment prior to export. 405.Pp 406The 407.Fn be_import 408function will import the boot environment in the file specified by 409.Fa fd , 410and give it the name 411.Fa be_name . 412.Pp 413The 414.Fn be_prop_list_alloc 415function allocates a property list suitable for passing to 416.Fn be_get_bootenv_props , 417.Fn be_get_dataset_props , 418or 419.Fn be_get_dataset_snapshots . 420It should be freed later by 421.Fa be_prop_list_free . 422.Pp 423The 424.Fn be_get_bootenv_props 425function will populate 426.Fa be_list 427with 428.Vt nvpair_t 429of boot environment names paired with an 430.Vt nvlist_t 431of their properties. 432The following properties are currently collected as appropriate: 433.Bl -column "Returned name" 434.It Sy Returned name Ta Sy Description 435.It dataset Ta - 436.It name Ta Boot environment name 437.It mounted Ta Current mount point 438.It mountpoint Ta Do mountpoint Dc property 439.It origin Ta Do origin Dc property 440.It creation Ta Do creation Dc property 441.It active Ta Currently booted environment 442.It used Ta Literal Do used Dc property 443.It usedds Ta Literal Do usedds Dc property 444.It usedsnap Ta Literal Do usedrefreserv Dc property 445.It referenced Ta Literal Do referenced Dc property 446.It nextboot Ta Active on next boot 447.El 448.Pp 449Only the 450.Dq dataset , 451.Dq name , 452.Dq active , 453and 454.Dq nextboot 455returned values will always be present. 456All other properties may be omitted if not available. 457.Pp 458The 459.Fn be_get_dataset_props 460function will get properties of the specified dataset. 461.Fa props 462is populated directly with a list of the properties as returned by 463.Fn be_get_bootenv_props . 464.Pp 465The 466.Fn be_get_dataset_snapshots 467function will retrieve all snapshots of the given dataset. 468.Fa snap_list 469will be populated with a list of 470.Vt nvpair_t 471exactly as specified by 472.Fn be_get_bootenv_props . 473.Pp 474The 475.Fn be_prop_list_free 476function will free the property list. 477.Sh DIAGNOSTICS 478Upon error, one of the following values will be returned: 479.Bl -dash -offset indent -compact 480.It 481BE_ERR_SUCCESS 482.It 483BE_ERR_INVALIDNAME 484.It 485BE_ERR_EXISTS 486.It 487BE_ERR_NOENT 488.It 489BE_ERR_PERMS 490.It 491BE_ERR_DESTROYACT 492.It 493BE_ERR_DESTROYMNT 494.It 495BE_ERR_BADPATH 496.It 497BE_ERR_PATHBUSY 498.It 499BE_ERR_PATHLEN 500.It 501BE_ERR_BADMOUNT 502.It 503BE_ERR_NOORIGIN 504.It 505BE_ERR_MOUNTED 506.It 507BE_ERR_NOMOUNT 508.It 509BE_ERR_ZFSOPEN 510.It 511BE_ERR_ZFSCLONE 512.It 513BE_ERR_IO 514.It 515BE_ERR_NOPOOL 516.It 517BE_ERR_NOMEM 518.It 519BE_ERR_UNKNOWN 520.It 521BE_ERR_INVORIGIN 522.El 523.Sh SEE ALSO 524.Xr bectl 8 525.Sh HISTORY 526.Nm 527and its corresponding command, 528.Xr bectl 8 , 529were written as a 2017 Google Summer of Code project with Allan Jude serving 530as a mentor. 531Later work was done by 532.An Kyle Evans Aq Mt kevans@FreeBSD.org . 533