2 .\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD
4 .\" Copyright (c) 2017 Kyle Kneitinger
5 .\" All rights reserved.
6 .\" Copyright (c) 2018 Kyle Evans <kevans@FreeBSD.org>
8 .\" Redistribution and use in source and binary forms, with or without
9 .\" modification, are permitted provided that the following conditions
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.
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
36 .Nd library for creating, destroying and modifying ZFS boot environments
41 .Ft "libbe_handle_t *hdl" Ns
45 .Fn libbe_close "libbe_handle_t *hdl"
48 .Fn be_active_name "libbe_handle_t *hdl"
51 .Fn be_active_path "libbe_handle_t *hdl"
54 .Fn be_nextboot_name "libbe_handle_t *hdl"
57 .Fn be_nextboot_path "libbe_handle_t *hdl"
60 .Fn be_root_path "libbe_handle_t *hdl"
63 .Fn be_create "libbe_handle_t *hdl" "const char *be_name"
66 .Fn be_create_from_existing "libbe_handle_t *hdl" "const char *be_name" "const char *be_origin"
69 .Fn be_create_from_existing_snap "libbe_handle_t *hdl" "const char *be_name" "const char *snap"
72 .Fn be_rename "libbe_handle_t *hdl" "const char *be_old" "const char *be_new"
75 .Fn be_activate "libbe_handle_t *hdl" "const char *be_name" "bool temporary"
77 .Fn be_destroy "libbe_handle_t *hdl" "const char *be_name" "int options"
80 .Fn be_nicenum "uint64_t num" "char *buf" "size_t bufsz"
82 .\" TODO: Write up of mount options
84 .\" BE_MNT_FORCE = 1 << 0,
85 .\" BE_MNT_DEEP = 1 << 1,
88 .Fn be_mount "libbe_handle_t *hdl" "char *be_name" "char *mntpoint" "int flags" "char *result"
91 .Fn be_mounted_at "libbe_handle_t *hdl" "const char *path" "nvlist_t *details"
94 .Fn be_unmount "libbe_handle_t *hdl" "char *be_name" "int flags"
97 .Fn libbe_errno "libbe_handle_t *hdl"
100 .Fn libbe_error_description "libbe_handle_t *hdl"
103 .Fn libbe_print_on_error "libbe_handle_t *hdl" "bool doprint"
106 .Fn be_root_concat "libbe_handle_t *hdl" "const char *be_name" "char *result"
109 .Fn be_validate_name "libbe_handle_t *hdl" "const char *be_name"
112 .Fn be_validate_snap "libbe_handle_t *hdl" "const char *snap"
115 .Fn be_exists "libbe_handle_t *hdl" "char *be_name"
118 .Fn be_export "libbe_handle_t *hdl" "const char *be_name" "int fd"
121 .Fn be_import "libbe_handle_t *hdl" "const char *be_name" "int fd"
124 .Fn be_prop_list_alloc "nvlist_t **prop_list"
127 .Fn be_get_bootenv_props "libbe_handle_t *hdl" "nvlist_t *be_list"
130 .Fn be_get_dataset_props "libbe_handle_t *hdl" "const char *ds_name" "nvlist_t *props"
133 .Fn be_get_dataset_snapshots "libbe_handle_t *hdl" "const char *ds_name" "nvlist_t *snap_list"
136 .Fn be_prop_list_free "nvlist_t *prop_list"
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.
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.
146 may be configured to print the corresponding error message to
148 when an error is encountered with
149 .Fn libbe_print_on_error .
151 All functions returning an
153 return 0 on success, or a
155 errno otherwise as described in
163 .Vt "libbe_handle_t *"
167 An error may occur if:
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
174 fails to open the zpool the active boot environment resides on, or
176 fails to locate the boot environment that is currently mounted.
181 function frees all resources previously acquired in
183 invalidating the handle in the process.
187 function returns the name of the currently booted boot environment,
191 function returns the full path of the currently booted boot environment.
195 function returns the name of the boot environment that will be active on reboot.
199 function returns the full path of the boot environment that will be
204 function returns the boot environment root path.
208 function creates a boot environment with the given name.
209 It will be created from a snapshot of the currently booted boot environment.
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.
219 .Fn be_create_from_existing_snap
220 function creates a boot environment with the given name from an existing
225 function renames a boot environment.
229 function makes a boot environment active on the next boot.
232 flag is set, then it will be active for the next boot only, as done by
234 Next boot functionality is currently only available when booting in x86 BIOS
239 function will recursively destroy the given boot environment.
240 It will not destroy a mounted boot environment unless the
249 in a traditional ZFS humanized format, similar to
250 .Xr humanize_number 3 .
251 This function effectively proxies
257 function will mount the given boot environment.
262 a mount point will be generated in
270 the final mount point will be copied into it.
281 function will check if there is a boot environment mounted at the given
287 it will be populated with a list of the mounted dataset's properties.
288 This list of properties matches the properties collected by
289 .Fn be_get_bootenv_props .
293 function will unmount the given boot environment.
309 .Fn libbe_error_description
310 function returns a string description of the currently set
315 .Fn libbe_print_on_error
316 function will change whether or not
318 prints the description of any encountered error to
325 function will concatenate the boot environment root and the given boot
326 environment name into
331 function will validate the given boot environment name.
335 function will validate the given snapshot name.
336 The snapshot must have a valid name, exist, and have a mountpoint of
338 This function does not set the internal library error state.
342 function will check whether the given boot environment exists and has a
348 function will export the given boot environment to the file specified by
350 A snapshot will be created of the boot environment prior to export.
354 function will import the boot environment in the file specified by
360 .Fn be_prop_list_alloc
361 function allocates a property list suitable for passing to
362 .Fn be_get_bootenv_props ,
363 .Fn be_get_dataset_props ,
365 .Fn be_get_dataset_snapshots .
366 It should be freed later by
367 .Fa be_prop_list_free .
370 .Fn be_get_bootenv_props
371 function will populate
375 of boot environment names paired with an
378 The following properties are currently collected as appropriate:
379 .Bl -column "Returned name"
380 .It Sy Returned name Ta Sy Description
382 .It name Ta Boot environment name
383 .It mounted Ta Current mount point
384 .It mountpoint Ta Do mountpoint Dc property
385 .It origin Ta Do origin Dc property
386 .It creation Ta Do creation Dc property
387 .It active Ta Currently booted environment
388 .It used Ta Literal Do used Dc property
389 .It usedds Ta Literal Do usedds Dc property
390 .It usedsnap Ta Literal Do usedrefreserv Dc property
391 .It referenced Ta Literal Do referenced Dc property
392 .It nextboot Ta Active on next boot
401 returned values will always be present.
402 All other properties may be omitted if not available.
405 .Fn be_get_dataset_props
406 function will get properties of the specified dataset.
408 is populated directly with a list of the properties as returned by
409 .Fn be_get_bootenv_props .
412 .Fn be_get_dataset_snapshots
413 function will retrieve all snapshots of the given dataset.
415 will be populated with a list of
417 exactly as specified by
418 .Fn be_get_bootenv_props .
421 .Fn be_prop_list_free
422 function will free the property list.
424 Upon error, one of the following values will be returned.
425 .\" TODO: make each entry on its own line.
426 .Bd -ragged -offset indent
452 and its corresponding command,
454 were written as a 2017 Google Summer of Code project with Allan Jude serving
456 Later work was done by
457 .An Kyle Evans Aq Mt kevans@FreeBSD.org .
461 function does not destroy the temporary boot environment it creates for import,
462 because the snapshot created to do the import may not be deleted since it is the
463 origin of the new boot environment.