1.\" 2.\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD 3.\" 4.\" Copyright (c) 2017 Kyle J. Kneitinger <kyle@kneit.in> 5.\" All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 16.\" 17.\" @(#)be.1 18.\" 19.\" $FreeBSD$ 20.\" 21.Dd September 11, 2019 22.Dt BECTL 8 23.Os 24.Sh NAME 25.Nm bectl 26.Nd Utility to manage boot environments on ZFS 27.Sh SYNOPSIS 28.Nm 29.Cm activate 30.Op Fl t 31.Ar beName 32.Nm 33.Cm check 34.Nm 35.Cm create 36.Op Fl r 37.Op Fl e Brq Ar nonActiveBe | Ar beName Ns Cm @ Ns Ar snapshot 38.Ar newBeName 39.Nm 40.Cm create 41.Op Fl r 42.Ar beName@snapshot 43.Nm 44.Cm destroy 45.Op Fl \&Fo 46.Ar beName Ns Op Cm @ Ns Ar snapshot 47.Nm 48.Cm export 49.Ar sourceBe 50.Nm 51.Cm import 52.Ar targetBe 53.Nm 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.Cm list 61.Op Fl aDHs 62.Op Fl c Ar property 63.Op Fl C Ar property 64.Oo Bro Fl c Ar property | Fl C Ar property Brc Oc 65.Nm 66.Cm mount 67.Ar beName 68.Op Ar mountpoint 69.Nm 70.Cm rename 71.Ar origBeName 72.Ar newBeName 73.Nm 74.Brq Cm ujail | unjail 75.Brq Ar jailId | jailName 76.Ar beName 77.Nm 78.Brq Cm umount | unmount 79.Op Fl f 80.Ar beName 81.Pp 82.Nm 83.Op Fl h\&? 84.Sh DESCRIPTION 85The 86.Nm 87command is used to setup and interact with ZFS boot environments, which are 88bootable clones of datasets. 89.Pp 90Boot environments 91allow the system to be upgraded, while preserving the old system environment in 92a separate ZFS dataset. 93.Pp 94The following commands are supported by 95.Nm : 96.Bl -tag -width activate 97.It Xo 98.Cm activate 99.Op Fl t 100.Ar beName 101.Xc 102Activate the given 103.Ar beName 104as the default boot filesystem. 105If the 106.Op Fl t 107flag is given, this takes effect only for the next boot. 108.It Xo 109.Cm check 110.Xc 111Performs a silent sanity check on the current system. 112If boot environments are supported and used, 113.Nm 114will exit with a status code of 0. 115Any other status code is not currently defined and may, in the future, grow 116special meaning for different degrees of sanity check failures. 117.It Xo 118.Cm create 119.Op Fl r 120.Op Fl e Brq Ar nonActiveBe | Ar beName Ns Cm @ Ns Ar snapshot 121.Ar newBeName 122.Xc 123Create a new boot environment named 124.Ar newBeName . 125.Pp 126If the 127.Fl r 128flag is given, a recursive boot environment will be made. 129.Pp 130If the 131.Fl e 132flag is specified, the new environment will be cloned from the given 133.Ar nonActiveBe 134or 135.Ar beName Ns Cm @ Ns Ar snapshot . 136Otherwise, the new environment will be created from the currently booted environment. 137.Pp 138If 139.Nm 140is creating from another boot environment, a snapshot of that boot environment will be created to clone from. 141.It Xo 142.Cm create 143.Op Fl r 144.Ar beName@snapshot 145.Xc 146Create a snapshot of the boot environment named 147.Ar beName . 148.Pp 149If the 150.Fl r 151flag is given, a recursive snapshot of the boot environment will be created. 152A snapshot is created for each descendant dataset of the boot environment. 153.Pp 154No new boot environment is created with this command. 155.It Xo 156.Cm destroy 157.Op Fl \&Fo 158.Ar beName Ns Op Cm @ Ns Ar snapshot 159.Xc 160Destroy the given 161.Ar beName 162boot environment or 163.Ar beName Ns Cm @ Ns Ar snapshot 164snapshot without confirmation, unlike in 165.Xr beadm 1 . 166Specifying 167.Fl F 168will automatically unmount without confirmation. 169.Pp 170By default, 171.Nm 172will warn that it is not destroying the origin of 173.Ar beName . 174The 175.Fl o 176flag may be specified to destroy the origin as well. 177.It Cm export Ar sourceBe 178Export 179.Ar sourceBe 180to 181.Xr stdout 4 . 182.Xr stdout 4 183must be piped or redirected to a file. 184.It Cm import Ar targetBe 185Import 186.Ar targetBe 187from 188.Xr stdin 4 . 189.It Xo 190.Cm jail 191.Op Fl bU 192.Oo Bro Fl o Ar key Ns Cm = Ns Ar value | Fl u Ar key Brc Oc Ns ... 193.Ar beName 194.Op Ar utility Op Ar argument ... 195.Xc 196Create a jail of the given boot environment. 197Multiple 198.Fl o 199and 200.Fl u 201arguments may be specified. 202.Fl o 203will set a jail parameter, and 204.Fl u 205will unset a jail parameter. 206.Pp 207By default, jails are created in interactive mode and 208.Pa /bin/sh 209is 210executed within the jail. 211If 212.Ar utility 213is specified, it will be executed instead of 214.Pa /bin/sh . 215The jail will be destroyed and the boot environment unmounted when the command 216finishes executing, unless the 217.Fl U 218argument is specified. 219.Pp 220The 221.Fl b 222argument enables batch mode, thereby disabling interactive mode. 223The 224.Fl U 225argument will be ignored in batch mode. 226.Pp 227The 228.Va name , 229.Va host.hostname , 230and 231.Va path 232must be set, the default values are specified below. 233.Pp 234All 235.Ar key Ns Cm = Ns Ar value 236pairs are interpreted as jail parameters as described in 237.Xr jail 8 . 238The following default parameters are provided: 239.Bl -column "allow.mount.devfs" "" 240.It Va allow.mount Ta Cm true 241.It Va allow.mount.devfs Ta Cm true 242.It Va enforce_statfs Ta Cm 1 243.It Va name Ta Set to jail ID. 244.It Va host.hostname Ta Va bootenv 245.It Va path Ta Set to a path in Pa /tmp 246generated by 247.Xr libbe 3 . 248.El 249.Pp 250All default parameters may be overwritten. 251.It Xo 252.Cm list 253.Op Fl DHas 254.Oo Bro Fl c Ar property | Fl C Ar property Brc Oc 255.Xc 256.Pp 257Display all boot environments. 258The 259.Em Active 260field indicates whether the boot environment is active now 261.Pq Em \&N ; 262active on reboot 263.Pq Em \&R ; 264or both 265.Pq Em \&NR . 266.Pp 267.Bl -tag -width indent 268.It Fl a 269Display all datasets. 270.It Fl D 271Display the full space usage for each boot environment, assuming all 272other boot environments were destroyed. 273.It Fl H 274Used for scripting. 275Do not print headers and separate fields by a single tab instead of 276arbitrary white space. 277.It Fl s 278Display all snapshots as well. 279.It Fl c Ar property 280Sort boot environments by given property name. 281The following properties are supported: 282.Pp 283.Bl -tag -width 4n -offset indent -compact 284.It name (default output) 285.It creation 286.It origin 287.It used 288.It usedds 289.It usedsnap 290.It usedrefreserv 291.El 292.It Fl C Ar property 293Same as the 294.Fl c 295option, but displays in descending order. 296.El 297.Pp 298The 299.Fl D 300option is ignored when either the 301.Fl s 302or 303.Fl a 304option is used. 305.It Cm mount Ar beName Op Ar mountpoint 306Temporarily mount the boot environment. 307Mount at the specified 308.Ar mountpoint 309if provided. 310.It Cm rename Ar origBeName newBeName 311Rename the given 312.Ar origBeName 313to the given 314.Ar newBeName . 315The boot environment will not be unmounted in order for this rename to occur. 316.It Cm ujail Bro Ar jailId | jailName Brc Ar beName 317.It Cm unjail Bro Ar jailId | jailName Brc Ar beName 318Destroy the jail created from the given boot environment. 319.It Xo 320.Cm umount 321.Op Fl f 322.Ar beName 323.Xc 324.It Xo 325.Cm unmount 326.Op Fl f 327.Ar beName 328.Xc 329Unmount the given boot environment, if it is mounted. 330Specifying 331.Fl f 332will force the unmount if busy. 333.El 334.Pp 335.Nm 336prints usage information if 337.Fl h 338or 339.Fl \&? 340is specified. 341.Sh EXAMPLES 342.Bl -bullet 343.It 344To fill in with jail upgrade example when behavior is firm. 345.El 346.Sh SEE ALSO 347.Xr beinstall.sh 1 , 348.Xr libbe 3 , 349.Xr jail 8 , 350.Xr zfs 8 , 351.Xr zpool 8 352.Sh HISTORY 353.Nm 354is based on 355.Xr beadm 1 356and was implemented as a project for the 2017 Summer of Code, along with 357.Xr libbe 3 . 358.Sh AUTHORS 359.Nm 360was written by 361.An Kyle Kneitinger (kneitinger) Aq Mt kyle@kneit.in . 362.Pp 363.Xr beadm 1 364was written and is maintained by 365.An Slawomir Wojciech Wojtczak (vermaden) Aq Mt vermaden@interia.pl . 366.Pp 367.An Bryan Drewery (bdrewery) Aq Mt bryan@shatow.net 368wrote the original 369.Xr beadm 1 370manual page that this one is derived from. 371