2 .\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD
4 .\" Copyright (c) 2017 Kyle J. Kneitinger <kyle@kneit.in>
5 .\" All rights reserved.
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
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.
21 .Dd September 11, 2019
26 .Nd Utility to manage boot environments on ZFS
37 .Op Fl e Brq Ar nonActiveBe | Ar beName Ns Cm @ Ns Ar snapshot
46 .Ar beName Ns Op Cm @ Ns Ar snapshot
56 .Oo Bro Fl o Ar key Ns Cm = Ns Ar value | Fl u Ar key Brc Oc Ns ...
58 .Op Ar utility Op Ar argument ...
64 .Oo Bro Fl c Ar property | Fl C Ar property Brc Oc
74 .Brq Cm ujail | unjail
75 .Brq Ar jailId | jailName
78 .Brq Cm umount | unmount
87 command is used to setup and interact with ZFS boot environments, which are
88 bootable clones of datasets.
91 allow the system to be upgraded, while preserving the old system environment in
92 a separate ZFS dataset.
94 The following commands are supported by
96 .Bl -tag -width activate
104 as the default boot filesystem.
107 flag is given, this takes effect only for the next boot.
111 Performs a silent sanity check on the current system.
112 If boot environments are supported and used,
114 will exit with a status code of 0.
115 Any other status code is not currently defined and may, in the future, grow
116 special meaning for different degrees of sanity check failures.
120 .Op Fl e Brq Ar nonActiveBe | Ar beName Ns Cm @ Ns Ar snapshot
123 Create a new boot environment named
128 flag is given, a recursive boot environment will be made.
132 flag is specified, the new environment will be cloned from the given
135 .Ar beName Ns Cm @ Ns Ar snapshot .
136 Otherwise, the new environment will be created from the currently booted environment.
140 is creating from another boot environment, a snapshot of that boot environment will be created to clone from.
146 Create a snapshot of the boot environment named
151 flag is given, a recursive snapshot of the boot environment will be created.
152 A snapshot is created for each descendant dataset of the boot environment.
154 No new boot environment is created with this command.
158 .Ar beName Ns Op Cm @ Ns Ar snapshot
163 .Ar beName Ns Cm @ Ns Ar snapshot
164 snapshot without confirmation, unlike in
168 will automatically unmount without confirmation.
172 will warn that it is not destroying the origin of
176 flag may be specified to destroy the origin as well.
177 .It Cm export Ar sourceBe
183 must be piped or redirected to a file.
184 .It Cm import Ar targetBe
192 .Oo Bro Fl o Ar key Ns Cm = Ns Ar value | Fl u Ar key Brc Oc Ns ...
194 .Op Ar utility Op Ar argument ...
196 Create a jail of the given boot environment.
201 arguments may be specified.
203 will set a jail parameter, and
205 will unset a jail parameter.
207 By default, jails are created in interactive mode and
210 executed within the jail.
213 is specified, it will be executed instead of
215 The jail will be destroyed and the boot environment unmounted when the command
216 finishes executing, unless the
218 argument is specified.
222 argument enables batch mode, thereby disabling interactive mode.
225 argument will be ignored in batch mode.
232 must be set, the default values are specified below.
235 .Ar key Ns Cm = Ns Ar value
236 pairs are interpreted as jail parameters as described in
238 The following default parameters are provided:
239 .Bl -column "allow.mount.devfs" ""
240 .It Va allow.mount Ta Cm true
241 .It Va allow.mount.devfs Ta Cm true
242 .It Va enforce_statfs Ta Cm 1
243 .It Va name Ta Set to jail ID.
244 .It Va host.hostname Ta Va bootenv
245 .It Va path Ta Set to a path in Pa /tmp
250 All default parameters may be overwritten.
254 .Oo Bro Fl c Ar property | Fl C Ar property Brc Oc
257 Display all boot environments.
260 field indicates whether the boot environment is active now
267 .Bl -tag -width indent
269 Display all datasets.
271 Display the full space usage for each boot environment, assuming all
272 other boot environments were destroyed.
275 Do not print headers and separate fields by a single tab instead of
276 arbitrary white space.
278 Display all snapshots as well.
280 Sort boot environments by given property name.
281 The following properties are supported:
283 .Bl -tag -width 4n -offset indent -compact
284 .It name (default output)
295 option, but displays in descending order.
300 option is ignored when either the
305 .It Cm mount Ar beName Op Ar mountpoint
306 Temporarily mount the boot environment.
307 Mount at the specified
310 .It Cm rename Ar origBeName newBeName
315 The boot environment will not be unmounted in order for this rename to occur.
316 .It Cm ujail Bro Ar jailId | jailName Brc Ar beName
317 .It Cm unjail Bro Ar jailId | jailName Brc Ar beName
318 Destroy the jail created from the given boot environment.
329 Unmount the given boot environment, if it is mounted.
332 will force the unmount if busy.
336 prints usage information if
344 To fill in with jail upgrade example when behavior is firm.
356 and was implemented as a project for the 2017 Summer of Code, along with
361 .An Kyle Kneitinger (kneitinger) Aq Mt kyle@kneit.in .
364 was written and is maintained by
365 .An Slawomir Wojciech Wojtczak (vermaden) Aq Mt vermaden@interia.pl .
367 .An Bryan Drewery (bdrewery) Aq Mt bryan@shatow.net
370 manual page that this one is derived from.