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