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