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 November 17, 2018
  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 .Pp
 257 The
 258 .Fn be_nicenum
 259 function will format
 260 .Fa name
 261 in a traditional ZFS humanized format, similar to
 262 .Xr humanize_number 3 .
 263 This function effectively proxies
 264 .Fn zfs_nicenum
 265 from libzfs.
 266 .Pp
 267 The
 268 .Fn be_mount
 269 function will mount the given boot environment.
 270 If
 271 .Fa mountpoint
 272 is
 273 .Dv NULL ,
 274 a mount point will be generated in
 275 .Pa /tmp
 276 using
 277 .Xr mkdtemp 3 .
 278 If
 279 .Fa result
 280 is not
 281 .Dv NULL ,
 282 it should be large enough to accommodate
 283 .Dv BE_MAXPATHLEN
 284 including the null terminator.
 285 the final mount point will be copied into it.
 286 Setting the
 287 .Dv BE_MNT_FORCE
 288 flag will pass
 289 .Dv MNT_FORCE
 290 to the underlying
 291 .Xr mount 2
 292 call.
 293 .Pp
 294 The
 295 .Fn be_mounted_at
 296 function will check if there is a boot environment mounted at the given
 297 .Fa path .
 298 If
 299 .Fa details
 300 is not
 301 .Dv NULL ,
 302 it will be populated with a list of the mounted dataset's properties.
 303 This list of properties matches the properties collected by
 304 .Fn be_get_bootenv_props .
 305 .Pp
 306 The
 307 .Fn be_unmount
 308 function will unmount the given boot environment.
 309 Setting the
 310 .Dv BE_MNT_FORCE
 311 flag will pass
 312 .Dv MNT_FORCE
 313 to the underlying
 314 .Xr mount 2
 315 call.
 316 .Pp
 317 The
 318 .Fn libbe_errno
 319 function returns the
 320 .Nm
 321 errno.
 322 .Pp
 323 The
 324 .Fn libbe_error_description
 325 function returns a string description of the currently set
 326 .Nm
 327 errno.
 328 .Pp
 329 The
 330 .Fn libbe_print_on_error
 331 function will change whether or not
 332 .Nm
 333 prints the description of any encountered error to
 334 .Dv stderr ,
 335 based on
 336 .Fa doprint .
 337 .Pp
 338 The
 339 .Fn be_root_concat
 340 function will concatenate the boot environment root and the given boot
 341 environment name into
 342 .Fa result .
 343 .Pp
 344 The
 345 .Fn be_validate_name
 346 function will validate the given boot environment name for both length
 347 restrictions as well as valid character restrictions.
 348 This function does not set the internal library error state.
 349 .Pp
 350 The
 351 .Fn be_validate_snap
 352 function will validate the given snapshot name.
 353 The snapshot must have a valid name, exist, and have a mountpoint of
 354 .Pa / .
 355 This function does not set the internal library error state.
 356 .Pp
 357 The
 358 .Fn be_exists
 359 function will check whether the given boot environment exists and has a
 360 mountpoint of
 361 .Pa / .
 362 This function does not set the internal library error state, but will return
 363 the appropriate error.
 364 .Pp
 365 The
 366 .Fn be_export
 367 function will export the given boot environment to the file specified by
 368 .Fa fd .
 369 A snapshot will be created of the boot environment prior to export.
 370 .Pp
 371 The
 372 .Fn be_import
 373 function will import the boot environment in the file specified by
 374 .Fa fd ,
 375 and give it the name
 376 .Fa be_name .
 377 .Pp
 378 The
 379 .Fn be_prop_list_alloc
 380 function allocates a property list suitable for passing to
 381 .Fn be_get_bootenv_props ,
 382 .Fn be_get_dataset_props ,
 383 or
 384 .Fn be_get_dataset_snapshots .
 385 It should be freed later by
 386 .Fa be_prop_list_free .
 387 .Pp
 388 The
 389 .Fn be_get_bootenv_props
 390 function will populate
 391 .Fa be_list
 392 with
 393 .Vt nvpair_t
 394 of boot environment names paired with an
 395 .Vt nvlist_t
 396 of their properties.
 397 The following properties are currently collected as appropriate:
 398 .Bl -column "Returned name"
 399 .It Sy Returned name Ta Sy Description
 400 .It dataset Ta -
 401 .It name Ta Boot environment name
 402 .It mounted Ta Current mount point
 403 .It mountpoint Ta Do mountpoint Dc property
 404 .It origin Ta Do origin Dc property
 405 .It creation Ta Do creation Dc property
 406 .It active Ta Currently booted environment
 407 .It used Ta Literal Do used Dc property
 408 .It usedds Ta Literal Do usedds Dc property
 409 .It usedsnap Ta Literal Do usedrefreserv Dc property
 410 .It referenced Ta Literal Do referenced Dc property
 411 .It nextboot Ta Active on next boot
 412 .El
 413 .Pp
 414 Only the
 415 .Dq dataset ,
 416 .Dq name ,
 417 .Dq active ,
 418 and
 419 .Dq nextboot
 420 returned values will always be present.
 421 All other properties may be omitted if not available.
 422 .Pp
 423 The
 424 .Fn be_get_dataset_props
 425 function will get properties of the specified dataset.
 426 .Fa props
 427 is populated directly with a list of the properties as returned by
 428 .Fn be_get_bootenv_props .
 429 .Pp
 430 The
 431 .Fn be_get_dataset_snapshots
 432 function will retrieve all snapshots of the given dataset.
 433 .Fa snap_list
 434 will be populated with a list of
 435 .Vt nvpair_t
 436 exactly as specified by
 437 .Fn be_get_bootenv_props .
 438 .Pp
 439 The
 440 .Fn be_prop_list_free
 441 function will free the property list.
 442 .Sh DIAGNOSTICS
 443 Upon error, one of the following values will be returned.
 444 .\" TODO: make each entry on its own line.
 445 .Bd -ragged -offset indent
 446 BE_ERR_SUCCESS,
 447 BE_ERR_INVALIDNAME,
 448 BE_ERR_EXISTS,
 449 BE_ERR_NOENT,
 450 BE_ERR_PERMS,
 451 BE_ERR_DESTROYACT,
 452 BE_ERR_DESTROYMNT,
 453 BE_ERR_BADPATH,
 454 BE_ERR_PATHBUSY,
 455 BE_ERR_PATHLEN,
 456 BE_ERR_BADMOUNT,
 457 BE_ERR_NOORIGIN,
 458 BE_ERR_MOUNTED,
 459 BE_ERR_NOMOUNT,
 460 BE_ERR_ZFSOPEN,
 461 BE_ERR_ZFSCLONE,
 462 BE_ERR_IO,
 463 BE_ERR_NOPOOL,
 464 BE_ERR_NOMEM,
 465 BE_ERR_UNKNOWN
 466 .Ed
 467 .Sh SEE ALSO
 468 .Xr be 1
 469 .Sh HISTORY
 470 .Nm
 471 and its corresponding command,
 472 .Xr bectl 8 ,
 473 were written as a 2017 Google Summer of Code project with Allan Jude serving
 474 as a mentor.
 475 Later work was done by
 476 .An Kyle Evans Aq Mt kevans@FreeBSD.org .