aboutsummaryrefslogtreecommitdiff
path: root/lib/libbe/libbe.3
blob: fe2ddaaf18199394a0d60d0185684a37ac9f7d5f (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
.\"
.\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD
.\"
.\" Copyright (c) 2017 Kyle Kneitinger
.\" All rights reserved.
.\" Copyright (c) 2018 Kyle Evans <kevans@FreeBSD.org>
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD$
.\"
.Dd April 22, 2019
.Dt LIBBE 3
.Os
.Sh NAME
.Nm libbe
.Nd library for creating, destroying and modifying ZFS boot environments
.Sh LIBRARY
.Lb libbe
.Sh SYNOPSIS
.In be.h
.Ft "libbe_handle_t *hdl" Ns
.Fn libbe_init "const char *be_root"
.Pp
.Ft void
.Fn libbe_close "libbe_handle_t *hdl"
.Pp
.Ft const char * Ns
.Fn be_active_name "libbe_handle_t *hdl"
.Pp
.Ft const char * Ns
.Fn be_active_path "libbe_handle_t *hdl"
.Pp
.Ft const char * Ns
.Fn be_nextboot_name "libbe_handle_t *hdl"
.Pp
.Ft const char * Ns
.Fn be_nextboot_path "libbe_handle_t *hdl"
.Pp
.Ft const char * Ns
.Fn be_root_path "libbe_handle_t *hdl"
.Pp
.Ft int
.Fn be_create "libbe_handle_t *hdl" "const char *be_name"
.Pp
.Ft int
.Fn be_create_depth "libbe_handle_t *hdl" "const char *be_name" "const char *snap" "int depth"
.Pp
.Ft int
.Fn be_create_from_existing "libbe_handle_t *hdl" "const char *be_name" "const char *be_origin"
.Pp
.Ft int
.Fn be_create_from_existing_snap "libbe_handle_t *hdl" "const char *be_name" "const char *snap"
.Pp
.Ft int
.Fn be_rename "libbe_handle_t *hdl" "const char *be_old" "const char *be_new"
.Pp
.Ft int
.Fn be_activate "libbe_handle_t *hdl" "const char *be_name" "bool temporary"
.Ft int
.Fn be_destroy "libbe_handle_t *hdl" "const char *be_name" "int options"
.Pp
.Ft void
.Fn be_nicenum "uint64_t num" "char *buf" "size_t bufsz"
.Pp
.\" TODO: Write up of mount options
.\" typedef enum {
.\"	BE_MNT_FORCE		= 1 << 0,
.\"	BE_MNT_DEEP		= 1 << 1,
.\" } be_mount_opt_t
.Ft int
.Fn be_mount "libbe_handle_t *hdl" "char *be_name" "char *mntpoint" "int flags" "char *result"
.Pp
.Ft int
.Fn be_mounted_at "libbe_handle_t *hdl" "const char *path" "nvlist_t *details"
.Pp
.Ft int
.Fn be_unmount "libbe_handle_t *hdl" "char *be_name" "int flags"
.Pp
.Ft int
.Fn libbe_errno "libbe_handle_t *hdl"
.Pp
.Ft const char * Ns
.Fn libbe_error_description "libbe_handle_t *hdl"
.Pp
.Ft void
.Fn libbe_print_on_error "libbe_handle_t *hdl" "bool doprint"
.Pp
.Ft int
.Fn be_root_concat "libbe_handle_t *hdl" "const char *be_name" "char *result"
.Pp
.Ft int
.Fn be_validate_name "libbe_handle_t *hdl" "const char *be_name"
.Pp
.Ft int
.Fn be_validate_snap "libbe_handle_t *hdl" "const char *snap"
.Pp
.Ft int
.Fn be_exists "libbe_handle_t *hdl" "char *be_name"
.Pp
.Ft int
.Fn be_export "libbe_handle_t *hdl" "const char *be_name" "int fd"
.Pp
.Ft int
.Fn be_import "libbe_handle_t *hdl" "const char *be_name" "int fd"
.Pp
.Ft int
.Fn be_prop_list_alloc "nvlist_t **prop_list"
.Pp
.Ft int
.Fn be_get_bootenv_props "libbe_handle_t *hdl" "nvlist_t *be_list"
.Pp
.Ft int
.Fn be_get_dataset_props "libbe_handle_t *hdl" "const char *ds_name" "nvlist_t *props"
.Pp
.Ft int
.Fn be_get_dataset_snapshots "libbe_handle_t *hdl" "const char *ds_name" "nvlist_t *snap_list"
.Pp
.Ft void
.Fn be_prop_list_free "nvlist_t *prop_list"
.Sh DESCRIPTION
.Nm
interfaces with libzfs to provide a set of functions for various operations
regarding ZFS boot environments including "deep" boot environments in which
a boot environments has child datasets.
.Pp
A context structure is passed to each function, allowing for a small amount
of state to be retained, such as errors from previous operations.
.Nm
may be configured to print the corresponding error message to
.Dv stderr
when an error is encountered with
.Fn libbe_print_on_error .
.Pp
All functions returning an
.Vt int
return 0 on success, or a
.Nm
errno otherwise as described in
.Sx DIAGNOSTICS .
.Pp
The
.Fn libbe_init
function takes an optional BE root and initializes
.Nm ,
returning a
.Vt "libbe_handle_t *"
on success, or
.Dv NULL
on error.
If a BE root is supplied,
.Nm
will only operate out of that pool and BE root.
An error may occur if:
.Bl -column
.It /boot and / are not on the same filesystem and device,
.It libzfs fails to initialize,
.It The system has not been properly booted with a ZFS boot
environment,
.It Nm
fails to open the zpool the active boot environment resides on, or
.It Nm
fails to locate the boot environment that is currently mounted.
.El
.Pp
The
.Fn libbe_close
function frees all resources previously acquired in
.Fn libbe_init ,
invalidating the handle in the process.
.Pp
The
.Fn be_active_name
function returns the name of the currently booted boot environment.
This boot environment may not belong to the same BE root as the root libbe
is operating on!
.Pp
The
.Fn be_active_path
function returns the full path of the currently booted boot environment.
This boot environment may not belong to the same BE root as the root libbe
is operating on!
.Pp
The
.Fn be_nextboot_name
function returns the name of the boot environment that will be active on reboot.
.Pp
The
.Fn be_nextboot_path
function returns the full path of the boot environment that will be
active on reboot.
.Pp
The
.Fn be_root_path
function returns the boot environment root path.
.Pp
The
.Fn be_create
function creates a boot environment with the given name.
The new boot environment will be created from a recursive snapshot of the
currently booted boot environment.
.Pp
The
.Fn be_create_depth
function creates a boot environment with the given name from an existing
snapshot.
The depth parameter specifies the depth of recursion that will be cloned from
the existing snapshot.
A depth of '0' is no recursion and '-1' is unlimited (i.e., a recursive boot
environment).
.Pp
The
.Fn be_create_from_existing
function creates a boot environment with the given name from the name of an
existing boot environment.
A recursive snapshot will be made of the origin boot environment, and the new
boot environment will be created from that.
.Pp
The
.Fn be_create_from_existing_snap
function creates a recursive boot environment with the given name from an
existing snapshot.
.Pp
The
.Fn be_rename
function renames a boot environment without unmounting it, as if renamed with
the
.Fl u
argument were passed to
.Nm zfs
.Cm rename
.Pp
The
.Fn be_activate
function makes a boot environment active on the next boot.
If the
.Fa temporary
flag is set, then it will be active for the next boot only, as done by
.Xr zfsbootcfg 8 .
Next boot functionality is currently only available when booting in x86 BIOS
mode.
.Pp
The
.Fn be_destroy
function will recursively destroy the given boot environment.
It will not destroy a mounted boot environment unless the
.Dv BE_DESTROY_FORCE
option is set in
.Fa options .
If the
.Dv BE_DESTROY_ORIGIN
option is set in
.Fa options ,
the
.Fn be_destroy
function will destroy the origin snapshot to this boot environment as well.
.Pp
The
.Fn be_nicenum
function will format
.Fa name
in a traditional ZFS humanized format, similar to
.Xr humanize_number 3 .
This function effectively proxies
.Fn zfs_nicenum
from libzfs.
.Pp
The
.Fn be_mount
function will mount the given boot environment.
If
.Fa mountpoint
is
.Dv NULL ,
a mount point will be generated in
.Pa /tmp
using
.Xr mkdtemp 3 .
If
.Fa result
is not
.Dv NULL ,
it should be large enough to accommodate
.Dv BE_MAXPATHLEN
including the null terminator.
the final mount point will be copied into it.
Setting the
.Dv BE_MNT_FORCE
flag will pass
.Dv MNT_FORCE
to the underlying
.Xr mount 2
call.
.Pp
The
.Fn be_mounted_at
function will check if there is a boot environment mounted at the given
.Fa path .
If
.Fa details
is not
.Dv NULL ,
it will be populated with a list of the mounted dataset's properties.
This list of properties matches the properties collected by
.Fn be_get_bootenv_props .
.Pp
The
.Fn be_unmount
function will unmount the given boot environment.
Setting the
.Dv BE_MNT_FORCE
flag will pass
.Dv MNT_FORCE
to the underlying
.Xr mount 2
call.
.Pp
The
.Fn libbe_errno
function returns the
.Nm
errno.
.Pp
The
.Fn libbe_error_description
function returns a string description of the currently set
.Nm
errno.
.Pp
The
.Fn libbe_print_on_error
function will change whether or not
.Nm
prints the description of any encountered error to
.Dv stderr ,
based on
.Fa doprint .
.Pp
The
.Fn be_root_concat
function will concatenate the boot environment root and the given boot
environment name into
.Fa result .
.Pp
The
.Fn be_validate_name
function will validate the given boot environment name for both length
restrictions as well as valid character restrictions.
This function does not set the internal library error state.
.Pp
The
.Fn be_validate_snap
function will validate the given snapshot name.
The snapshot must have a valid name, exist, and have a mountpoint of
.Pa / .
This function does not set the internal library error state.
.Pp
The
.Fn be_exists
function will check whether the given boot environment exists and has a
mountpoint of
.Pa / .
This function does not set the internal library error state, but will return
the appropriate error.
.Pp
The
.Fn be_export
function will export the given boot environment to the file specified by
.Fa fd .
A snapshot will be created of the boot environment prior to export.
.Pp
The
.Fn be_import
function will import the boot environment in the file specified by
.Fa fd ,
and give it the name
.Fa be_name .
.Pp
The
.Fn be_prop_list_alloc
function allocates a property list suitable for passing to
.Fn be_get_bootenv_props ,
.Fn be_get_dataset_props ,
or
.Fn be_get_dataset_snapshots .
It should be freed later by
.Fa be_prop_list_free .
.Pp
The
.Fn be_get_bootenv_props
function will populate
.Fa be_list
with
.Vt nvpair_t
of boot environment names paired with an
.Vt nvlist_t
of their properties.
The following properties are currently collected as appropriate:
.Bl -column "Returned name"
.It Sy Returned name Ta Sy Description
.It dataset Ta -
.It name Ta Boot environment name
.It mounted Ta Current mount point
.It mountpoint Ta Do mountpoint Dc property
.It origin Ta Do origin Dc property
.It creation Ta Do creation Dc property
.It active Ta Currently booted environment
.It used Ta Literal Do used Dc property
.It usedds Ta Literal Do usedds Dc property
.It usedsnap Ta Literal Do usedrefreserv Dc property
.It referenced Ta Literal Do referenced Dc property
.It nextboot Ta Active on next boot
.El
.Pp
Only the
.Dq dataset ,
.Dq name ,
.Dq active ,
and
.Dq nextboot
returned values will always be present.
All other properties may be omitted if not available.
.Pp
The
.Fn be_get_dataset_props
function will get properties of the specified dataset.
.Fa props
is populated directly with a list of the properties as returned by
.Fn be_get_bootenv_props .
.Pp
The
.Fn be_get_dataset_snapshots
function will retrieve all snapshots of the given dataset.
.Fa snap_list
will be populated with a list of
.Vt nvpair_t
exactly as specified by
.Fn be_get_bootenv_props .
.Pp
The
.Fn be_prop_list_free
function will free the property list.
.Sh DIAGNOSTICS
Upon error, one of the following values will be returned:
.Bl -dash -offset indent -compact
.It
BE_ERR_SUCCESS
.It
BE_ERR_INVALIDNAME
.It
BE_ERR_EXISTS
.It
BE_ERR_NOENT
.It
BE_ERR_PERMS
.It
BE_ERR_DESTROYACT
.It
BE_ERR_DESTROYMNT
.It
BE_ERR_BADPATH
.It
BE_ERR_PATHBUSY
.It
BE_ERR_PATHLEN
.It
BE_ERR_BADMOUNT
.It
BE_ERR_NOORIGIN
.It
BE_ERR_MOUNTED
.It
BE_ERR_NOMOUNT
.It
BE_ERR_ZFSOPEN
.It
BE_ERR_ZFSCLONE
.It
BE_ERR_IO
.It
BE_ERR_NOPOOL
.It
BE_ERR_NOMEM
.It
BE_ERR_UNKNOWN
.It
BE_ERR_INVORIGIN
.El
.Sh SEE ALSO
.Xr bectl 8
.Sh HISTORY
.Nm
and its corresponding command,
.Xr bectl 8 ,
were written as a 2017 Google Summer of Code project with Allan Jude serving
as a mentor.
Later work was done by
.An Kyle Evans Aq Mt kevans@FreeBSD.org .