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