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