lib/libbe/libbe.3

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