sbin/bectl/bectl.8

   1 .\"
   2 .\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD
   3 .\"
   4 .\" Copyright (c) 2017 Kyle J. Kneitinger <kyle@kneit.in>
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\"
  15 .\"
  16 .\"     @(#)be.1
  17 .\"
  18 .\" $FreeBSD$
  19 .\"
  20 .Dd March 31, 2022
  21 .Dt BECTL 8
  22 .Os
  23 .Sh NAME
  24 .Nm bectl
  25 .Nd Utility to manage boot environments on ZFS
  26 .Sh SYNOPSIS
  27 .Nm
  28 .Cm activate
  29 .Op Fl t | Fl T
  30 .Ar beName
  31 .Nm
  32 .Cm check
  33 .Nm
  34 .Cm create
  35 .Op Fl r
  36 .Op Fl e Brq Ar nonActiveBe | Ar beName Ns Cm @ Ns Ar snapshot
  37 .Ar newBeName
  38 .Nm
  39 .Cm create
  40 .Op Fl r
  41 .Ar beName@snapshot
  42 .Nm
  43 .Cm destroy
  44 .Op Fl \&Fo
  45 .Ar beName Ns Op Cm @ Ns Ar snapshot
  46 .Nm
  47 .Cm export
  48 .Ar sourceBe
  49 .Nm
  50 .Cm import
  51 .Ar targetBe
  52 .Nm
  53 .Cm jail
  54 .Op Fl bU
  55 .Oo Bro Fl o Ar key Ns Cm = Ns Ar value | Fl u Ar key Brc Oc Ns ...
  56 .Ar beName
  57 .Op Ar utility Op Ar argument ...
  58 .Nm
  59 .Cm list
  60 .Op Fl aDHs
  61 .Op Fl c Ar property
  62 .Op Fl C Ar property
  63 .Oo Bro Fl c Ar property | Fl C Ar property Brc Oc
  64 .Nm
  65 .Cm mount
  66 .Ar beName
  67 .Op Ar mountpoint
  68 .Nm
  69 .Cm rename
  70 .Ar origBeName
  71 .Ar newBeName
  72 .Nm
  73 .Brq Cm ujail | unjail
  74 .Brq Ar jailId | jailName | 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
  83 The
  84 .Nm
  85 command is used to setup and interact with ZFS boot environments, which are
  86 bootable clones of datasets.
  87 .Pp
  88 Boot environments
  89 allow the system to be upgraded, while preserving the old system environment in
  90 a separate ZFS dataset.
  91 .Pp
  92 The following commands are supported by
  93 .Nm :
  94 .Bl -tag -width activate
  95 .It Xo
  96 .Cm activate
  97 .Op Fl t | Fl T
  98 .Ar beName
  99 .Xc
 100 Activate the given
 101 .Ar beName
 102 as the default boot filesystem.
 103 If the
 104 .Fl t
 105 flag is given, this takes effect only for the next boot.
 106 Flag
 107 .Fl T
 108 removes temporary boot once configuration.
 109 Without temporary configuration, the next boot will use zfs dataset specified
 110 in boot pool
 111 .Ar bootfs
 112 property.
 113 .It Xo
 114 .Cm check
 115 .Xc
 116 Performs a silent sanity check on the current system.
 117 If boot environments are supported and used,
 118 .Nm
 119 will exit with a status code of 0.
 120 Any other status code is not currently defined and may, in the future, grow
 121 special meaning for different degrees of sanity check failures.
 122 .It Xo
 123 .Cm create
 124 .Op Fl r
 125 .Op Fl e Brq Ar nonActiveBe | Ar beName Ns Cm @ Ns Ar snapshot
 126 .Ar newBeName
 127 .Xc
 128 Create a new boot environment named
 129 .Ar newBeName .
 130 .Pp
 131 If the
 132 .Fl r
 133 flag is given, a recursive boot environment will be made.
 134 See
 135 .Sx Boot Environment Structures
 136 for a discussion on different layouts.
 137 .Pp
 138 If the
 139 .Fl e
 140 flag is specified, the new environment will be cloned from the given
 141 .Ar nonActiveBe
 142 or
 143 .Ar beName Ns Cm @ Ns Ar snapshot .
 144 Otherwise, the new environment will be created from the currently booted environment.
 145 .Pp
 146 If
 147 .Nm
 148 is creating from another boot environment, a snapshot of that boot environment will be created to clone from.
 149 .It Xo
 150 .Cm create
 151 .Op Fl r
 152 .Ar beName@snapshot
 153 .Xc
 154 Create a snapshot of the boot environment named
 155 .Ar beName .
 156 .Pp
 157 If the
 158 .Fl r
 159 flag is given, a recursive snapshot of the boot environment will be created.
 160 A snapshot is created for each descendant dataset of the boot environment.
 161 See
 162 .Sx Boot Environment Structures
 163 for a discussion on different layouts.
 164 .Pp
 165 No new boot environment is created with this command.
 166 .It Xo
 167 .Cm destroy
 168 .Op Fl \&Fo
 169 .Ar beName Ns Op Cm @ Ns Ar snapshot
 170 .Xc
 171 Destroy the given
 172 .Ar beName
 173 boot environment or
 174 .Ar beName Ns Cm @ Ns Ar snapshot
 175 snapshot without confirmation, unlike in
 176 .Xr beadm 1 .
 177 Specifying
 178 .Fl F
 179 will automatically unmount without confirmation.
 180 .Pp
 181 By default,
 182 .Nm
 183 will warn that it is not destroying the origin of
 184 .Ar beName .
 185 The
 186 .Fl o
 187 flag may be specified to destroy the origin as well.
 188 .It Cm export Ar sourceBe
 189 Export
 190 .Ar sourceBe
 191 to
 192 .Xr stdout 4 .
 193 .Xr stdout 4
 194 must be piped or redirected to a file.
 195 .It Cm import Ar targetBe
 196 Import
 197 .Ar targetBe
 198 from
 199 .Xr stdin 4 .
 200 .It Xo
 201 .Cm jail
 202 .Op Fl bU
 203 .Oo Bro Fl o Ar key Ns Cm = Ns Ar value | Fl u Ar key Brc Oc Ns ...
 204 .Ar beName
 205 .Op Ar utility Op Ar argument ...
 206 .Xc
 207 Create a jail of the given boot environment.
 208 Multiple
 209 .Fl o
 210 and
 211 .Fl u
 212 arguments may be specified.
 213 .Fl o
 214 will set a jail parameter, and
 215 .Fl u
 216 will unset a jail parameter.
 217 .Pp
 218 By default, jails are created in interactive mode and
 219 .Pa /bin/sh
 220 is
 221 executed within the jail.
 222 If
 223 .Ar utility
 224 is specified, it will be executed instead of
 225 .Pa /bin/sh .
 226 The jail will be destroyed and the boot environment unmounted when the command
 227 finishes executing, unless the
 228 .Fl U
 229 argument is specified.
 230 .Pp
 231 The
 232 .Fl b
 233 argument enables batch mode, thereby disabling interactive mode.
 234 The
 235 .Fl U
 236 argument will be ignored in batch mode.
 237 .Pp
 238 The
 239 .Va name ,
 240 .Va host.hostname ,
 241 and
 242 .Va path
 243 must be set, the default values are specified below.
 244 .Pp
 245 All
 246 .Ar key Ns Cm = Ns Ar value
 247 pairs are interpreted as jail parameters as described in
 248 .Xr jail 8 .
 249 The following default parameters are provided:
 250 .Bl -column "allow.mount.devfs" ""
 251 .It Va allow.mount Ta Cm true
 252 .It Va allow.mount.devfs Ta Cm true
 253 .It Va enforce_statfs Ta Cm 1
 254 .It Va name Ta Set to jail ID.
 255 .It Va host.hostname Ta Va bootenv
 256 .It Va path Ta Set to a path in Pa /tmp
 257 generated by
 258 .Xr libbe 3 .
 259 .El
 260 .Pp
 261 All default parameters may be overwritten.
 262 .It Xo
 263 .Cm list
 264 .Op Fl aDHs
 265 .Oo Bro Fl c Ar property | Fl C Ar property Brc Oc
 266 .Xc
 267 .Pp
 268 Display all boot environments.
 269 The
 270 .Em Active
 271 field indicates whether the boot environment is active now
 272 .Pq Em \&N ;
 273 active on reboot
 274 .Pq Em \&R ;
 275 is used on next boot once
 276 .Pq Em \&T ;
 277 or combination of
 278 .Pq Em \&NRT .
 279 .Pp
 280 .Bl -tag -width indent
 281 .It Fl a
 282 Display all datasets.
 283 .It Fl D
 284 Display the full space usage for each boot environment, assuming all
 285 other boot environments were destroyed.
 286 .It Fl H
 287 Used for scripting.
 288 Do not print headers and separate fields by a single tab instead of
 289 arbitrary white space.
 290 .It Fl s
 291 Display all snapshots as well.
 292 .It Fl c Ar property
 293 Sort boot environments by given property name.
 294 The following properties are supported:
 295 .Pp
 296 .Bl -tag -width 4n -offset indent -compact
 297 .It name (default output)
 298 .It creation
 299 .It origin
 300 .It used
 301 .It usedds
 302 .It usedsnap
 303 .It usedrefreserv
 304 .El
 305 .It Fl C Ar property
 306 Same as the
 307 .Fl c
 308 option, but displays in descending order.
 309 .El
 310 .Pp
 311 The
 312 .Fl D
 313 option is ignored when either the
 314 .Fl s
 315 or
 316 .Fl a
 317 option is used.
 318 .It Cm mount Ar beName Op Ar mountpoint
 319 Temporarily mount the boot environment.
 320 Mount at the specified
 321 .Ar mountpoint
 322 if provided.
 323 .It Cm rename Ar origBeName newBeName
 324 Rename the given
 325 .Ar origBeName
 326 to the given
 327 .Ar newBeName .
 328 The boot environment will not be unmounted in order for this rename to occur.
 329 .It Cm ujail Brq Ar jailId | jailName | beName
 330 .It Cm unjail Brq Ar jailId | jailName | beName
 331 Destroy the jail created from the given boot environment.
 332 .It Xo
 333 .Cm umount
 334 .Op Fl f
 335 .Ar beName
 336 .Xc
 337 .It Xo
 338 .Cm unmount
 339 .Op Fl f
 340 .Ar beName
 341 .Xc
 342 Unmount the given boot environment, if it is mounted.
 343 Specifying
 344 .Fl f
 345 will force the unmount if busy.
 346 .El
 347 .Pp
 348 .Nm
 349 prints usage information if
 350 .Fl h
 351 or
 352 .Fl \&?
 353 is specified.
 354 .Ss Boot Environment Structures
 355 The traditional
 356 .Fx
 357 boot environment layout, as created by the Auto ZFS option to
 358 .Xr bsdinstall 8 ,
 359 is a
 360 .Dq shallow
 361 boot environment structure, where boot environment datasets do not have any
 362 directly subordinate datasets.
 363 Instead, they're organized off in
 364 .Pa zroot/ROOT ,
 365 and they rely on datasets elsewhere in the pool having
 366 .Dv canmount
 367 set to
 368 .Dv off .
 369 For instance, a simplified pool may be laid out as such:
 370 .Bd -literal -offset indent
 371 % zfs list -o name,canmount,mountpoint
 372 NAME                    CANMOUNT        MOUNTPOINT
 373 zroot
 374 zroot/ROOT              noauto          none
 375 zroot/ROOT/default      noauto          none
 376 zroot/usr               off             /usr
 377 zroot/usr/home          on              /usr/home
 378 zroot/var               on              /var
 379 .Ed
 380 .Pp
 381 In that example,
 382 .Pa zroot/usr
 383 has
 384 .Dv canmount
 385 set to
 386 .Dv off ,
 387 thus files in
 388 .Pa /usr
 389 typically fall into the boot environment because this dataset is not mounted.
 390 .Pa zroot/usr/home
 391 is mounted, thus files in
 392 .Pa /usr/home
 393 are not in the boot environment.
 394 .Pp
 395 The other style of boot environments in use, frequently called
 396 .Dq deep boot environments ,
 397 organizes some or all of the boot environment as subordinate to the boot
 398 environment dataset.
 399 For example:
 400 .Bd -literal -offset indent
 401 % zfs list -o name,canmount,mountpoint
 402 NAME                            CANMOUNT        MOUNTPOINT
 403 zroot
 404 zroot/ROOT                      noauto          none
 405 zroot/ROOT/default              noauto          none
 406 zroot/ROOT/default/usr          noauto          /usr
 407 zroot/ROOT/default/usr/local    noauto          /usr/local
 408 zroot/var                       on              /var
 409 .Ed
 410 .Pp
 411 Note that the subordinate datasets now have
 412 .Dv canmount
 413 set to
 414 .Dv noauto .
 415 These are more obviously a part of the boot environment, as indicated by their
 416 positioning in the layout.
 417 These subordinate datasets will be mounted by the
 418 .Dv zfsbe
 419 .Xr rc 8
 420 script at boot time.
 421 In this example,
 422 .Pa /var
 423 is excluded from the boot environment.
 424 .Pp
 425 .Nm
 426 commands that have their own
 427 .Fl r
 428 operate on this second,
 429 .Dq deep
 430 style of boot environment, when the
 431 .Fl r
 432 flag is set.
 433 A future version of
 434 .Nm
 435 may default to handling both styles and deprecate the various
 436 .Fl r
 437 flags.
 438 \" .Sh EXAMPLES
 439 \" .Bl -bullet
 440 \" .It
 441 \" To fill in with jail upgrade example when behavior is firm.
 442 \" .El
 443 .Sh SEE ALSO
 444 .Xr libbe 3 ,
 445 .Xr beinstall.sh 8 ,
 446 .Xr jail 8 ,
 447 .Xr zfs 8 ,
 448 .Xr zpool 8
 449 .Sh HISTORY
 450 .Nm
 451 is based on
 452 .Xr beadm 1
 453 and was implemented as a project for the 2017 Summer of Code, along with
 454 .Xr libbe 3 .
 455 .Sh AUTHORS
 456 .Nm
 457 was written by
 458 .An Kyle Kneitinger (kneitinger) Aq Mt kyle@kneit.in .
 459 .Pp
 460 .Xr beadm 1
 461 was written and is maintained by
 462 .An Slawomir Wojciech Wojtczak (vermaden) Aq Mt vermaden@interia.pl .
 463 .Pp
 464 .An Bryan Drewery (bdrewery) Aq Mt bryan@shatow.net
 465 wrote the original
 466 .Xr beadm 1
 467 manual page that this one is derived from.