Bug 235850 - bectl(8): create should mention it creates from booted system without any other argument
Summary: bectl(8): create should mention it creates from booted system without any oth...
Status: Closed FIXED
Alias: None
Product: Documentation
Classification: Unclassified
Component: Manual Pages (show other bugs)
Version: Latest
Hardware: Any Any
: --- Affects Only Me
Assignee: Mateusz Piotrowski
URL:
Keywords: needs-patch
Depends on:
Blocks:
 
Reported: 2019-02-19 03:54 UTC by Larry Rosenman
Modified: 2019-09-09 17:54 UTC (History)
3 users (show)

See Also:


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description Larry Rosenman freebsd_committer 2019-02-19 03:54:00 UTC
The bectl(8) manpage under the create option should echo the libbe(3) be_create wording to say that it populates the BE from the running system if no other arguments are given.

 It	will be	created	from a snapshot	of the currently booted	boot environ-
     ment.
Comment 1 Mateusz Piotrowski freebsd_committer 2019-03-07 10:48:36 UTC
(In reply to Larry Rosenman from comment #0)

Mmm, I think I misunderstood something: I think that bectl always requires an argument, doesn't it?
Comment 2 Larry Rosenman freebsd_committer 2019-03-07 16:22:15 UTC
When you say:

bectl create newbe

it will use the currently running boot environment.  For a person that is 
not familiar with the underlying libbe(3) create call, it's unclear that the currently running boot environment will be the one cloned to create the newbe environment.

What I'm asking for is to add the statement from the libbe(3) create call documentation to the bectl(8) create command documentation that without a 3rd argument the currently running boot environment will be cloned to create the new boot environment.
Comment 3 Kyle Evans freebsd_committer 2019-03-19 19:13:39 UTC
(In reply to Mateusz Piotrowski from comment #1)

Right, he's talking specifically about the 'create' subcommand. I note that the man page here is kind of... bad. We should do the following:

1.) Get rid of the bectl create [-r] beName@snapshot line in SYNOPSIS
2.) Get rid of the same down in commands
3.) Amend the create command description to mention:

If the
.Fl e
argument is specified, the new environment will be cloned from the given nonActiveBE | beName@snapshot.
When the
.Fl e
argument is not specified, the new environment will be created from the currently booted environment. 
If
.Nm
is creating from another boot environment, a snapshot of that boot environment will be created to clone from.

Of course, the markup is basically all wrong, but I think that gets the idea across. We should mention for those not familiar with bectl that the default is to use the currently booted environment, and we should mention for those maybe not necessarily familiar with some of the underlying ZFS terminology that create of anything other than beName@snapshot implies that a snapshot of that boot environment will be made for creation.
Comment 4 Mateusz Piotrowski freebsd_committer 2019-03-29 09:23:47 UTC
https://reviews.freebsd.org/D19666
Comment 5 commit-hook freebsd_committer 2019-04-03 13:47:20 UTC
A commit references this bug:

Author: 0mp
Date: Wed Apr  3 13:46:44 UTC 2019
New revision: 345845
URL: https://svnweb.freebsd.org/changeset/base/345845

Log:
  bectl.8: Clean up & clarify the create subcommand

  - Improve formatting
  - Use consistent variable names
  - Improve the description of the create subcommand (1)

  PR:		235850 (1)
  Submitted by:	kevans (1)
  Reported by:	ler (1)
  Reviewed by:	kevans
  Approved by:	src (kevans)
  Differential Revision:	https://reviews.freebsd.org/D19666

Changes:
  head/sbin/bectl/bectl.8
Comment 6 Mateusz Piotrowski freebsd_committer 2019-04-03 13:48:12 UTC
Larry, could you have a look if it's fine?
Comment 7 Larry Rosenman freebsd_committer 2019-04-04 14:40:48 UTC
MUCH nicer!  Thanks!
Comment 8 commit-hook freebsd_committer 2019-09-09 17:54:00 UTC
A commit references this bug:

Author: kevans
Date: Mon Sep  9 17:53:16 UTC 2019
New revision: 352086
URL: https://svnweb.freebsd.org/changeset/base/352086

Log:
  MFC r345845-r345846: bectl(8) manpage clarity

  r345845:
  bectl.8: Clean up & clarify the create subcommand

  - Improve formatting
  - Use consistent variable names
  - Improve the description of the create subcommand (1)

  PR:		235850

  r345846:
  bectl.8: Bump date after r345845

Changes:
_U  stable/12/
  stable/12/sbin/bectl/bectl.8