1.\" 2.\" SPDX-License-Identifier: BSD-2-Clause 3.\" 4.\" Copyright (c) 2017 Kyle Kneitinger 5.\" Copyright (c) 2018 Kyle Evans <kevans@FreeBSD.org> 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.Dd April 20, 2025 29.Dt LIBBE 3 30.Os 31.Sh NAME 32.Nm libbe 33.Nd library for creating, destroying and modifying ZFS boot environments 34.Sh LIBRARY 35.Lb libbe 36.Sh SYNOPSIS 37.In be.h 38.Ft "libbe_handle_t *hdl" Ns 39.Fn libbe_init "const char *be_root" 40.Pp 41.Ft void 42.Fn libbe_close "libbe_handle_t *hdl" 43.Pp 44.Ft const char * Ns 45.Fn be_active_name "libbe_handle_t *hdl" 46.Pp 47.Ft const char * Ns 48.Fn be_active_path "libbe_handle_t *hdl" 49.Pp 50.Ft const char * Ns 51.Fn be_nextboot_name "libbe_handle_t *hdl" 52.Pp 53.Ft const char * Ns 54.Fn be_nextboot_path "libbe_handle_t *hdl" 55.Pp 56.Ft const char * Ns 57.Fn be_root_path "libbe_handle_t *hdl" 58.Pp 59.Ft int Ns 60.Fn be_snapshot "libbe_handle_t *hdl" "const char *be_name" "const char *snap_name" "bool recursive" "char *result" 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.Pp 83.Ft int 84.Fn be_deactivate "libbe_handle_t *hdl" "const char *be_name" "bool temporary" 85.Pp 86.Ft int 87.Fn be_destroy "libbe_handle_t *hdl" "const char *be_name" "int options" 88.Pp 89.Ft void 90.Fn be_nicenum "uint64_t num" "char *buf" "size_t bufsz" 91.Pp 92.\" TODO: Write up of mount options 93.\" typedef enum { 94.\" BE_MNT_FORCE = 1 << 0, 95.\" BE_MNT_DEEP = 1 << 1, 96.\" } be_mount_opt_t 97.Ft int 98.Fn be_mount "libbe_handle_t *hdl" "const char *be_name" "const char *mntpoint" "int flags" "char *result" 99.Pp 100.Ft int 101.Fn be_mounted_at "libbe_handle_t *hdl" "const char *path" "nvlist_t *details" 102.Pp 103.Ft int 104.Fn be_unmount "libbe_handle_t *hdl" "const char *be_name" "int flags" 105.Pp 106.Ft int 107.Fn libbe_errno "libbe_handle_t *hdl" 108.Pp 109.Ft const char * Ns 110.Fn libbe_error_description "libbe_handle_t *hdl" 111.Pp 112.Ft void 113.Fn libbe_print_on_error "libbe_handle_t *hdl" "bool doprint" 114.Pp 115.Ft int 116.Fn be_root_concat "libbe_handle_t *hdl" "const char *be_name" "char *result" 117.Pp 118.Ft int 119.Fn be_validate_name "libbe_handle_t *hdl" "const char *be_name" 120.Pp 121.Ft int 122.Fn be_validate_snap "libbe_handle_t *hdl" "const char *snap" 123.Pp 124.Ft int 125.Fn be_exists "libbe_handle_t *hdl" "const char *be_name" 126.Pp 127.Ft int 128.Fn be_export "libbe_handle_t *hdl" "const char *be_name" "int fd" 129.Pp 130.Ft int 131.Fn be_import "libbe_handle_t *hdl" "const char *be_name" "int fd" 132.Pp 133.Ft int 134.Fn be_prop_list_alloc "nvlist_t **prop_list" 135.Pp 136.Ft int 137.Fn be_get_bootenv_props "libbe_handle_t *hdl" "nvlist_t *be_list" 138.Pp 139.Ft int 140.Fn be_get_dataset_props "libbe_handle_t *hdl" "const char *ds_name" "nvlist_t *props" 141.Pp 142.Ft int 143.Fn be_get_dataset_snapshots "libbe_handle_t *hdl" "const char *ds_name" "nvlist_t *snap_list" 144.Pp 145.Ft void 146.Fn be_prop_list_free "nvlist_t *prop_list" 147.Sh DESCRIPTION 148.Nm 149interfaces with libzfs to provide a set of functions for various operations 150regarding ZFS boot environments, including "deep" boot environments in which 151a boot environment has child datasets. 152.Pp 153A context structure is passed to each function, allowing for a small amount 154of state to be retained, such as errors from previous operations. 155.Nm 156may be configured to print the corresponding error message to 157.Dv stderr 158when an error is encountered with 159.Fn libbe_print_on_error . 160.Pp 161All functions returning an 162.Vt int 163return 0 on success, or a 164.Nm 165errno otherwise as described in 166.Sx DIAGNOSTICS . 167.Pp 168The 169.Fn libbe_init 170function takes an optional BE root and initializes 171.Nm , 172returning a 173.Vt "libbe_handle_t *" 174on success, or 175.Dv NULL 176on error. 177If a BE root is supplied, 178.Nm 179will only operate out of that pool and BE root. 180An error may occur if: 181.Bl -bullet 182.It 183.Pa /boot 184and 185.Pa / 186are not on the same filesystem and device, 187.It 188libzfs fails to initialize, 189.It 190The system has not been properly booted with a ZFS boot 191environment, 192.It 193.Nm 194fails to open the zpool the active boot environment resides on, or 195.It 196.Nm 197fails to locate the boot environment that is currently mounted. 198.El 199.Pp 200The 201.Fn libbe_close 202function frees all resources previously acquired in 203.Fn libbe_init , 204invalidating the handle in the process. 205.Pp 206The 207.Fn be_active_name 208function returns the name of the currently booted boot environment. 209This boot environment may not belong to the same BE root as the root libbe 210is operating on! 211.Pp 212The 213.Fn be_active_path 214function returns the full path of the currently booted boot environment. 215This boot environment may not belong to the same BE root as the root libbe 216is operating on! 217.Pp 218The 219.Fn be_nextboot_name 220function returns the name of the boot environment that will be active on reboot. 221.Pp 222The 223.Fn be_nextboot_path 224function returns the full path of the boot environment that will be 225active on reboot. 226.Pp 227The 228.Fn be_root_path 229function returns the boot environment root path. 230.Pp 231The 232.Fn be_snapshot 233function creates a snapshot of 234.Fa be_name 235named 236.Fa snap_name . 237A value of 238.Dv NULL 239may be used, indicating that 240.Fn be_snaphot 241should derive the snapshot name from the current date and time. 242If 243.Fa recursive 244is set, then 245.Fn be_snapshot 246will recursively snapshot the dataset. 247If 248.Fa result 249is not 250.Dv NULL , 251then it will be populated with the final 252.Dq Fa be_name Ns @ Ns Fa snap_name . 253.Pp 254The 255.Fn be_is_auto_snapshot_name 256function is used to determine if the given snapshot name matches the format that 257the 258.Fn be_snapshot 259function will use by default if it is not given a snapshot name to use. 260It returns 261.Dv true 262if the name matches the format, and 263.Dv false 264if it does not. 265.Pp 266The 267.Fn be_create 268function creates a boot environment with the given name. 269The new boot environment will be created from a recursive snapshot of the 270currently booted boot environment. 271.Pp 272The 273.Fn be_create_depth 274function creates a boot environment with the given name from an existing 275snapshot. 276The depth parameter specifies the depth of recursion that will be cloned from 277the existing snapshot. 278A depth of '0' is no recursion and '-1' is unlimited (i.e., a recursive boot 279environment). 280.Pp 281The 282.Fn be_create_from_existing 283function creates a boot environment with the given name from the name of an 284existing boot environment. 285A recursive snapshot will be made of the origin boot environment, and the new 286boot environment will be created from that. 287.Pp 288The 289.Fn be_create_from_existing_snap 290function creates a recursive boot environment with the given name from an 291existing snapshot. 292.Pp 293The 294.Fn be_rename 295function renames a boot environment without unmounting it, as if renamed with 296the 297.Fl u 298argument were passed to 299.Nm zfs 300.Cm rename 301.Pp 302The 303.Fn be_activate 304function makes a boot environment active on the next boot. 305If the 306.Fa temporary 307flag is set, then it will be active for the next boot only, as done by 308.Xr zfsbootcfg 8 . 309.Pp 310The 311.Fn be_deactivate 312function deactivates a boot environment. 313If the 314.Fa temporary 315flag is set, then it will cause removal of boot once configuration, set by 316.Fn be_activate 317function or by 318.Xr zfsbootcfg 8 . 319If the 320.Fa temporary 321flag is not set, 322.Fn be_deactivate 323function will set zfs 324.Dv canmount 325property to 326.Dv noauto . 327.Pp 328The 329.Fn be_destroy 330function will recursively destroy the given boot environment. 331It will not destroy a mounted boot environment unless the 332.Dv BE_DESTROY_FORCE 333option is set in 334.Fa options . 335If the 336.Dv BE_DESTROY_ORIGIN 337option is set in 338.Fa options , 339the 340.Fn be_destroy 341function will destroy the origin snapshot to this boot environment as well. 342.Pp 343The 344.Fn be_nicenum 345function will format 346.Fa name 347in a traditional ZFS humanized format, similar to 348.Xr humanize_number 3 . 349This function effectively proxies 350.Fn zfs_nicenum 351from libzfs. 352.Pp 353The 354.Fn be_mount 355function will mount the given boot environment. 356If 357.Fa mountpoint 358is 359.Dv NULL , 360a mount point will be generated in 361.Ev TMPDIR 362or, if 363.Ev TMPDIR 364is not set, 365.Pa /tmp 366using 367.Xr mkdtemp 3 . 368If 369.Fa result 370is not 371.Dv NULL , 372it should be large enough to accommodate 373.Dv BE_MAXPATHLEN 374including the null terminator. 375the final mount point will be copied into it. 376Setting the 377.Dv BE_MNT_FORCE 378flag will pass 379.Dv MNT_FORCE 380to the underlying 381.Xr mount 2 382call. 383.Pp 384The 385.Fn be_mounted_at 386function will check if there is a boot environment mounted at the given 387.Fa path . 388If 389.Fa details 390is not 391.Dv NULL , 392it will be populated with a list of the mounted dataset's properties. 393This list of properties matches the properties collected by 394.Fn be_get_bootenv_props . 395.Pp 396The 397.Fn be_unmount 398function will unmount the given boot environment. 399If the mount point looks like it was created by 400.Fn be_mount , 401then 402.Fn be_unmount 403will attempt to 404.Xr rmdir 2 405the mountpoint after a successful unmount. 406Setting the 407.Dv BE_MNT_FORCE 408flag will pass 409.Dv MNT_FORCE 410to the underlying 411.Xr mount 2 412call. 413.Pp 414The 415.Fn libbe_errno 416function returns the 417.Nm 418errno. 419.Pp 420The 421.Fn libbe_error_description 422function returns a string description of the currently set 423.Nm 424errno. 425.Pp 426The 427.Fn libbe_print_on_error 428function will change whether or not 429.Nm 430prints the description of any encountered error to 431.Dv stderr , 432based on 433.Fa doprint . 434.Pp 435The 436.Fn be_root_concat 437function will concatenate the boot environment root and the given boot 438environment name into 439.Fa result . 440.Pp 441The 442.Fn be_validate_name 443function will validate the given boot environment name for both length 444restrictions as well as valid character restrictions. 445This function does not set the internal library error state. 446.Pp 447The 448.Fn be_validate_snap 449function will validate the given snapshot name. 450The snapshot must have a valid name, exist, and have a mountpoint of 451.Pa / . 452This function does not set the internal library error state. 453.Pp 454The 455.Fn be_exists 456function will check whether the given boot environment exists and has a 457mountpoint of 458.Pa / . 459This function does not set the internal library error state, but will return 460the appropriate error. 461.Pp 462The 463.Fn be_export 464function will export the given boot environment to the file specified by 465.Fa fd . 466A snapshot will be created of the boot environment prior to export. 467.Pp 468The 469.Fn be_import 470function will import the boot environment in the file specified by 471.Fa fd , 472and give it the name 473.Fa be_name . 474.Pp 475The 476.Fn be_prop_list_alloc 477function allocates a property list suitable for passing to 478.Fn be_get_bootenv_props , 479.Fn be_get_dataset_props , 480or 481.Fn be_get_dataset_snapshots . 482It should be freed later by 483.Fa be_prop_list_free . 484.Pp 485The 486.Fn be_get_bootenv_props 487function will populate 488.Fa be_list 489with 490.Vt nvpair_t 491of boot environment names paired with an 492.Vt nvlist_t 493of their properties. 494The following properties are currently collected as appropriate: 495.Bl -column "Returned name" 496.It Sy Returned name Ta Sy Description 497.It dataset Ta - 498.It name Ta Boot environment name 499.It mounted Ta Current mount point 500.It mountpoint Ta Do mountpoint Dc property 501.It origin Ta Do origin Dc property 502.It creation Ta Do creation Dc property 503.It active Ta Currently booted environment 504.It used Ta Literal Do used Dc property 505.It usedds Ta Literal Do usedds Dc property 506.It usedsnap Ta Literal Do usedrefreserv Dc property 507.It referenced Ta Literal Do referenced Dc property 508.It nextboot Ta Active on next boot 509.El 510.Pp 511Only the 512.Dq dataset , 513.Dq name , 514.Dq active , 515and 516.Dq nextboot 517returned values will always be present. 518All other properties may be omitted if not available. 519.Pp 520The 521.Fn be_get_dataset_props 522function will get properties of the specified dataset. 523.Fa props 524is populated directly with a list of the properties as returned by 525.Fn be_get_bootenv_props . 526.Pp 527The 528.Fn be_get_dataset_snapshots 529function will retrieve all snapshots of the given dataset. 530.Fa snap_list 531will be populated with a list of 532.Vt nvpair_t 533exactly as specified by 534.Fn be_get_bootenv_props . 535.Pp 536The 537.Fn be_prop_list_free 538function will free the property list. 539.Sh DIAGNOSTICS 540Upon error, one of the following values will be returned: 541.Bl -bullet -offset indent -compact 542.It 543BE_ERR_SUCCESS 544.It 545BE_ERR_INVALIDNAME 546.It 547BE_ERR_EXISTS 548.It 549BE_ERR_NOENT 550.It 551BE_ERR_PERMS 552.It 553BE_ERR_DESTROYACT 554.It 555BE_ERR_DESTROYMNT 556.It 557BE_ERR_BADPATH 558.It 559BE_ERR_PATHBUSY 560.It 561BE_ERR_PATHLEN 562.It 563BE_ERR_BADMOUNT 564.It 565BE_ERR_NOORIGIN 566.It 567BE_ERR_MOUNTED 568.It 569BE_ERR_NOMOUNT 570.It 571BE_ERR_ZFSOPEN 572.It 573BE_ERR_ZFSCLONE 574.It 575BE_ERR_IO 576.It 577BE_ERR_NOPOOL 578.It 579BE_ERR_NOMEM 580.It 581BE_ERR_UNKNOWN 582.It 583BE_ERR_INVORIGIN 584.El 585.Sh SEE ALSO 586.Xr bectl 8 587.Sh HISTORY 588.Xr bectl 8 589and 590.Nm 591were written by 592.An Kyle Kneitinger (kneitinger) Aq Mt kyle@kneit.in 593as a 2017 Google Summer of Code project, with 594.An Allan Jude (allanjude) Aq Mt allanjude@freebsd.org 595as mentor. 596.Sh AUTHORS 597Kyle Kneitinger, mentored as above. 598.Pp 599Post-GSoC changes were written by 600.An Kyle Evans (kevans) Aq Mt kevans@freebsd.org . 601