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