====== ZFS Boot Environment Introduction ======

===== Introduction =====

The boot environment (or BE) is a consequence of booting from ZFS. ZFS mounts the selected BE and loads everything from there. Even if you've never explicitly created a boot environment, by booting from ZFS, you're using one - the 'default' boot environment.

To take advantage of BEs, you must at some point create at least one additional BE and then switch to using that BE.

BEs allow you to make drastic changes inside one BE while leaving another clean BE as a fallback should things go awry. It is important to understand the BEs are separate from each other in that changes to one BE has no effect on the others. You can create two identical BEs A and B. If you edit a file on BE "A" and switch to "B" - those edits aren't available in "B". Likewise, you can delete a file in "B", switch to "A", and the file still appears on "A".

Obviously, you must have installed %%FreeBSD%% with ZFS as the boot partition to make use of BEs.

The ZFS command [[https://www.freebsd.org/cgi/man.cgi?query=bectl&manpath=FreeBSD+12.1-RELEASE|bectl]] combined with judicious use of [[https://www.freebsd.org/cgi/man.cgi?query=reboot&manpath=FreeBSD+12.1-RELEASE|reboot]] is all you need to manage BEs. The work flow becomes:

  * Create a new BE with ''%%bectl create%%''.
  * Make changes like ''%%freebsd-update%%'' or ''%%pkg install/upgrade%%'' inside your working BE (usually named 'default').
  * Test drive the BE.
    * Happy? Keep the BE. Use ''%%bectl destroy -o%%'' to clean up the backup.
    * Unhappy? Roll back to the backup BE with ''%%bectl activate%%'' and ''%%reboot%%'' to start over.

====== Lab ======

Here are some exercises to get you comfortable with using BEs.

===== Create =====

<code>
# bectl list
(verify your current BE is named 'default')
# bectl create lab
</code>

===== Activate =====

Boot into this new BE by activating it and re-booting.

<code>
# bectl activate lab
# reboot
</code>

===== Make Changes =====

Log in as root and use your favorite editor to create a text file called "belab.txt".

TODO: clarify where in the hierarchy this works. BEs do not protect /var/log /var/tmp /var/mail /var/audit /tmp /mail /home /usr/ports or /usr/src.

<code>
# vi ~/belab.txt
</code>

Put some meaningful text in there. Something that shows you wrote it. Save and exit from the editor.

Install a binary package. For example, the text editor 'micro':

<code>
# pkg install micro
</code>

Verify the text file is there:

<code>
# cat ~/belab.txt
</code>

Verify the 'micro' package is installed.

<code>
# pkg info micro
</code>

===== Go Back =====

<code>
# bectl list
(verify spelling of your default BE)
# bectl activate default
# reboot
</code>

===== Check for Changes =====

Log back in as root and look for the pkg 'micro' and your text file 'belab.txt'.

<code>
# cat ~/belab.txt
# pkg info micro
</code>

===== Lab Cleanup =====

Let's clean up after ourselves by destroying the toy BE created above.

<code>
# bectl list
(verify spelling of the BE to be removed)
# bectl destroy -o lab
</code>

====== History ======

''%%bectl%%'' was inspired by the Bourne shell script [[https://www.freebsd.org/cgi/man.cgi?query=beadm&manpath=FreeBSD+12.1-RELEASE+and+Ports|beadm]] contributed by %%FreeBSD%% ports contributor Slawomir Wojciech Wojtczak (vermaden). The syntax for ''%%beadm%%'' and ''%%bectl%%'' are nearly identical. ''%%beadm%%'' was inspired by the Solaris utility of the same name.

Thank you vermaden!

====== See Also ======

===== Reference =====

[[https://vermaden.files.wordpress.com/2018/11/nluug-zfs-boot-environments-reloaded-2018-11-15.pdf|zfs-boot-environments-reloaded]]

[[Ports/sysutils/beadm|beadm]]

[[/BootEnvironments|BE Details]]

[[https://vermaden.wordpress.com/2021/02/23/upgrade-freebsd-with-zfs-boot-environments/|Upgrade Freebsd with ZFS Boot Environments]]

===== Safely Upgrade =====

This page describes how to leverage BEs to manage upgrading %%FreeBSD%%.

[[unitrunker/base-upgrade|Base Upgrade]]

===== Try All The X Environments =====

This pages describes how to leverage BEs to test out a dozen or more X.org Window Managers and Desktop Environments

[[unitrunker/try-them-all|X: Try Them All]]

----

{{tag>HowTo}}