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