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 August 12, 2018 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 29activate 30.Op Fl t 31.Ao Ar beName Ac 32.Nm 33create 34.Op Fl r 35.Op Fl e Ar nonActiveBe | Fl e Ar beName@snapshot 36.Ao Ar beName Ac 37.Nm 38create 39.Op Fl r 40.Ao Ar beName@snapshot Ac 41.Nm 42destroy 43.Op Fl F 44.Ao Ar beName | beName@snapshot Ac 45.Nm 46export 47.Ao Ar sourceBe Ac 48.Nm 49import 50.Ao Ar targetBe Ac 51.Nm 52jail 53.Oo Fl o Ar key Ns = Ns Ar value | Fl u Ar key Oc Ns ... 54.Ao Ar jailID | jailName Ac 55.Ao Ar bootenv Ac 56.Nm 57list 58.Op Fl a 59.Op Fl D 60.Op Fl H 61.Op Fl s 62.Nm 63mount 64.Ao Ar beName Ac 65.Op mountpoint 66.Nm 67rename 68.Ao Ar origBeName Ac 69.Ao Ar newBeName Ac 70.Nm 71{ ujail | unjail } 72.Ao Ar jailID | jailName Ac 73.Ao Ar bootenv Ac 74.Nm 75{ umount | unmount } 76.Op Fl f 77.Ao Ar beName Ac 78.Sh DESCRIPTION 79The 80.Nm 81command is used to setup and interact with ZFS boot environments, which are bootable clones of datasets. 82.Pp 83.Em Boot Environments 84allows the system to be upgraded, while preserving the old system environment in a separate ZFS dataset. 85.Sh COMMANDS 86The following commands are supported by 87.Nm : 88.Bl -tag -width activate 89.It Ic activate 90.Op Fl t 91.Ar <beName> 92.Pp 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 Ic create 100.Op Fl r 101.Op Fl e Ar nonActiveBe | Fl e Ar beName@snapshot 102.Ao Ar beName Ac 103.Pp 104Creates a new boot environment named 105.Ar beName . 106If the -e param is specified, the new environment will be cloned from the given 107.Ar nonActiveBe | Ar beName@snapshot . 108If the 109.Op Fl r 110flag is given, a recursive boot environment will be made. 111.It Ic create 112.Op Fl r 113.Ao Ar beName@snapshot Ac 114.Pp 115Creates a snapshot of the existing boot environment named 116.Ar beName . 117If the 118.Op Fl r 119flag is given, a recursive boot environment will be made. 120.It Ic destroy 121.Op Fl F 122.Ao Ar beName | beName@snapshot Ac 123.Pp 124Destroys the given 125.Ar beName 126boot environment or 127.Ar beName@snapshot 128snapshot. 129Specifying 130.Fl F 131will automatically unmount without confirmation. 132.It Ic export 133.Ao Ar sourceBe Ac 134.Pp 135Export 136.Ar sourceBe 137to 138.Dv stdout . 139.Dv stdout 140must be piped or redirected to a file. 141.It Ic import 142.Ao Ar targetBe Ac 143.Pp 144Import 145.Ar targetBe 146from 147.Dv stdin . 148.It Ic jail 149.Oo Fl o Ar key Ns = Ns Ar value | Fl u Ar key Oc Ns ... 150.Ao Ar jailID | jailName Ac 151.Ao Ar bootenv Ac 152.Pp 153Creates a jail of the given boot environment. 154Multiple 155.Fl o 156and 157.Fl u 158arguments may be specified. 159.Fl o 160will set a jail parameter, and 161.Fl u 162will unset a jail parameter. 163.Pp 164The 165.Va name , 166.Va host.hostname , 167and 168.Va path 169may not actually be unset. 170Attempts to unset any of these will revert them to the default values specified 171below, if they have been overwritten by 172.Fl o . 173.Pp 174All 175.Ar key , 176.Ar value 177pairs are interpreted as jail parameters as described in 178.Xr jail 8 . 179The following default parameters are provided: 180.Bl -tag -width -indent 181.It Va allow.mount Ns = Ns Ar true 182.It Va allow.mount.devfs Ns = Ns Ar true 183.It Va enforce_statfs Ns = Ns Ar 1 184.It Va name Ns = Ns Ar bootenv 185.It Va host.hostname Ns = Ns Ar bootenv 186.It Va path 187Set to a path in /tmp generated by 188.Xr libbe 3 . 189.El 190.Pp 191All default parameters may be overwritten. 192.It Ic list 193.Op Fl a 194.Op Fl D 195.Op Fl H 196.Op Fl s 197.Pp 198Displays all boot environments. 199The Active field indicates whether the boot environment is active now (N); active on reboot (R); or both (NR). 200.Pp 201If 202.Fl a 203is used, display all datasets. 204If 205.Fl D 206is used, display the full space usage for each boot environment, assuming all other boot environments were destroyed. 207The 208.Fl H 209option is used for scripting. 210It does not print headers and separate fields by a single tab instead of arbitrary white space. 211If 212.Fl s 213is used, display all snapshots as well. 214.It Ic mount 215.Ao Ar beName Ac 216.Op mountpoint 217.Pp 218Temporarily mount the boot environment. 219Mount at the specified 220.Ar mountpoint 221if provided. 222.It Ic rename Ao Ar origBeName Ac Ao Ar newBeName Ac 223.Pp 224Renames the given nonactive 225.Ar origBeName 226to the given 227.Ar newBeName 228.It Ic unjail Ao Ar jailID | jailName | beName Ac 229.Pp 230Destroys the jail created from the given boot environment. 231.It Ic unmount 232.Op Fl f 233.Ao Ar beName Ac 234.Pp 235Unmount the given boot environment, if it is mounted. 236Specifying 237.Fl f 238will force the unmount if busy. 239.El 240.Sh EXAMPLES 241.Bl -bullet 242.It 243To fill in with jail upgrade example when behavior is firm. 244.El 245.Sh SEE ALSO 246.Xr jail 8 , 247.Xr zfs 8 , 248.Xr zpool 8 249.Sh HISTORY 250.Nm 251is based on 252.Xr beadm 1 253and was implemented as a project for the 2017 Summer of Code, along with 254.Xr libbe 3 . 255.Sh AUTHORS 256.Bl -bullet 257.It 258.An Kyle Kneitinger (kneitinger) Aq Mt kyle@kneit.in 259.Pp 260Creator of 261.Nm . 262.It 263.An Slawomir Wojciech Wojtczak (vermaden) Aq Mt vermaden@interia.pl 264.Pp 265Creator and maintainer of 266.Xr beadm 1 . 267.It 268.An Bryan Drewery (bdrewery) Aq Mt bryan@shatow.net 269.Pp 270Wrote the original 271.Xr beadm 1 272manual page that this one is derived from. 273.El 274