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