sbin/bectl/bectl.8

   1 .\"
   2 .\" be - Utility to manage Boot Environments on the ZFS filesystem
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\"
  14 .\"     @(#)be.1
  15 .\" $FreeBSD$
  16 .\"
  17 .Dd June 15, 2017
  18 .Dt BE 1
  19 .Os FreeBSD
  20 .Sh NAME
  21 .Nm be
  22 .Nd Utility to manage Boot Environments on ZFS
  23 .Sh SYNOPSIS
  24 .Nm
  25 activate
  26 .Op Fl t
  27 .Ao Ar beName Ac
  28 .Nm
  29 create
  30 .Op Fl r
  31 .Op Fl e Ar nonActiveBe | Fl e Ar beName@snapshot
  32 .Ao Ar beName Ac
  33 .Nm
  34 create
  35 .Op Fl r
  36 .Ao Ar beName@snapshot Ac
  37 .Nm
  38 destroy
  39 .Op Fl F
  40 .Ao Ar beName | beName@snapshot Ac
  41 .Nm
  42 jail
  43 .Ao Ar jailID | jailName Ac
  44 .Ao Ar bootenv Ac
  45 .Nm
  46 list
  47 .Op Fl a
  48 .Op Fl D
  49 .Op Fl H
  50 .Op Fl s
  51 .Nm
  52 mount
  53 .Ao Ar beName Ac
  54 .Op mountpoint
  55 .Nm
  56 rename
  57 .Ao Ar origBeName Ac
  58 .Ao Ar newBeName Ac
  59 .Nm
  60 { ujail | unjail }
  61 .Ao Ar jailID | jailName Ac
  62 .Ao Ar bootenv Ac
  63 .Nm
  64 { umount | unmount }
  65 .Op Fl f
  66 .Ao Ar beName Ac
  67 .Sh DESCRIPTION
  68 The
  69 .Nm
  70 command is used to setup and interact with ZFS boot environments, which are bootable clones of datasets.
  71 .Pp
  72 .Em Boot Environments
  73 allows the system to be upgraded, while preserving the old system environment in a separate ZFS dataset.
  74 .Pp
  75 .Sh COMMANDS
  76 The following commands are supported by
  77 .Nm :
  78 .Bl -tag -width activate
  79 .It Ic activate
  80 .Op Fl t
  81 .Ar <beName>
  82 .Pp
  83 Activate the given
  84 .Ar beName
  85 as the default boot filesystem. If the
  86 .Op Fl t
  87 flag is given, this takes effect only for the next boot.
  88 .Pp
  89 .It Ic create
  90 .Op Fl r
  91 .Op Fl e Ar nonActiveBe | Fl e Ar beName@snapshot
  92 .Ao Ar beName Ac
  93 .Pp
  94 Creates a new boot environment named
  95 .Ar beName .
  96 If the -e param is specified, the new environment will be cloned from the given
  97 .Ar nonActiveBe | Ar beName@snapshot .
  98 If the
  99 .Op Fl r
 100 flag is given, a recursive boot environment will be made.
 101 .Pp
 102 .It Ic create
 103 .Op Fl r
 104 .Ao Ar beName@snapshot Ac
 105 .Pp
 106 Creates a snapshot of the existing boot environment named
 107 .Ar beName .
 108 If the
 109 .Op Fl r
 110 flag is given, a recursive boot environment will be made.
 111 .Pp
 112 .It Ic destroy
 113 .Op Fl F
 114 .Ao Ar beName | beName@snapshot Ac
 115 .Pp
 116 Destroys the given
 117 .Ar beName
 118 boot environment or
 119 .Ar beName@snapshot
 120 snapshot.
 121 Specifying
 122 .Fl F
 123 will automatically unmount without confirmation.
 124 .Pp
 125 .It Ic jail
 126 .Ao Ar jailID | jailName Ac
 127 .Ao Ar bootenv Ac
 128 .Pp
 129 Creates a jail of the given boot environment.
 130 .Pp
 131 .It Ic list
 132 .Op Fl a
 133 .Op Fl D
 134 .Op Fl H
 135 .Op Fl s
 136 .Pp
 137 Displays all boot environments.
 138 The Active field indicates whether the boot environment is active now (N); active on reboot (R); or both (NR).
 139 .Pp
 140 If
 141 .Fl a
 142 is used, display all datasets.
 143 If
 144 .Fl D
 145 is used, display the full space usage for each boot environment, assuming all other boot environments were destroyed.
 146 The
 147 .Fl H
 148 option is used for scripting. It does not print headers and separate fields by a single tab instead of arbitrary white space.
 149 If
 150 .Fl s
 151 is used, display all snapshots as well.
 152 .Pp
 153 .It Ic mount
 154 .Ao Ar beName Ac
 155 .Op mountpoint
 156 .Pp
 157 Temporarily mount the boot environment.
 158 Mount at the specified
 159 .Ar mountpoint
 160 if provided.
 161 .Pp
 162 .It Ic rename Ao Ar origBeName Ac Ao Ar newBeName Ac
 163 .Pp
 164 Renames the given nonactive
 165 .Ar origBeName
 166 to the given
 167 .Ar newBeName
 168 .Pp
 169 .It Ic unmount
 170 .Op Fl f
 171 .Ao Ar beName Ac
 172 .Pp
 173 Unmount the given boot environment, if it is mounted.
 174 Specifying
 175 .Fl f
 176 will force the unmount if busy.
 177 .Pp
 178 .It Ic unjail
 179 .Ao Ar beName Ac
 180 .Pp
 181 Destroys the jail created from the given boot environment.
 182 .Pp
 183 .El
 184 .Sh EXAMPLES
 185 .Bl -bullet
 186 .It
 187 To fill in with jail upgrade example when behavior is firm.
 188 .Pp
 189 .Sh SEE ALSO
 190 .Xr jail 8 ,
 191 .Xr zfs 8 ,
 192 .Xr zpool 8
 193 .Sh HISTORY
 194 .Nm
 195 is based on
 196 .Xr beadm 1
 197 and was implemented as a project for the 2017 Summer of Code, along with
 198 .Xr libbe 3 .
 199 .Sh AUTHORS
 200 .Bl -bullet
 201 .It
 202 Kyle Kneitinger (kneitinger)
 203 .Ar kyle@kneit.in
 204 .Pp
 205 Creator of
 206 .Nm .
 207 .It
 208 Slawomir Wojciech Wojtczak (vermaden)
 209 .Ar vermaden@interia.pl
 210 .Pp
 211 Creator and maintainer of
 212 .Xr beadm 1 .
 213 .It
 214 Bryan Drewery (bdrewery)
 215 .Ar bryan@shatow.net
 216 .Pp
 217 Wrote the original
 218 .Xr beadm 1
 219 manual page that this one is derived from.
 220 .El