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