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