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