libbe(3): Brain dump...

This commit is contained in:
Kyle Evans 2018-08-11 03:33:10 +00:00
parent c3c5a72e4e
commit 7c2cc9b222
Notes: svn2git 2020-12-20 02:59:44 +00:00
svn path=/projects/bectl/; revision=337601

View File

@ -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