2 .\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD
4 .\" Copyright (c) 2017 Kyle J. Kneitinger <kyle@kneit.in>
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
25 .Nd Utility to manage boot environments on ZFS
36 .Op Fl e Brq Ar nonActiveBe | Ar beName Ns Cm @ Ns Ar snapshot
45 .Ar beName Ns Op Cm @ Ns Ar snapshot
55 .Oo Bro Fl o Ar key Ns Cm = Ns Ar value | Fl u Ar key Brc Oc Ns ...
57 .Op Ar utility Op Ar argument ...
63 .Oo Bro Fl c Ar property | Fl C Ar property Brc Oc
73 .Brq Cm ujail | unjail
74 .Brq Ar jailId | jailName | beName
76 .Brq Cm umount | unmount
85 command is used to setup and interact with ZFS boot environments, which are
86 bootable clones of datasets.
89 allow the system to be upgraded, while preserving the old system environment in
90 a separate ZFS dataset.
92 The following commands are supported by
94 .Bl -tag -width activate
102 as the default boot filesystem.
105 flag is given, this takes effect only for the next boot.
108 removes temporary boot once configuration.
109 Without temporary configuration, the next boot will use zfs dataset specified
116 Performs a silent sanity check on the current system.
117 If boot environments are supported and used,
119 will exit with a status code of 0.
120 Any other status code is not currently defined and may, in the future, grow
121 special meaning for different degrees of sanity check failures.
125 .Op Fl e Brq Ar nonActiveBe | Ar beName Ns Cm @ Ns Ar snapshot
128 Create a new boot environment named
133 flag is given, a recursive boot environment will be made.
135 .Sx Boot Environment Structures
136 for a discussion on different layouts.
140 flag is specified, the new environment will be cloned from the given
143 .Ar beName Ns Cm @ Ns Ar snapshot .
144 Otherwise, the new environment will be created from the currently booted environment.
148 is creating from another boot environment, a snapshot of that boot environment will be created to clone from.
154 Create a snapshot of the boot environment named
159 flag is given, a recursive snapshot of the boot environment will be created.
160 A snapshot is created for each descendant dataset of the boot environment.
162 .Sx Boot Environment Structures
163 for a discussion on different layouts.
165 No new boot environment is created with this command.
169 .Ar beName Ns Op Cm @ Ns Ar snapshot
174 .Ar beName Ns Cm @ Ns Ar snapshot
175 snapshot without confirmation, unlike in
179 will automatically unmount without confirmation.
183 will warn that it is not destroying the origin of
187 flag may be specified to destroy the origin as well.
188 .It Cm export Ar sourceBe
194 must be piped or redirected to a file.
195 .It Cm import Ar targetBe
203 .Oo Bro Fl o Ar key Ns Cm = Ns Ar value | Fl u Ar key Brc Oc Ns ...
205 .Op Ar utility Op Ar argument ...
207 Create a jail of the given boot environment.
212 arguments may be specified.
214 will set a jail parameter, and
216 will unset a jail parameter.
218 By default, jails are created in interactive mode and
221 executed within the jail.
224 is specified, it will be executed instead of
226 The jail will be destroyed and the boot environment unmounted when the command
227 finishes executing, unless the
229 argument is specified.
233 argument enables batch mode, thereby disabling interactive mode.
236 argument will be ignored in batch mode.
243 must be set, the default values are specified below.
246 .Ar key Ns Cm = Ns Ar value
247 pairs are interpreted as jail parameters as described in
249 The following default parameters are provided:
250 .Bl -column "allow.mount.devfs" ""
251 .It Va allow.mount Ta Cm true
252 .It Va allow.mount.devfs Ta Cm true
253 .It Va enforce_statfs Ta Cm 1
254 .It Va name Ta Set to jail ID.
255 .It Va host.hostname Ta Va bootenv
256 .It Va path Ta Set to a path in Pa /tmp
261 All default parameters may be overwritten.
265 .Oo Bro Fl c Ar property | Fl C Ar property Brc Oc
268 Display all boot environments.
271 field indicates whether the boot environment is active now
275 is used on next boot once
280 .Bl -tag -width indent
282 Display all datasets.
284 Display the full space usage for each boot environment, assuming all
285 other boot environments were destroyed.
288 Do not print headers and separate fields by a single tab instead of
289 arbitrary white space.
291 Display all snapshots as well.
293 Sort boot environments by given property name.
294 The following properties are supported:
296 .Bl -tag -width 4n -offset indent -compact
297 .It name (default output)
308 option, but displays in descending order.
313 option is ignored when either the
318 .It Cm mount Ar beName Op Ar mountpoint
319 Temporarily mount the boot environment.
320 Mount at the specified
323 .It Cm rename Ar origBeName newBeName
328 The boot environment will not be unmounted in order for this rename to occur.
329 .It Cm ujail Brq Ar jailId | jailName | beName
330 .It Cm unjail Brq Ar jailId | jailName | beName
331 Destroy the jail created from the given boot environment.
342 Unmount the given boot environment, if it is mounted.
345 will force the unmount if busy.
349 prints usage information if
354 .Ss Boot Environment Structures
357 boot environment layout, as created by the Auto ZFS option to
361 boot environment structure, where boot environment datasets do not have any
362 directly subordinate datasets.
363 Instead, they're organized off in
365 and they rely on datasets elsewhere in the pool having
369 For instance, a simplified pool may be laid out as such:
370 .Bd -literal -offset indent
371 % zfs list -o name,canmount,mountpoint
372 NAME CANMOUNT MOUNTPOINT
374 zroot/ROOT noauto none
375 zroot/ROOT/default noauto none
377 zroot/usr/home on /usr/home
389 typically fall into the boot environment because this dataset is not mounted.
391 is mounted, thus files in
393 are not in the boot environment.
395 The other style of boot environments in use, frequently called
396 .Dq deep boot environments ,
397 organizes some or all of the boot environment as subordinate to the boot
400 .Bd -literal -offset indent
401 % zfs list -o name,canmount,mountpoint
402 NAME CANMOUNT MOUNTPOINT
404 zroot/ROOT noauto none
405 zroot/ROOT/default noauto none
406 zroot/ROOT/default/usr noauto /usr
407 zroot/ROOT/default/usr/local noauto /usr/local
411 Note that the subordinate datasets now have
415 These are more obviously a part of the boot environment, as indicated by their
416 positioning in the layout.
417 These subordinate datasets will be mounted by the
423 is excluded from the boot environment.
426 commands that have their own
428 operate on this second,
430 style of boot environment, when the
435 may default to handling both styles and deprecate the various
441 \" To fill in with jail upgrade example when behavior is firm.
453 and was implemented as a project for the 2017 Summer of Code, along with
458 .An Kyle Kneitinger (kneitinger) Aq Mt kyle@kneit.in .
461 was written and is maintained by
462 .An Slawomir Wojciech Wojtczak (vermaden) Aq Mt vermaden@interia.pl .
464 .An Bryan Drewery (bdrewery) Aq Mt bryan@shatow.net
467 manual page that this one is derived from.