Date: Sat, 11 Aug 2018 03:33:11 +0000 (UTC) From: Kyle Evans <kevans@FreeBSD.org> To: src-committers@freebsd.org, svn-src-projects@freebsd.org Subject: svn commit: r337601 - projects/bectl/lib/libbe Message-ID: <201808110333.w7B3XBDv017377@repo.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: kevans Date: Sat Aug 11 03:33:10 2018 New Revision: 337601 URL: https://svnweb.freebsd.org/changeset/base/337601 Log: libbe(3): Brain dump... Modified: projects/bectl/lib/libbe/libbe.3 Modified: projects/bectl/lib/libbe/libbe.3 ============================================================================== --- projects/bectl/lib/libbe/libbe.3 Sat Aug 11 02:56:43 2018 (r337600) +++ projects/bectl/lib/libbe/libbe.3 Sat Aug 11 03:33:10 2018 (r337601) @@ -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,126 +35,394 @@ .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. -.Pp -Applications using this interface must be linked with -.Fl l Ns Ar be -.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. -.\" TODO: describe break on err functionality -.Sh FUNCTION OVERVIEW -.Ft "libbe_handle_t *" Ns -.Fn libbe_init void ; -.Pp .Ft void -.Fn libbe_close "libbe_handle_t *" ; +.Fn libbe_close "libbe_handle_t *hdl" .Pp .Ft const char * Ns -.Fn be_active_name "libbe_handle_t *" ; +.Fn be_active_name "libbe_handle_t *hdl" .Pp .Ft const char * Ns -.Fn be_active_path "libbe_handle_t *" ; +.Fn be_active_path "libbe_handle_t *hdl" .Pp .Ft const char * Ns -.Fn be_nextboot_name "libbe_handle_t *" ; +.Fn be_nextboot_name "libbe_handle_t *hdl" .Pp .Ft const char * Ns -.Fn be_nextboot_path "libbe_handle_t *" ; +.Fn be_nextboot_path "libbe_handle_t *hdl" .Pp .Ft const char * Ns -.Fn be_root_path "libbe_handle_t *" ; +.Fn be_root_path "libbe_handle_t *hdl" .Pp .Ft int -.Fn be_create "libbe_handle_t *" "const char *" ; +.Fn be_create "libbe_handle_t *hdl" "const char *be_name" .Pp .Ft int -.Fn be_create_from_existing "libbe_handle_t *" "const char *" "const char *" ; +.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 *" "const char *" "const char *" ; +.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 *" "const char *" "const char *" ; +.Fn be_rename "libbe_handle_t *hdl" "const char *be_old" "const char *be_new" .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; +.Fn be_activate "libbe_handle_t *hdl" "const char *be_name" "bool temporary" .Ft int -.Fn be_destroy "libbe_handle_t *" "const char *" "int" ; +.Fn be_destroy "libbe_handle_t *hdl" "const char *be_name" "int options" .Pp .Ft void -.Fn be_nicenum uint64_t" "char *" "size_t" ; +.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; +.\" } be_mount_opt_t .Ft int -.Fn be_mount "libbe_handle_t *" "char *" "char *" "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 *" "const char *" "nvlist_t" ; +.Fn be_mounted_at "libbe_handle_t *hdl" "const char *path" "nvlist_t *details" .Pp .Ft int -.Fn be_unmount "libbe_handle_t *" "char *" "int" ; +.Fn be_unmount "libbe_handle_t *hdl" "char *be_name" "int flags" .Pp .Ft int -.Fn libbe_errno "libbe_handle_t *" ; +.Fn libbe_errno "libbe_handle_t *hdl" .Pp .Ft const char * Ns -.Fn libbe_error_description "libbe_handle_t *" ; +.Fn libbe_error_description "libbe_handle_t *hdl" .Pp .Ft void -.Fn libbe_print_on_error "libbe_handle_t *" "bool" ; +.Fn libbe_print_on_error "libbe_handle_t *hdl" "bool doprint" .Pp .Ft int -.Fn be_root_concat "libbe_handle_t *" "const char *" "char *" ; +.Fn be_root_concat "libbe_handle_t *hdl" "const char *be_name" "char *result" .Pp .Ft int -.Fn be_validate_name "libbe_handle_t *" "const char *" ; +.Fn be_validate_name "libbe_handle_t *hdl" "const char *be_name" .Pp .Ft int -.Fn be_validate_snap "libbe_handle_t *" "const char *" ; +.Fn be_validate_snap "libbe_handle_t *hdl" "const char *snap" .Pp .Ft bool -.Fn be_exists "libbe_handle_t *" "char *" ; +.Fn be_exists "libbe_handle_t *hdl" "char *be_name" .Pp .Ft int -.Fn be_export "libbe_handle_t *" "const char *" "int fd" ; +.Fn be_export "libbe_handle_t *hdl" "const char *be_name" "int fd" .Pp .Ft int -.Fn be_import "libbe_handle_t *" "const char *" "int fd" ; +.Fn be_import "libbe_handle_t *hdl" "const char *be_name" "int fd" .Pp .Ft int -.Fn be_prop_list_alloc "nvlist_t **" ; +.Fn be_prop_list_alloc "nvlist_t **prop_list" .Pp .Ft int -.Fn be_get_bootenv_props "libbe_handle_t *" "nvlist_t *" ; +.Fn be_get_bootenv_props "libbe_handle_t *hdl" "nvlist_t *be_list" .Pp .Ft int -.Fn be_get_dataset_props "libbe_handle_t *" "const char *" "nvlist_t *" ; +.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 *" "const char *" "nvlist_t *" ; +.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 *" ; +.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 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 +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, +.Pp +The +.Fn be_active_path +function returns the full path of the currently booted boot environment. +.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. +It will be created from a snapshot of the currently booted 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 snapshot will be made of the base boot environment, and the new boot +environment will be created from that. +.Pp +The +.Fn be_create_from_existing_snap +function creates a boot environment with the given name from an existing +snapshot. +.Pp +The +.Fn be_rename +function renames a boot environment. +.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 . +.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 , +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. +.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 / . +.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. +.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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201808110333.w7B3XBDv017377>