1.\" 2.\" Copyright (c) 2017 Kyle J. Kneitinger <kyle@kneit.in> 3.\" 4.\" SPDX-License-Identifier: BSD-2-Clause 5.\" 6.Dd February 4, 2026 7.Dt BECTL 8 8.Os 9.Sh NAME 10.Nm bectl 11.Nd manage ZFS boot environments 12.Sh SYNOPSIS 13.Nm 14.Op Fl h 15.Nm 16.Op Fl r Ar beroot 17.Cm activate 18.Op Fl t | Fl T 19.Ar beName 20.Nm 21.Op Fl r Ar beroot 22.Cm check 23.Nm 24.Op Fl r Ar beroot 25.Cm create 26.Op Fl r 27.Op Fl e Brq Ar nonActiveBe | Ar beName Ns Cm @ Ns Ar snapshot 28.Ar newBeName 29.Nm 30.Op Fl r Ar beroot 31.Cm create 32.Op Fl r 33.Ar beName@snapshot 34.Nm 35.Op Fl r Ar beroot 36.Cm create 37.Fl E 38.Ar newBeName 39.Nm 40.Op Fl r Ar beroot 41.Cm destroy 42.Op Fl \&Fo 43.Ar beName Ns Op Cm @ Ns Ar snapshot 44.Nm 45.Op Fl r Ar beroot 46.Cm export 47.Ar sourceBe 48.Nm 49.Op Fl r Ar beroot 50.Cm import 51.Ar targetBe 52.Nm 53.Op Fl r Ar beroot 54.Cm jail 55.Op Fl bU 56.Oo Bro Fl o Ar key Ns Cm = Ns Ar value | Fl u Ar key Brc Oc Ns ... 57.Ar beName 58.Op Ar utility Op Ar argument ... 59.Nm 60.Op Fl r Ar beroot 61.Cm list 62.Op Fl aDHs 63.Op Fl c Ar property 64.Op Fl C Ar property 65.Oo Bro Fl c Ar property | Fl C Ar property Brc Oc 66.Nm 67.Op Fl r Ar beroot 68.Cm mount 69.Ar beName 70.Op Ar mountpoint 71.Nm 72.Op Fl r Ar beroot 73.Cm rename 74.Ar origBeName 75.Ar newBeName 76.Nm 77.Op Fl r Ar beroot 78.Brq Cm ujail | unjail 79.Brq Ar jailId | jailName | beName 80.Nm 81.Op Fl r Ar beroot 82.Brq Cm umount | unmount 83.Op Fl f 84.Ar beName 85.Sh DESCRIPTION 86The 87.Nm 88utility manages bootable ZFS clones called boot environments. 89Boot envionments allow system changes to be tested safely, 90as they are selectable directly from the boot 91.Xr loader 8 . 92This utility can 93.Cm create , 94.Cm list , 95.Cm mount , 96or 97.Cm jail 98boot environments. 99Once the changes have been tested, the boot environment can be 100.Cm unmount Ns ed , 101.Cm activate Ns d , 102.Cm rename Ns d , 103and 104.Cm destroy Ns ed . 105.Ss Supported Subcommands and Flags 106.Bl -tag -width indent 107.It Fl h 108Print usage information and exit. 109.It Fl r Ar beroot Sy Ar subcommand 110Specify a parent dataset for the boot environment to use for 111.Ar subcommand 112for operation on manually imported pools or unusual layouts. 113.It Xo 114.Cm activate 115.Op Fl t | Fl T 116.Ar beName 117.Xc 118Activate the given 119.Ar beName 120as the default boot filesystem. 121If the 122.Fl t 123flag is given, this takes effect only for the next boot. 124Flag 125.Fl T 126removes temporary boot once configuration. 127Without temporary configuration, 128the next boot will use zfs dataset specified in boot pool 129.Ar bootfs 130property. 131.It Xo 132.Cm check 133.Xc 134Perform a check to see if the current system can use boot environments. 135If boot environments are supported and used, 136.Nm 137will exit with a status code of 0. 138Any other status code is not currently defined and may, in the future, 139grow special meaning for different degrees of sanity check failures. 140.It Xo 141.Cm create 142.Op Fl r 143.Op Fl e Brq Ar nonActiveBe | Ar beName Ns Cm @ Ns Ar snapshot 144.Ar newBeName 145.Xc 146Create a new boot environment named 147.Ar newBeName . 148.Pp 149If the 150.Fl r 151flag is given, a recursive boot environment will be made. 152See 153.Sx Boot Environment Structures 154for a discussion on different layouts. 155.Pp 156If the 157.Fl e 158flag is specified, the new environment will be cloned from the given 159.Ar nonActiveBe 160or 161.Ar beName Ns Cm @ Ns Ar snapshot . 162Otherwise, the new environment will be created from the currently booted 163environment. 164.Pp 165If 166.Nm 167is creating from another boot environment, 168a snapshot of that boot environment will be created to clone from. 169.It Xo 170.Cm create 171.Op Fl r 172.Ar beName@snapshot 173.Xc 174Create a snapshot of the boot environment named 175.Ar beName . 176.Pp 177If the 178.Fl r 179flag is given, 180a recursive snapshot of the boot environment will be created. 181A snapshot is created for each descendant dataset 182of the boot environment. 183See 184.Sx Boot Environment Structures 185for a discussion on different layouts. 186.Pp 187No new boot environment is created with this subcommand. 188.It Xo 189.Cm create 190.Fl E 191.Ar newBeName 192.Xc 193Create a new empty boot environment named 194.Ar newBeName . 195.It Xo 196.Cm destroy 197.Op Fl \&Fo 198.Ar beName Ns Op Cm @ Ns Ar snapshot 199.Xc 200Destroy the given 201.Ar beName 202boot environment or 203.Ar beName Ns Cm @ Ns Ar snapshot 204snapshot without confirmation, unlike in 205.Xr beadm 8 . 206Specifying 207.Fl F 208will automatically unmount without confirmation. 209.Pp 210By default, 211.Nm 212will warn that it is not destroying the origin of 213.Ar beName . 214The 215.Fl o 216flag may be specified to destroy the origin as well. 217.It Cm export Ar sourceBe 218Export 219.Ar sourceBe 220to 221.Xr stdout 4 . 222.Xr stdout 4 223must be piped or redirected to a file. 224.It Cm import Ar targetBe 225Import 226.Ar targetBe 227from 228.Xr stdin 4 . 229.It Xo 230.Cm jail 231.Op Fl bU 232.Oo Bro Fl o Ar key Ns Cm = Ns Ar value | Fl u Ar key Brc Oc Ns ... 233.Ar beName 234.Op Ar utility Op Ar argument ... 235.Xc 236Create a jail of the given boot environment. 237Multiple 238.Fl o 239and 240.Fl u 241arguments may be specified. 242.Fl o 243will set a jail parameter, and 244.Fl u 245will unset a jail parameter. 246.Pp 247By default, jails are created in interactive mode and 248.Pa /bin/sh 249is 250executed within the jail. 251If 252.Ar utility 253is specified, it will be executed instead of 254.Pa /bin/sh . 255The jail will be destroyed and the boot environment unmounted 256when the command finishes executing, unless the 257.Fl U 258argument is specified. 259.Pp 260The 261.Fl b 262argument enables batch mode, thereby disabling interactive mode. 263The 264.Fl U 265argument will be ignored in batch mode. 266.Pp 267The 268.Va name , 269.Va host.hostname , 270and 271.Va path 272must be set, the default values are specified below. 273.Pp 274All 275.Ar key Ns Cm = Ns Ar value 276pairs are interpreted as jail parameters as described in 277.Xr jail 8 . 278The following default parameters are provided: 279.Bl -column "allow.mount.devfs" "" 280.It Va allow.mount Ta Cm true 281.It Va allow.mount.devfs Ta Cm true 282.It Va enforce_statfs Ta Cm 1 283.It Va name Ta set to jail ID 284.It Va host.hostname Ta Va bootenv 285.It Va path Ta set to a path in Pa /tmp 286generated by 287.Xr libbe 3 288.El 289.Pp 290All default parameters may be overwritten. 291.It Xo 292.Cm list 293.Op Fl aDHs 294.Oo Bro Fl c Ar property | Fl C Ar property Brc Oc 295.Xc 296.Pp 297Display all boot environments. 298The 299.Em Active 300field indicates whether the boot environment is active now 301.Pq Em \&N ; 302active on reboot 303.Pq Em \&R ; 304is used on next boot once 305.Pq Em \&T ; 306or combination of 307.Pq Em \&NRT . 308.Bl -tag -width indent 309.It Fl a 310Display all datasets. 311.It Fl D 312Display the full space usage for each boot environment, 313assuming all other boot environments were destroyed. 314.It Fl H 315Used for scripting. 316Do not print headers and separate fields by a single tab instead of 317arbitrary white space. 318.It Fl s 319Display all snapshots as well. 320.It Fl c Ar property 321Sort boot environments by the given ZFS dataset property. 322The following properties are supported: 323.Pp 324.Bl -tag -width 4n -offset indent -compact 325.It name (the default) 326.It creation 327.It origin 328.It used 329.It usedbydataset 330.It usedbyrefreservation 331.It usedbysnapshots 332.El 333.Pp 334Short forms usedds, usedrefreserv and usedsnap are also supported. 335.It Fl C Ar property 336Same as the 337.Fl c 338option, but displays in descending order. 339.El 340.Pp 341The 342.Fl D 343option is ignored when either the 344.Fl s 345or 346.Fl a 347option is used. 348.It Cm mount Ar beName Op Ar mountpoint 349Mount the given boot environment. 350.Pp 351If a nonexistent 352.Ar mountpoint 353is given: 354.Nm 355will make the directory, including intermediate directories as required. 356.Pp 357If no 358.Ar mountpoint 359is given: 360.Nm 361will make a directory such as 362.Pa be_mount.c6Sf 363in 364.Pa /tmp . 365Randomness in the last four characters of the directory name 366will prevent mount point conflicts. 367Unmount of an environment, followed by mount of the same environment 368without giving a 369.Ar mountpoint , 370will result in a different randomly-named mountpoint. 371.It Cm rename Ar origBeName newBeName 372Rename the given 373.Ar origBeName 374to the given 375.Ar newBeName . 376The boot environment will not be unmounted for this rename to occur. 377.It Cm ujail Brq Ar jailId | jailName | beName 378.It Cm unjail Brq Ar jailId | jailName | beName 379Destroy the jail created from the given boot environment. 380.It Xo 381.Cm umount 382.Op Fl f 383.Ar beName 384.Xc 385.It Xo 386.Cm unmount 387.Op Fl f 388.Ar beName 389.Xc 390Unmount the given boot environment, if it is mounted. 391Specifying 392.Fl f 393will force the unmount if busy. 394.Pp 395Unmount will not remove the mount point. 396.El 397.Ss Boot Environment Structures 398The traditional 399.Fx 400boot environment layout, as created by the Auto ZFS option to 401.Xr bsdinstall 8 , 402is a 403.Dq shallow 404boot environment structure, where boot environment datasets 405do not have any directly subordinate datasets. 406Instead, they're organized off in 407.Pa zroot/ROOT , 408and they rely on datasets elsewhere in the pool having 409.Dv canmount 410set to 411.Dv off . 412For instance, a simplified pool may be laid out as such: 413.Bd -literal -offset indent 414% zfs list -o name,canmount,mountpoint 415NAME CANMOUNT MOUNTPOINT 416zroot 417zroot/ROOT noauto none 418zroot/ROOT/default noauto none 419zroot/home on /home 420zroot/usr off /usr 421zroot/usr/src on /usr/src 422zroot/var off /var 423.Ed 424.Pp 425In that example, 426.Pa zroot/usr 427has 428.Dv canmount 429set to 430.Dv off , 431thus files in 432.Pa /usr 433typically fall into the boot environment 434because this dataset is not mounted. 435.Pa zroot/usr/src 436is mounted, thus files in 437.Pa /usr/src 438are not in the boot environment. 439.Pp 440The other style of boot environments in use, frequently called 441.Dq deep boot environments , 442organizes some or all of the boot environment as subordinate to the boot 443environment dataset. 444For example: 445.Bd -literal -offset indent 446% zfs list -o name,canmount,mountpoint 447NAME CANMOUNT MOUNTPOINT 448zroot 449zroot/ROOT noauto none 450zroot/ROOT/default noauto none 451zroot/ROOT/default/usr noauto /usr 452zroot/ROOT/default/usr/local noauto /usr/local 453zroot/var on /var 454.Ed 455.Pp 456Note that the subordinate datasets now have 457.Dv canmount 458set to 459.Dv noauto . 460These are more obviously a part of the boot environment, 461as indicated by their positioning in the layout. 462These subordinate datasets will be mounted by the 463.Dv zfsbe 464.Xr rc 8 465script at boot time. 466In this example, 467.Pa /var 468is excluded from the boot environment. 469.Pp 470.Nm 471subcommands that have their own 472.Fl r 473operate on this second, 474.Dq deep 475style of boot environment, when the 476.Fl r 477flag is set. 478A future version of 479.Nm 480may default to handling both styles and deprecate the various 481.Fl r 482flags. 483.Sh EXAMPLES 484Create a boot environment, named with today's date, 485containing snapshots of the root dataset and of all child datasets: 486.Pp 487.Dl bectl create -r `date +%Y%m%d` 488.Pp 489Mount a previous boot environment, 490.Ar yesterdaysbe , 491to 492.Pa /mnt : 493.Pp 494.Dl bectl mount yesterdaysbe /mnt 495.\" To fill in with jail upgrade example when behavior is firm. 496.Sh SEE ALSO 497.Xr libbe 3 , 498.Xr zfsprops 7 , 499.Xr beinstall.sh 8 , 500.Xr jail 8 , 501.Xr loader 8 , 502.Xr zfs 8 , 503.Xr zpool 8 504.Sh HISTORY 505.Nm 506and 507.Xr libbe 3 508were written by 509.An Kyle Kneitinger (kneitinger) Aq Mt kyle@kneit.in 510as a 2017 Google Summer of Code project, with 511.An Allan Jude (allanjude) Aq Mt allanjude@freebsd.org 512as mentor. 513.Pp 514.Nm 515and this manual page were derived from 516.Xr beadm 8 . 517.Sh AUTHORS 518.An Slawomir Wojciech Wojtczak (vermaden) Aq Mt vermaden@interia.pl 519is the creator and maintainer of 520.Xr beadm 8 . 521.An Bryan Drewery (bdrewery) Aq Mt bryan@shatow.net 522contributed child dataset fixes, and wrote the 523.Xr beadm 8 524manual page. 525.Pp 526Most later changes to 527.Nm , 528and to this page, were written by 529.An Kyle Evans (kevans) Aq Mt kevans@freebsd.org . 530