libbe(3): Brain dump...
This commit is contained in:
parent
c3c5a72e4e
commit
7c2cc9b222
Notes:
svn2git
2020-12-20 02:59:44 +00:00
svn path=/projects/bectl/; revision=337601
@ -3,6 +3,7 @@
|
||||
.\"
|
||||
.\" 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
|
||||
@ -34,16 +35,105 @@
|
||||
.Nm libbe
|
||||
.Nd library for creating, destroying and modifying ZFS boot environments
|
||||
.Sh LIBRARY
|
||||
.Lb be
|
||||
.Lb libbe
|
||||
.Sh SYNOPSIS
|
||||
.In be.h
|
||||
.Ft "libbe_handle_t *hdl" Ns
|
||||
.Fn libbe_init void
|
||||
.Pp
|
||||
Function prototypes are given in the
|
||||
.Sx FUNCTION OVERVIEW
|
||||
section.
|
||||
.Ft void
|
||||
.Fn libbe_close "libbe_handle_t *hdl"
|
||||
.Pp
|
||||
Applications using this interface must be linked with
|
||||
.Fl l Ns Ar be
|
||||
.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_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 bool
|
||||
.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
|
||||
@ -52,108 +142,287 @@ 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.
|
||||
.\" TODO: describe break on err functionality
|
||||
.Sh FUNCTION OVERVIEW
|
||||
.Ft "libbe_handle_t *" Ns
|
||||
.Fn libbe_init void ;
|
||||
.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
|
||||
.Ft void
|
||||
.Fn libbe_close "libbe_handle_t *" ;
|
||||
All functions returning an
|
||||
.Vt int
|
||||
return 0 on success, or a
|
||||
.Nm
|
||||
errno otherwise as described in
|
||||
.Sx DIAGNOSTICS .
|
||||
.Pp
|
||||
.Ft const char * Ns
|
||||
.Fn be_active_name "libbe_handle_t *" ;
|
||||
The
|
||||
.Fn libbe_init
|
||||
function initializes
|
||||
.Nm ,
|
||||
returning a
|
||||
.Vt "libbe_handle_t *"
|
||||
on success, or
|
||||
.Dv NULL
|
||||
on error.
|
||||
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
|
||||
.Ft const char * Ns
|
||||
.Fn be_active_path "libbe_handle_t *" ;
|
||||
The
|
||||
.Fn libbe_close
|
||||
function frees all resources previously acquired in
|
||||
.Fn libbe_init ,
|
||||
invalidating the handle in the process.
|
||||
.Pp
|
||||
.Ft const char * Ns
|
||||
.Fn be_nextboot_name "libbe_handle_t *" ;
|
||||
The
|
||||
.Fn be_active_name
|
||||
function returns the name of the currently booted boot environment,
|
||||
.Pp
|
||||
.Ft const char * Ns
|
||||
.Fn be_nextboot_path "libbe_handle_t *" ;
|
||||
The
|
||||
.Fn be_active_path
|
||||
function returns the full path of the currently booted boot environment.
|
||||
.Pp
|
||||
.Ft const char * Ns
|
||||
.Fn be_root_path "libbe_handle_t *" ;
|
||||
The
|
||||
.Fn be_nextboot_name
|
||||
function returns the name of the boot environment that will be active on reboot.
|
||||
.Pp
|
||||
.Ft int
|
||||
.Fn be_create "libbe_handle_t *" "const char *" ;
|
||||
The
|
||||
.Fn be_nextboot_path
|
||||
function returns the full path of the boot environment that will be
|
||||
active on reboot.
|
||||
.Pp
|
||||
.Ft int
|
||||
.Fn be_create_from_existing "libbe_handle_t *" "const char *" "const char *" ;
|
||||
The
|
||||
.Fn be_root_path
|
||||
function returns the boot environment root path.
|
||||
.Pp
|
||||
.Ft int
|
||||
.Fn be_create_from_existing_snap "libbe_handle_t *" "const char *" "const char *" ;
|
||||
The
|
||||
.Fn be_create
|
||||
function creates a boot environment with the given name.
|
||||
It will be created from a snapshot of the currently booted boot environment.
|
||||
.Pp
|
||||
.Ft int
|
||||
.Fn be_rename "libbe_handle_t *" "const char *" "const char *" ;
|
||||
The
|
||||
.Fn be_create_from_existing
|
||||
function creates a boot environment with the given name from the name of an
|
||||
existing boot environment.
|
||||
A snapshot will be made of the base boot environment, and the new boot
|
||||
environment will be created from that.
|
||||
.Pp
|
||||
.Ft int
|
||||
.Fn be_activate "libbe_handle_t *" "const char *" "bool" ;
|
||||
.\" TODO: Write up of destroy options
|
||||
.\" typedef enum {
|
||||
.\" BE_DESTROY_FORCE = 1 << 0,
|
||||
.\" } be_destroy_opt_t;
|
||||
.Ft int
|
||||
.Fn be_destroy "libbe_handle_t *" "const char *" "int" ;
|
||||
The
|
||||
.Fn be_create_from_existing_snap
|
||||
function creates a boot environment with the given name from an existing
|
||||
snapshot.
|
||||
.Pp
|
||||
.Ft void
|
||||
.Fn be_nicenum uint64_t" "char *" "size_t" ;
|
||||
The
|
||||
.Fn be_rename
|
||||
function renames a boot environment.
|
||||
.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 *" "char *" "char *" "int" ;
|
||||
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
|
||||
.Ft int
|
||||
.Fn be_mounted_at "libbe_handle_t *" "const char *" "nvlist_t" ;
|
||||
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 .
|
||||
.Pp
|
||||
.Ft int
|
||||
.Fn be_unmount "libbe_handle_t *" "char *" "int" ;
|
||||
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
|
||||
.Ft int
|
||||
.Fn libbe_errno "libbe_handle_t *" ;
|
||||
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 ,
|
||||
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
|
||||
.Ft const char * Ns
|
||||
.Fn libbe_error_description "libbe_handle_t *" ;
|
||||
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
|
||||
.Ft void
|
||||
.Fn libbe_print_on_error "libbe_handle_t *" "bool" ;
|
||||
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
|
||||
.Ft int
|
||||
.Fn be_root_concat "libbe_handle_t *" "const char *" "char *" ;
|
||||
The
|
||||
.Fn libbe_errno
|
||||
function returns the
|
||||
.Nm
|
||||
errno.
|
||||
.Pp
|
||||
.Ft int
|
||||
.Fn be_validate_name "libbe_handle_t *" "const char *" ;
|
||||
The
|
||||
.Fn libbe_error_description
|
||||
function returns a string description of the currently set
|
||||
.Nm
|
||||
errno.
|
||||
.Pp
|
||||
.Ft int
|
||||
.Fn be_validate_snap "libbe_handle_t *" "const char *" ;
|
||||
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
|
||||
.Ft bool
|
||||
.Fn be_exists "libbe_handle_t *" "char *" ;
|
||||
The
|
||||
.Fn be_root_concat
|
||||
function will concatenate the boot environment root and the given boot
|
||||
environment name into
|
||||
.Fa result .
|
||||
.Pp
|
||||
.Ft int
|
||||
.Fn be_export "libbe_handle_t *" "const char *" "int fd" ;
|
||||
The
|
||||
.Fn be_validate_name
|
||||
function will validate the given boot environment name.
|
||||
.Pp
|
||||
.Ft int
|
||||
.Fn be_import "libbe_handle_t *" "const char *" "int fd" ;
|
||||
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
|
||||
.Ft int
|
||||
.Fn be_prop_list_alloc "nvlist_t **" ;
|
||||
The
|
||||
.Fn be_exists
|
||||
function will check whether the given boot environment exists and has a
|
||||
mountpoint of
|
||||
.Pa / .
|
||||
.Pp
|
||||
.Ft int
|
||||
.Fn be_get_bootenv_props "libbe_handle_t *" "nvlist_t *" ;
|
||||
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
|
||||
.Ft int
|
||||
.Fn be_get_dataset_props "libbe_handle_t *" "const char *" "nvlist_t *" ;
|
||||
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
|
||||
.Ft int
|
||||
.Fn be_get_dataset_snapshots "libbe_handle_t *" "const char *" "nvlist_t *" ;
|
||||
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
|
||||
.Ft void
|
||||
.Fn be_prop_list_free "nvlist_t *" ;
|
||||
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.
|
||||
.Fp
|
||||
.Sh DIAGNOSTICS
|
||||
Upon error, one of the following values will be returned.
|
||||
.\" TODO: make each entry on its own line.
|
||||
@ -187,5 +456,7 @@ 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 .
|
||||
.\" TODO: update when implementation complete.
|
||||
.\" .Sh BUGS
|
||||
|
Loading…
Reference in New Issue
Block a user