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
77 .Brq Cm umount | unmount
86 command is used to setup and interact with ZFS boot environments, which are
87 bootable clones of datasets.
90 allow the system to be upgraded, while preserving the old system environment in
91 a separate ZFS dataset.
93 The following commands are supported by
95 .Bl -tag -width activate
103 as the default boot filesystem.
106 flag is given, this takes effect only for the next boot.
109 removes temporary boot once configuration.
110 Without temporary configuration, the next boot will use zfs dataset specified
117 Performs a silent sanity check on the current system.
118 If boot environments are supported and used,
120 will exit with a status code of 0.
121 Any other status code is not currently defined and may, in the future, grow
122 special meaning for different degrees of sanity check failures.
126 .Op Fl e Brq Ar nonActiveBe | Ar beName Ns Cm @ Ns Ar snapshot
129 Create a new boot environment named
134 flag is given, a recursive boot environment will be made.
138 flag is specified, the new environment will be cloned from the given
141 .Ar beName Ns Cm @ Ns Ar snapshot .
142 Otherwise, the new environment will be created from the currently booted environment.
146 is creating from another boot environment, a snapshot of that boot environment will be created to clone from.
152 Create a snapshot of the boot environment named
157 flag is given, a recursive snapshot of the boot environment will be created.
158 A snapshot is created for each descendant dataset of the boot environment.
160 No new boot environment is created with this command.
164 .Ar beName Ns Op Cm @ Ns Ar snapshot
169 .Ar beName Ns Cm @ Ns Ar snapshot
170 snapshot without confirmation, unlike in
174 will automatically unmount without confirmation.
178 will warn that it is not destroying the origin of
182 flag may be specified to destroy the origin as well.
183 .It Cm export Ar sourceBe
189 must be piped or redirected to a file.
190 .It Cm import Ar targetBe
198 .Oo Bro Fl o Ar key Ns Cm = Ns Ar value | Fl u Ar key Brc Oc Ns ...
200 .Op Ar utility Op Ar argument ...
202 Create a jail of the given boot environment.
207 arguments may be specified.
209 will set a jail parameter, and
211 will unset a jail parameter.
213 By default, jails are created in interactive mode and
216 executed within the jail.
219 is specified, it will be executed instead of
221 The jail will be destroyed and the boot environment unmounted when the command
222 finishes executing, unless the
224 argument is specified.
228 argument enables batch mode, thereby disabling interactive mode.
231 argument will be ignored in batch mode.
238 must be set, the default values are specified below.
241 .Ar key Ns Cm = Ns Ar value
242 pairs are interpreted as jail parameters as described in
244 The following default parameters are provided:
245 .Bl -column "allow.mount.devfs" ""
246 .It Va allow.mount Ta Cm true
247 .It Va allow.mount.devfs Ta Cm true
248 .It Va enforce_statfs Ta Cm 1
249 .It Va name Ta Set to jail ID.
250 .It Va host.hostname Ta Va bootenv
251 .It Va path Ta Set to a path in Pa /tmp
256 All default parameters may be overwritten.
260 .Oo Bro Fl c Ar property | Fl C Ar property Brc Oc
263 Display all boot environments.
266 field indicates whether the boot environment is active now
270 is used on next boot once
275 .Bl -tag -width indent
277 Display all datasets.
279 Display the full space usage for each boot environment, assuming all
280 other boot environments were destroyed.
283 Do not print headers and separate fields by a single tab instead of
284 arbitrary white space.
286 Display all snapshots as well.
288 Sort boot environments by given property name.
289 The following properties are supported:
291 .Bl -tag -width 4n -offset indent -compact
292 .It name (default output)
303 option, but displays in descending order.
308 option is ignored when either the
313 .It Cm mount Ar beName Op Ar mountpoint
314 Temporarily mount the boot environment.
315 Mount at the specified
318 .It Cm rename Ar origBeName newBeName
323 The boot environment will not be unmounted in order for this rename to occur.
324 .It Cm ujail Bro Ar jailId | jailName Brc Ar beName
325 .It Cm unjail Bro Ar jailId | jailName Brc Ar beName
326 Destroy the jail created from the given boot environment.
337 Unmount the given boot environment, if it is mounted.
340 will force the unmount if busy.
344 prints usage information if
352 \" To fill in with jail upgrade example when behavior is firm.
364 and was implemented as a project for the 2017 Summer of Code, along with
369 .An Kyle Kneitinger (kneitinger) Aq Mt kyle@kneit.in .
372 was written and is maintained by
373 .An Slawomir Wojciech Wojtczak (vermaden) Aq Mt vermaden@interia.pl .
375 .An Bryan Drewery (bdrewery) Aq Mt bryan@shatow.net
378 manual page that this one is derived from.