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