2 .\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD
4 .\" Copyright (c) 2017 Kyle Kneitinger
5 .\" Copyright (c) 2018 Kyle Evans <kevans@FreeBSD.org>
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
10 .\" 1. Redistributions of source code must retain the above copyright
11 .\" notice, this list of conditions and the following disclaimer.
12 .\" 2. Redistributions in binary form must reproduce the above copyright
13 .\" notice, this list of conditions and the following disclaimer in the
14 .\" documentation and/or other materials provided with the distribution.
16 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
35 .Nd library for creating, destroying and modifying ZFS boot environments
40 .Ft "libbe_handle_t *hdl" Ns
41 .Fn libbe_init "const char *be_root"
44 .Fn libbe_close "libbe_handle_t *hdl"
47 .Fn be_active_name "libbe_handle_t *hdl"
50 .Fn be_active_path "libbe_handle_t *hdl"
53 .Fn be_nextboot_name "libbe_handle_t *hdl"
56 .Fn be_nextboot_path "libbe_handle_t *hdl"
59 .Fn be_root_path "libbe_handle_t *hdl"
62 .Fn be_is_auto_snapshot_name "libbe_handle_t *hdl" "const char *snap"
65 .Fn be_create "libbe_handle_t *hdl" "const char *be_name"
68 .Fn be_create_depth "libbe_handle_t *hdl" "const char *be_name" "const char *snap" "int depth"
71 .Fn be_create_from_existing "libbe_handle_t *hdl" "const char *be_name" "const char *be_origin"
74 .Fn be_create_from_existing_snap "libbe_handle_t *hdl" "const char *be_name" "const char *snap"
77 .Fn be_rename "libbe_handle_t *hdl" "const char *be_old" "const char *be_new"
80 .Fn be_activate "libbe_handle_t *hdl" "const char *be_name" "bool temporary"
82 .Fn be_destroy "libbe_handle_t *hdl" "const char *be_name" "int options"
85 .Fn be_nicenum "uint64_t num" "char *buf" "size_t bufsz"
87 .\" TODO: Write up of mount options
89 .\" BE_MNT_FORCE = 1 << 0,
90 .\" BE_MNT_DEEP = 1 << 1,
93 .Fn be_mount "libbe_handle_t *hdl" "char *be_name" "char *mntpoint" "int flags" "char *result"
96 .Fn be_mounted_at "libbe_handle_t *hdl" "const char *path" "nvlist_t *details"
99 .Fn be_unmount "libbe_handle_t *hdl" "char *be_name" "int flags"
102 .Fn libbe_errno "libbe_handle_t *hdl"
105 .Fn libbe_error_description "libbe_handle_t *hdl"
108 .Fn libbe_print_on_error "libbe_handle_t *hdl" "bool doprint"
111 .Fn be_root_concat "libbe_handle_t *hdl" "const char *be_name" "char *result"
114 .Fn be_validate_name "libbe_handle_t *hdl" "const char *be_name"
117 .Fn be_validate_snap "libbe_handle_t *hdl" "const char *snap"
120 .Fn be_exists "libbe_handle_t *hdl" "char *be_name"
123 .Fn be_export "libbe_handle_t *hdl" "const char *be_name" "int fd"
126 .Fn be_import "libbe_handle_t *hdl" "const char *be_name" "int fd"
129 .Fn be_prop_list_alloc "nvlist_t **prop_list"
132 .Fn be_get_bootenv_props "libbe_handle_t *hdl" "nvlist_t *be_list"
135 .Fn be_get_dataset_props "libbe_handle_t *hdl" "const char *ds_name" "nvlist_t *props"
138 .Fn be_get_dataset_snapshots "libbe_handle_t *hdl" "const char *ds_name" "nvlist_t *snap_list"
141 .Fn be_prop_list_free "nvlist_t *prop_list"
144 interfaces with libzfs to provide a set of functions for various operations
145 regarding ZFS boot environments including "deep" boot environments in which
146 a boot environments has child datasets.
148 A context structure is passed to each function, allowing for a small amount
149 of state to be retained, such as errors from previous operations.
151 may be configured to print the corresponding error message to
153 when an error is encountered with
154 .Fn libbe_print_on_error .
156 All functions returning an
158 return 0 on success, or a
160 errno otherwise as described in
165 function takes an optional BE root and initializes
168 .Vt "libbe_handle_t *"
172 If a BE root is supplied,
174 will only operate out of that pool and BE root.
175 An error may occur if:
177 .It /boot and / are not on the same filesystem and device,
178 .It libzfs fails to initialize,
179 .It The system has not been properly booted with a ZFS boot
182 fails to open the zpool the active boot environment resides on, or
184 fails to locate the boot environment that is currently mounted.
189 function frees all resources previously acquired in
191 invalidating the handle in the process.
195 function returns the name of the currently booted boot environment.
196 This boot environment may not belong to the same BE root as the root libbe
201 function returns the full path of the currently booted boot environment.
202 This boot environment may not belong to the same BE root as the root libbe
207 function returns the name of the boot environment that will be active on reboot.
211 function returns the full path of the boot environment that will be
216 function returns the boot environment root path.
219 .Fn be_is_auto_snapshot_name
220 function is used to determine if the given snapshot name matches the format that
223 function will use by default if it is not given a snapshot name to use.
226 if the name matches the format, and
232 function creates a boot environment with the given name.
233 The new boot environment will be created from a recursive snapshot of the
234 currently booted boot environment.
238 function creates a boot environment with the given name from an existing
240 The depth parameter specifies the depth of recursion that will be cloned from
241 the existing snapshot.
242 A depth of '0' is no recursion and '-1' is unlimited (i.e., a recursive boot
246 .Fn be_create_from_existing
247 function creates a boot environment with the given name from the name of an
248 existing boot environment.
249 A recursive snapshot will be made of the origin boot environment, and the new
250 boot environment will be created from that.
253 .Fn be_create_from_existing_snap
254 function creates a recursive boot environment with the given name from an
259 function renames a boot environment without unmounting it, as if renamed with
262 argument were passed to
268 function makes a boot environment active on the next boot.
271 flag is set, then it will be active for the next boot only, as done by
273 Next boot functionality is currently only available when booting in x86 BIOS
278 function will recursively destroy the given boot environment.
279 It will not destroy a mounted boot environment unless the
284 .Dv BE_DESTROY_ORIGIN
289 function will destroy the origin snapshot to this boot environment as well.
295 in a traditional ZFS humanized format, similar to
296 .Xr humanize_number 3 .
297 This function effectively proxies
303 function will mount the given boot environment.
308 a mount point will be generated in
316 it should be large enough to accommodate
318 including the null terminator.
319 the final mount point will be copied into it.
330 function will check if there is a boot environment mounted at the given
336 it will be populated with a list of the mounted dataset's properties.
337 This list of properties matches the properties collected by
338 .Fn be_get_bootenv_props .
342 function will unmount the given boot environment.
358 .Fn libbe_error_description
359 function returns a string description of the currently set
364 .Fn libbe_print_on_error
365 function will change whether or not
367 prints the description of any encountered error to
374 function will concatenate the boot environment root and the given boot
375 environment name into
380 function will validate the given boot environment name for both length
381 restrictions as well as valid character restrictions.
382 This function does not set the internal library error state.
386 function will validate the given snapshot name.
387 The snapshot must have a valid name, exist, and have a mountpoint of
389 This function does not set the internal library error state.
393 function will check whether the given boot environment exists and has a
396 This function does not set the internal library error state, but will return
397 the appropriate error.
401 function will export the given boot environment to the file specified by
403 A snapshot will be created of the boot environment prior to export.
407 function will import the boot environment in the file specified by
413 .Fn be_prop_list_alloc
414 function allocates a property list suitable for passing to
415 .Fn be_get_bootenv_props ,
416 .Fn be_get_dataset_props ,
418 .Fn be_get_dataset_snapshots .
419 It should be freed later by
420 .Fa be_prop_list_free .
423 .Fn be_get_bootenv_props
424 function will populate
428 of boot environment names paired with an
431 The following properties are currently collected as appropriate:
432 .Bl -column "Returned name"
433 .It Sy Returned name Ta Sy Description
435 .It name Ta Boot environment name
436 .It mounted Ta Current mount point
437 .It mountpoint Ta Do mountpoint Dc property
438 .It origin Ta Do origin Dc property
439 .It creation Ta Do creation Dc property
440 .It active Ta Currently booted environment
441 .It used Ta Literal Do used Dc property
442 .It usedds Ta Literal Do usedds Dc property
443 .It usedsnap Ta Literal Do usedrefreserv Dc property
444 .It referenced Ta Literal Do referenced Dc property
445 .It nextboot Ta Active on next boot
454 returned values will always be present.
455 All other properties may be omitted if not available.
458 .Fn be_get_dataset_props
459 function will get properties of the specified dataset.
461 is populated directly with a list of the properties as returned by
462 .Fn be_get_bootenv_props .
465 .Fn be_get_dataset_snapshots
466 function will retrieve all snapshots of the given dataset.
468 will be populated with a list of
470 exactly as specified by
471 .Fn be_get_bootenv_props .
474 .Fn be_prop_list_free
475 function will free the property list.
477 Upon error, one of the following values will be returned:
478 .Bl -dash -offset indent -compact
526 and its corresponding command,
528 were written as a 2017 Google Summer of Code project with Allan Jude serving
530 Later work was done by
531 .An Kyle Evans Aq Mt kevans@FreeBSD.org .