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 February 12, 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 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 takes an optional BE root and initializes 161.Nm , 162returning a 163.Vt "libbe_handle_t *" 164on success, or 165.Dv NULL 166on error. 167If a BE root is supplied, 168.Nm 169will only operate out of that pool and BE root. 170An error may occur if: 171.Bl -column 172.It /boot and / are not on the same filesystem and device, 173.It libzfs fails to initialize, 174.It The system has not been properly booted with a ZFS boot 175environment, 176.It Nm 177fails to open the zpool the active boot environment resides on, or 178.It Nm 179fails to locate the boot environment that is currently mounted. 180.El 181.Pp 182The 183.Fn libbe_close 184function frees all resources previously acquired in 185.Fn libbe_init , 186invalidating the handle in the process. 187.Pp 188The 189.Fn be_active_name 190function returns the name of the currently booted boot environment. 191This boot environment may not belong to the same BE root as the root libbe 192is operating on! 193.Pp 194The 195.Fn be_active_path 196function returns the full path 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_nextboot_name 202function returns the name of the boot environment that will be active on reboot. 203.Pp 204The 205.Fn be_nextboot_path 206function returns the full path of the boot environment that will be 207active on reboot. 208.Pp 209The 210.Fn be_root_path 211function returns the boot environment root path. 212.Pp 213The 214.Fn be_create 215function creates a boot environment with the given name. 216It will be created from a snapshot of the currently booted boot environment. 217.Pp 218The 219.Fn be_create_from_existing 220function creates a boot environment with the given name from the name of an 221existing boot environment. 222A snapshot will be made of the base boot environment, and the new boot 223environment will be created from that. 224.Pp 225The 226.Fn be_create_from_existing_snap 227function creates a boot environment with the given name from an existing 228snapshot. 229.Pp 230The 231.Fn be_rename 232function renames a boot environment without unmounting it, as if renamed with 233the 234.Fl u 235argument were passed to 236.Nm zfs 237.Cm rename 238.Pp 239The 240.Fn be_activate 241function makes a boot environment active on the next boot. 242If the 243.Fa temporary 244flag is set, then it will be active for the next boot only, as done by 245.Xr zfsbootcfg 8 . 246Next boot functionality is currently only available when booting in x86 BIOS 247mode. 248.Pp 249The 250.Fn be_destroy 251function will recursively destroy the given boot environment. 252It will not destroy a mounted boot environment unless the 253.Dv BE_DESTROY_FORCE 254option is set in 255.Fa options . 256If the 257.Dv BE_DESTROY_ORIGIN 258option is set in 259.Fa options , 260the 261.Fn be_destroy 262function will destroy the origin snapshot to this boot environment as well. 263.Pp 264The 265.Fn be_nicenum 266function will format 267.Fa name 268in a traditional ZFS humanized format, similar to 269.Xr humanize_number 3 . 270This function effectively proxies 271.Fn zfs_nicenum 272from libzfs. 273.Pp 274The 275.Fn be_mount 276function will mount the given boot environment. 277If 278.Fa mountpoint 279is 280.Dv NULL , 281a mount point will be generated in 282.Pa /tmp 283using 284.Xr mkdtemp 3 . 285If 286.Fa result 287is not 288.Dv NULL , 289it should be large enough to accommodate 290.Dv BE_MAXPATHLEN 291including the null terminator. 292the final mount point will be copied into it. 293Setting the 294.Dv BE_MNT_FORCE 295flag will pass 296.Dv MNT_FORCE 297to the underlying 298.Xr mount 2 299call. 300.Pp 301The 302.Fn be_mounted_at 303function will check if there is a boot environment mounted at the given 304.Fa path . 305If 306.Fa details 307is not 308.Dv NULL , 309it will be populated with a list of the mounted dataset's properties. 310This list of properties matches the properties collected by 311.Fn be_get_bootenv_props . 312.Pp 313The 314.Fn be_unmount 315function will unmount the given boot environment. 316Setting the 317.Dv BE_MNT_FORCE 318flag will pass 319.Dv MNT_FORCE 320to the underlying 321.Xr mount 2 322call. 323.Pp 324The 325.Fn libbe_errno 326function returns the 327.Nm 328errno. 329.Pp 330The 331.Fn libbe_error_description 332function returns a string description of the currently set 333.Nm 334errno. 335.Pp 336The 337.Fn libbe_print_on_error 338function will change whether or not 339.Nm 340prints the description of any encountered error to 341.Dv stderr , 342based on 343.Fa doprint . 344.Pp 345The 346.Fn be_root_concat 347function will concatenate the boot environment root and the given boot 348environment name into 349.Fa result . 350.Pp 351The 352.Fn be_validate_name 353function will validate the given boot environment name for both length 354restrictions as well as valid character restrictions. 355This function does not set the internal library error state. 356.Pp 357The 358.Fn be_validate_snap 359function will validate the given snapshot name. 360The snapshot must have a valid name, exist, and have a mountpoint of 361.Pa / . 362This function does not set the internal library error state. 363.Pp 364The 365.Fn be_exists 366function will check whether the given boot environment exists and has a 367mountpoint of 368.Pa / . 369This function does not set the internal library error state, but will return 370the appropriate error. 371.Pp 372The 373.Fn be_export 374function will export the given boot environment to the file specified by 375.Fa fd . 376A snapshot will be created of the boot environment prior to export. 377.Pp 378The 379.Fn be_import 380function will import the boot environment in the file specified by 381.Fa fd , 382and give it the name 383.Fa be_name . 384.Pp 385The 386.Fn be_prop_list_alloc 387function allocates a property list suitable for passing to 388.Fn be_get_bootenv_props , 389.Fn be_get_dataset_props , 390or 391.Fn be_get_dataset_snapshots . 392It should be freed later by 393.Fa be_prop_list_free . 394.Pp 395The 396.Fn be_get_bootenv_props 397function will populate 398.Fa be_list 399with 400.Vt nvpair_t 401of boot environment names paired with an 402.Vt nvlist_t 403of their properties. 404The following properties are currently collected as appropriate: 405.Bl -column "Returned name" 406.It Sy Returned name Ta Sy Description 407.It dataset Ta - 408.It name Ta Boot environment name 409.It mounted Ta Current mount point 410.It mountpoint Ta Do mountpoint Dc property 411.It origin Ta Do origin Dc property 412.It creation Ta Do creation Dc property 413.It active Ta Currently booted environment 414.It used Ta Literal Do used Dc property 415.It usedds Ta Literal Do usedds Dc property 416.It usedsnap Ta Literal Do usedrefreserv Dc property 417.It referenced Ta Literal Do referenced Dc property 418.It nextboot Ta Active on next boot 419.El 420.Pp 421Only the 422.Dq dataset , 423.Dq name , 424.Dq active , 425and 426.Dq nextboot 427returned values will always be present. 428All other properties may be omitted if not available. 429.Pp 430The 431.Fn be_get_dataset_props 432function will get properties of the specified dataset. 433.Fa props 434is populated directly with a list of the properties as returned by 435.Fn be_get_bootenv_props . 436.Pp 437The 438.Fn be_get_dataset_snapshots 439function will retrieve all snapshots of the given dataset. 440.Fa snap_list 441will be populated with a list of 442.Vt nvpair_t 443exactly as specified by 444.Fn be_get_bootenv_props . 445.Pp 446The 447.Fn be_prop_list_free 448function will free the property list. 449.Sh DIAGNOSTICS 450Upon error, one of the following values will be returned: 451.Bl -dash -offset indent -compact 452.It 453BE_ERR_SUCCESS 454.It 455BE_ERR_INVALIDNAME 456.It 457BE_ERR_EXISTS 458.It 459BE_ERR_NOENT 460.It 461BE_ERR_PERMS 462.It 463BE_ERR_DESTROYACT 464.It 465BE_ERR_DESTROYMNT 466.It 467BE_ERR_BADPATH 468.It 469BE_ERR_PATHBUSY 470.It 471BE_ERR_PATHLEN 472.It 473BE_ERR_BADMOUNT 474.It 475BE_ERR_NOORIGIN 476.It 477BE_ERR_MOUNTED 478.It 479BE_ERR_NOMOUNT 480.It 481BE_ERR_ZFSOPEN 482.It 483BE_ERR_ZFSCLONE 484.It 485BE_ERR_IO 486.It 487BE_ERR_NOPOOL 488.It 489BE_ERR_NOMEM 490.It 491BE_ERR_UNKNOWN 492.It 493BE_ERR_INVORIGIN 494.El 495.Sh SEE ALSO 496.Xr bectl 8 497.Sh HISTORY 498.Nm 499and its corresponding command, 500.Xr bectl 8 , 501were written as a 2017 Google Summer of Code project with Allan Jude serving 502as a mentor. 503Later work was done by 504.An Kyle Evans Aq Mt kevans@FreeBSD.org . 505