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