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