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