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