Bug 254428

Summary: bectl(8) manual page update for bectl destroy, without and with option -o
Product: Documentation Reporter: Graham Perrin <grahamperrin>
Component: Manual PagesAssignee: freebsd-bugs (Nobody) <bugs>
Status: New ---    
Severity: Affects Some People CC: doc, kaltheat, kevans, lwhsu, ygy
Priority: --- Keywords: needs-patch
Version: Latest   
Hardware: Any   
OS: Any   
URL: https://www.freebsd.org/cgi/man.cgi?query=bectl&manpath=FreeBSD+12.2-RELEASE+and+Ports
Attachments:
Description Flags
An example: one warning during a series of destructions none

Description Graham Perrin freebsd_committer freebsd_triage 2021-03-20 09:42:46 UTC
<https://cgit.freebsd.org/src/commit/sbin/bectl?id=8338f584dc6e4b8bc6257bcce210d068f8280e3c&h=main> (2019-10-16):

> bectl(8): destroy: use BE_DESTROY_AUTOORIGIN if -o is not specified
> 
> -o will force the origin to be destroyed unconditionally.
> 
> BE_DESTROY_AUTOORIGIN, on the other hand, will only destroy the 
> origin if it matches the format used by be_snapshot. This lets us 
> clean up the snapshots that are clearly not user-managed (because 
> we're creating them) while leaving user-created snapshots in place 
> and warning that they're still around when the BE created goes away.

From the manual page, for bectl destroy: 

> … By default, bectl will warn that it is not destroying the origin of beName. …

Is this statement of default behaviour suitably descriptive of the changes that were introduced in 2019?

Commentary under <https://vermaden.wordpress.com/2021/02/23/upgrade-freebsd-with-zfs-boot-environments/#comment-18498> may be indicative of misunderstanding, or partial understanding. 

(Do beadm(1) and bectl(8) share the same format for be_snapshot? And so on.)
Comment 1 Graham Perrin freebsd_committer freebsd_triage 2021-03-24 01:45:26 UTC
Created attachment 223539 [details]
An example: one warning during a series of destructions
Comment 2 Graham Perrin freebsd_committer freebsd_triage 2021-03-24 01:55:21 UTC
Instead of: 

> will warn that it is not destroying

– maybe: 

> warns if it does not destroy 

– is that less open to interpretation? Keyword: 

    if
Comment 3 kaltheat 2021-06-18 16:38:54 UTC
Hi,

as an addition:

When running bectl without or with wrong parameters, you get an "Usage" information. In this output '-o' is not mentioned at all for 'bectl destroy' ...

Please add it.

Kind regards,
kaltheat
Comment 4 Graham Perrin freebsd_committer freebsd_triage 2021-06-19 04:23:22 UTC
(In reply to kaltheat from comment #3)

It's mentioned as: 

bectl destroy [-Fo] {beName | beName@snapshot}