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