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