On 5/24/26 04:53, Takashi Shimizu wrote:
Hi,
I'd like to propose an improvement to the Boot Environment naming
convention used by freebsd-update.
I don't use freebsd-update and still install from source instead of
using the newer pkgbase. I migrated my pre-boot-environment layout to
use 'deep boot environments' layout. I still feel like my understanding
of BEs is a bit weak and am still learning but is seems there are common
misconceptions shared around about them.
*Current behavior and problems*
Here is a typical bectl list output after several freebsd-update runs:
|BE Active Mountpoint Space Created 15.0-RELEASE-p2_2026-02-11_220708 -
- 5.22G 2026-02-11 22:07 15.0-RELEASE-p4_2026-04-23_104906 - - 2.55G
2026-04-23 10:49 15.0-RELEASE-p5_2026-04-23_103138 - - 69.5M 2026-04-23
10:31 15.0-RELEASE-p6_2026-05-06_110219 - - 579M 2026-05-06 11:02 15.0-
RELEASE-p8_2026-05-21_183216 NR / 31.2G 2026-05-21 18:32 15.0-RELEASE-
p8_2026-05-24_153246 - - 1.29M 2026-05-24 15:32 15.0-
RELEASE_2026-02-01_103504 - - 179M 2026-02-01 10:35 default - - 1.22G
2026-02-01 10:29 |
This output raises several problems:
1.
The name "default" is misleading. It suggests "the BE that boots by
default" or "the latest running state", but in practice it is just
the residue of the initial installation, with no NR flag. The name
and its actual purpose are mismatched.
I currently use 'default' as I do not switch from one to the next and
do an install in place. A name that better represents the current state
needs to be renamed whenever the state changes so I shrugged my
shoulders and left it at that. With this use, default maintains NR flags
until I need to call up another boot environment. I could see value in
renaming it to represent its state but never took the time to add that
to my update sequence.
2.
freebsd-update install updates the current BE in place, then saves a
snapshot of the pre-update state with a new date-stamped name. As a
result, the actual content of the current BE does not match its
name. In the example above, 15.0-RELEASE-p8_2026-05-21_183216 has
the NR flag and is the running system, but its actual content is
15.0-RELEASE-p9, installed by freebsd-update. The name says p8, but
the system is running p9. This is highly misleading, especially when
trying to recover from a failed reboot.
Seemed like an issue I had when initially thinking about what boot
environments are. When applied to upgrades, they always mark a 'before'
state. You can use the new BE to copy the current state into and modify
it so it represents an 'after upgrade' state but it never means that at
the time of creation. Once changes are applied to upgrade its contents
then it does represent that state without a way to go back, at least as
long as no snapshots/checkpoint was created pre-upgrade. If an
environment is created with the purpose of only being an upgraded state
then may as well name it as such (or at least rename it after the update).
3.
Furthermore, the snapshot taken just before the update, 15.0-
RELEASE-p8_2026-05-24_153246, has a newer timestamp than the current
BE. The BE with the newer date is actually the older state. If a
reboot fails and the user needs to identify which BE to activate,
the date-based names actively mislead them.
Not sure if I understand the problem as I didn't seem to see it right
in your example.
Is this confusion coming from the BE name containing a tool entered
timestamp vs the time it is actually created at? Adding a timestamp to
the name avoids the likelyhood of duplicate names but is otherwise
unnecessary noise. a '_1' added to the end would make less noisy names
but I thought some places list BE names only which means any time
reference is lost there. If it is not already done, the name's timestamp
could be set based on the creation time as an after creation step to
avoid any variance. Whatever is used, documentation is always good.
If you do not timestamp or number BEs that would otherwise have the
same name and just block them then there is no confusion of which BE is
which, but that also means if an upgrade fails but may contain something
needed then you either have to copy the data out to another BE that is
needed so you can destroy the bad update or have to wait until another
upgrade changes the name later; easier to understand and harder to
induce user error but far less useful.
As I have used full system snapshots before migrating to a BE
compatible layout, I still separately create full pool snapshots before
upgrading. My understanding is BE tools create a snapshot and then
promote the snapshot to a clone; I thought the snapshots no longer exist
once completed but never looked into if that was a BE tools thing or a
ZFS promote snapshot to clone thing; just know I have a lot less
snapshot debris than I would have expected.
4.
As upgrades accumulate, date-stamped BEs proliferate with no clear
indication of which is current and which are fallbacks.
Is pkg or another task also creating them? I thought the BEs of
freebsd-update only create when there is an update and at that point
there is normally at least a patchlevel being bumped accordingly. Its
rare that I want to know when a boot environment was made as a way to
sort out what it is but there have been times where I make a mess of
trying different things and timestamps are what made it manageable.
*Proposal*
*
Rename the initial installation BE from "default" to "original".
This accurately reflects its purpose as a preserved baseline.
If we know what is installed during install then we should know what
its version is. If not using default as an ever evolving state as I do
then it may as well be named for its actual version just like the others.
Even if freebsd-update had a way to downgrade instead of just
rollback, it would still be clear what that first BE contains.
'original' suffers just the same as 'default' in that it doesn't
actually describe what is in the BE. Messing with source code builds you
could run a system backwards and I suspect pkgbase could be coerced into
it too; you would still know.
*
After each freebsd-update install, rename the current BE to "HEAD".
HEAD always refers to the latest BE created automatically by
freebsd-update. User-created BEs are outside the scope of this
convention and should be managed by the user themselves, with names
of their own choosing such as "RELEASE-p9-preRC1".
Sounds like your 'HEAD' is being used as I use 'default'. Both names
suffer from not actually saying what is in the boot environment. If you
switch off of HEAD and go back to another boot environment, are you
expecting BE tooling to replace 'HEAD' with a descriptive line of what
was on that clone and remove the descriptive line of what is on the one
you are switching to? If its not being automatically switched then you
would be unable to create/rename to HEAD anytime you try to upgrade from
any BE that was not already named HEAD unless the tooling is ready to
shift all of the names.
The result would be a bectl list that is immediately understandable:
|BE Active Mountpoint Space Created HEAD NR / 31.2G 2026-05-24 RELEASE-
p9-preRC1 - - 1.5G 2026-05-24 15.0-RELEASE-p6_2026-05-06 - - 579M
2026-05-06 15.0-RELEASE-p2_2026-02-11 - - 5.22G 2026-02-11 original - -
1.22G 2026-02-01 |
You would know what 'original' contains assuming you don't forget.
Anyone else would not know what version is in it until they examine it
further. Same would hold true for HEAD and again if names are not
autoshifted then they could guess HEAD is newest but will not know if it is.
HEAD is always the latest state managed by freebsd-update. User-created
BEs with meaningful names serve as fallbacks for specific purposes.
"original" is preserved as a historical baseline.
This change would make the BE state self-explanatory, reduce confusion
after failed upgrades, and lower the risk of users activating the wrong
BE during recovery.
As someone who spent far too long learning BEs from docs and
thinking, I'd say its still not self-explanatory and I don't see the
risk of wrong selection moving.
I use scripts to either run or manually copy commands to run to avoid
typos and mental memory issues when upgrading from source. My current BE
and snapshots come from:
oldver=`uname -U`
newver=`awk '/^\#define[[:space:]]*__FreeBSD_version/ {print $3}'
/usr/src/sys/sys/param.h`
bectl -r pool/be create upgrade-${oldver}-${newver}
zfs snapshot -r pool@`date -u "+%Y%m%dT%H%M%SZ"`
I've been thinking of removing $newver as it just seems like noise
and as mentioned earlier the BE doesn't contain the new version but its
kept any issues with naming from being duplicates so far on my
incremental upgrades as long as they are only occasionally frequent; I
don't have a test that the name was not already in use. Using
$oldver-$newver tells me the BE contains the old version and the backup
was made to upgrade from it to the new version; so its the state just
before upgrading away from oldver rather than just after upgrading to
oldver or anywhere else inbetween. As much as I dislike that noise, that
does make it more descriptive than what I usually see around, though if
used officially it still needs to be documented to be properly useful
(or made much more wordy).
The snapshot gives me a time+date that sorts chronologically when
sorted alphanumerically thanks to 'not' using common date formatting of
my country; its not descriptive of what is in the backup or why it was
made and just says when. I could certainly shorten it as its quite rare
I'd run such a creation twice in the same minute but left it for now.
Though I build from source which is maintained by git, I do not use
hashes in the names because I know of no practical way to compare hashes
other than manually searching for them within `git log`
Note: As FreeBSD transitions from freebsd-update to pkgbase, it would be
worth considering whether pkgbase will provide automatic BE creation and
a clear naming convention from the start, rather than inheriting the
same confusion.
Still learning pkgbase but I agree that either options to have it
make such calls should exist or prompt the user to do so before some
update actions are taken. Base upgrades are not the only upgrades I have
had to roll back before so there is value in it. Wider pool rollback
capabilities than BEs offer have been needed on occasion too though.
Alternatively, if freebsd-update is modified to do the pkgbase updates
then its current BE management would be a reason for users to use it for
those calls.
Thanks for considering this.
Takashi
