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 August 24, 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 void
  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 bool
 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 initializes
 161 .Nm ,
 162 returning a
 163 .Vt "libbe_handle_t *"
 164 on success, or
 165 .Dv NULL
 166 on error.
 167 An error may occur if:
 168 .Bl -column
 169 .It /boot and / are not on the same filesystem and device,
 170 .It libzfs fails to initialize,
 171 .It The system has not been properly booted with a ZFS boot
 172 environment,
 173 .It Nm
 174 fails to open the zpool the active boot environment resides on, or
 175 .It Nm
 176 fails to locate the boot environment that is currently mounted.
 177 .El
 178 .Pp
 179 The
 180 .Fn libbe_close
 181 function frees all resources previously acquired in
 182 .Fn libbe_init ,
 183 invalidating the handle in the process.
 184 .Pp
 185 The
 186 .Fn be_active_name
 187 function returns the name of the currently booted boot environment,
 188 .Pp
 189 The
 190 .Fn be_active_path
 191 function returns the full path of the currently booted boot environment.
 192 .Pp
 193 The
 194 .Fn be_nextboot_name
 195 function returns the name of the boot environment that will be active on reboot.
 196 .Pp
 197 The
 198 .Fn be_nextboot_path
 199 function returns the full path of the boot environment that will be
 200 active on reboot.
 201 .Pp
 202 The
 203 .Fn be_root_path
 204 function returns the boot environment root path.
 205 .Pp
 206 The
 207 .Fn be_create
 208 function creates a boot environment with the given name.
 209 It will be created from a snapshot of the currently booted boot environment.
 210 .Pp
 211 The
 212 .Fn be_create_from_existing
 213 function creates a boot environment with the given name from the name of an
 214 existing boot environment.
 215 A snapshot will be made of the base boot environment, and the new boot
 216 environment will be created from that.
 217 .Pp
 218 The
 219 .Fn be_create_from_existing_snap
 220 function creates a boot environment with the given name from an existing
 221 snapshot.
 222 .Pp
 223 The
 224 .Fn be_rename
 225 function renames a boot environment without unmounting it, as if renamed with
 226 the
 227 .Fl u
 228 argument were passed to
 229 .Nm zfs
 230 .Cm rename
 231 .Pp
 232 The
 233 .Fn be_activate
 234 function makes a boot environment active on the next boot.
 235 If the
 236 .Fa temporary
 237 flag is set, then it will be active for the next boot only, as done by
 238 .Xr zfsbootcfg 8 .
 239 Next boot functionality is currently only available when booting in x86 BIOS
 240 mode.
 241 .Pp
 242 The
 243 .Fn be_destroy
 244 function will recursively destroy the given boot environment.
 245 It will not destroy a mounted boot environment unless the
 246 .Dv BE_DESTROY_FORCE
 247 option is set in
 248 .Fa options .
 249 .Pp
 250 The
 251 .Fn be_nicenum
 252 function will format
 253 .Fa name
 254 in a traditional ZFS humanized format, similar to
 255 .Xr humanize_number 3 .
 256 This function effectively proxies
 257 .Fn zfs_nicenum
 258 from libzfs.
 259 .Pp
 260 The
 261 .Fn be_mount
 262 function will mount the given boot environment.
 263 If
 264 .Fa mountpoint
 265 is
 266 .Dv NULL ,
 267 a mount point will be generated in
 268 .Pa /tmp
 269 using
 270 .Xr mkdtemp 3 .
 271 If
 272 .Fa result
 273 is not
 274 .Dv NULL ,
 275 it should be large enough to accommodate
 276 .Dv BE_MAXPATHLEN
 277 including the null terminator.
 278 the final mount point will be copied into it.
 279 Setting the
 280 .Dv BE_MNT_FORCE
 281 flag will pass
 282 .Dv MNT_FORCE
 283 to the underlying
 284 .Xr mount 2
 285 call.
 286 .Pp
 287 The
 288 .Fn be_mounted_at
 289 function will check if there is a boot environment mounted at the given
 290 .Fa path .
 291 If
 292 .Fa details
 293 is not
 294 .Dv NULL ,
 295 it will be populated with a list of the mounted dataset's properties.
 296 This list of properties matches the properties collected by
 297 .Fn be_get_bootenv_props .
 298 .Pp
 299 The
 300 .Fn be_unmount
 301 function will unmount the given boot environment.
 302 Setting the
 303 .Dv BE_MNT_FORCE
 304 flag will pass
 305 .Dv MNT_FORCE
 306 to the underlying
 307 .Xr mount 2
 308 call.
 309 .Pp
 310 The
 311 .Fn libbe_errno
 312 function returns the
 313 .Nm
 314 errno.
 315 .Pp
 316 The
 317 .Fn libbe_error_description
 318 function returns a string description of the currently set
 319 .Nm
 320 errno.
 321 .Pp
 322 The
 323 .Fn libbe_print_on_error
 324 function will change whether or not
 325 .Nm
 326 prints the description of any encountered error to
 327 .Dv stderr ,
 328 based on
 329 .Fa doprint .
 330 .Pp
 331 The
 332 .Fn be_root_concat
 333 function will concatenate the boot environment root and the given boot
 334 environment name into
 335 .Fa result .
 336 .Pp
 337 The
 338 .Fn be_validate_name
 339 function will validate the given boot environment name for both length
 340 restrictions as well as valid character restrictions.
 341 This function does not set the internal library error state.
 342 .Pp
 343 The
 344 .Fn be_validate_snap
 345 function will validate the given snapshot name.
 346 The snapshot must have a valid name, exist, and have a mountpoint of
 347 .Pa / .
 348 This function does not set the internal library error state.
 349 .Pp
 350 The
 351 .Fn be_exists
 352 function will check whether the given boot environment exists and has a
 353 mountpoint of
 354 .Pa / .
 355 .Pp
 356 The
 357 .Fn be_export
 358 function will export the given boot environment to the file specified by
 359 .Fa fd .
 360 A snapshot will be created of the boot environment prior to export.
 361 .Pp
 362 The
 363 .Fn be_import
 364 function will import the boot environment in the file specified by
 365 .Fa fd ,
 366 and give it the name
 367 .Fa be_name .
 368 .Pp
 369 The
 370 .Fn be_prop_list_alloc
 371 function allocates a property list suitable for passing to
 372 .Fn be_get_bootenv_props ,
 373 .Fn be_get_dataset_props ,
 374 or
 375 .Fn be_get_dataset_snapshots .
 376 It should be freed later by
 377 .Fa be_prop_list_free .
 378 .Pp
 379 The
 380 .Fn be_get_bootenv_props
 381 function will populate
 382 .Fa be_list
 383 with
 384 .Vt nvpair_t
 385 of boot environment names paired with an
 386 .Vt nvlist_t
 387 of their properties.
 388 The following properties are currently collected as appropriate:
 389 .Bl -column "Returned name"
 390 .It Sy Returned name Ta Sy Description
 391 .It dataset Ta -
 392 .It name Ta Boot environment name
 393 .It mounted Ta Current mount point
 394 .It mountpoint Ta Do mountpoint Dc property
 395 .It origin Ta Do origin Dc property
 396 .It creation Ta Do creation Dc property
 397 .It active Ta Currently booted environment
 398 .It used Ta Literal Do used Dc property
 399 .It usedds Ta Literal Do usedds Dc property
 400 .It usedsnap Ta Literal Do usedrefreserv Dc property
 401 .It referenced Ta Literal Do referenced Dc property
 402 .It nextboot Ta Active on next boot
 403 .El
 404 .Pp
 405 Only the
 406 .Dq dataset ,
 407 .Dq name ,
 408 .Dq active ,
 409 and
 410 .Dq nextboot
 411 returned values will always be present.
 412 All other properties may be omitted if not available.
 413 .Pp
 414 The
 415 .Fn be_get_dataset_props
 416 function will get properties of the specified dataset.
 417 .Fa props
 418 is populated directly with a list of the properties as returned by
 419 .Fn be_get_bootenv_props .
 420 .Pp
 421 The
 422 .Fn be_get_dataset_snapshots
 423 function will retrieve all snapshots of the given dataset.
 424 .Fa snap_list
 425 will be populated with a list of
 426 .Vt nvpair_t
 427 exactly as specified by
 428 .Fn be_get_bootenv_props .
 429 .Pp
 430 The
 431 .Fn be_prop_list_free
 432 function will free the property list.
 433 .Sh DIAGNOSTICS
 434 Upon error, one of the following values will be returned.
 435 .\" TODO: make each entry on its own line.
 436 .Bd -ragged -offset indent
 437 BE_ERR_SUCCESS,
 438 BE_ERR_INVALIDNAME,
 439 BE_ERR_EXISTS,
 440 BE_ERR_NOENT,
 441 BE_ERR_PERMS,
 442 BE_ERR_DESTROYACT,
 443 BE_ERR_DESTROYMNT,
 444 BE_ERR_BADPATH,
 445 BE_ERR_PATHBUSY,
 446 BE_ERR_PATHLEN,
 447 BE_ERR_INVORIGIN,
 448 BE_ERR_NOORIGIN,
 449 BE_ERR_MOUNTED,
 450 BE_ERR_NOMOUNT,
 451 BE_ERR_ZFSOPEN,
 452 BE_ERR_ZFSCLONE,
 453 BE_ERR_IO,
 454 BE_ERR_NOPOOL,
 455 BE_ERR_NOMEM,
 456 BE_ERR_UNKNOWN
 457 .Ed
 458 .Sh SEE ALSO
 459 .Xr be 1
 460 .Sh HISTORY
 461 .Nm
 462 and its corresponding command,
 463 .Xr bectl 8 ,
 464 were written as a 2017 Google Summer of Code project with Allan Jude serving
 465 as a mentor.
 466 Later work was done by
 467 .An Kyle Evans Aq Mt kevans@FreeBSD.org .