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.
26 .Nd Utility to manage boot environments on ZFS
35 .Op Fl e Brq Ar nonActiveBe | Ar beName Ns Cm @ Ns Ar snapshot
40 .Ar beName Ns Op Cm @ Ns Ar snapshot
50 .Oo Bro Fl o Ar key Ns Cm = Ns Ar value | Fl u Ar key Brc Oc Ns ...
52 .Op Ar utility Op Ar argument ...
65 .Brq Cm ujail | unjail
66 .Brq Ar jailId | jailName
69 .Brq Cm umount | unmount
78 command is used to setup and interact with ZFS boot environments, which are
79 bootable clones of datasets.
82 allow the system to be upgraded, while preserving the old system environment in
83 a separate ZFS dataset.
85 The following commands are supported by
87 .Bl -tag -width activate
95 as the default boot filesystem.
98 flag is given, this takes effect only for the next boot.
102 .Op Fl e Brq Ar nonActiveBe | Ar beName Ns Cm @ Ns Ar snapshot
105 Create a new boot environment named
110 flag is given, a recursive boot environment will be made.
114 flag is specified, the new environment will be cloned from the given
117 .Ar beName Ns Cm @ Ns Ar snapshot .
118 Otherwise, the new environment will be created from the currently booted environment.
122 is creating from another boot environment, a snapshot of that boot environment will be created to clone from.
126 .Ar beName Ns Op Cm @ Ns Ar snapshot
131 .Ar beName Ns Cm @ Ns Ar snapshot
132 snapshot without confirmation, unlike in
136 will automatically unmount without confirmation.
140 will warn that it is not destroying the origin of
144 flag may be specified to destroy the origin as well.
145 .It Cm export Ar sourceBe
151 must be piped or redirected to a file.
152 .It Cm import Ar targetBe
160 .Oo Bro Fl o Ar key Ns Cm = Ns Ar value | Fl u Ar key Brc Oc Ns ...
162 .Op Ar utility Op Ar argument ...
164 Create a jail of the given boot environment.
169 arguments may be specified.
171 will set a jail parameter, and
173 will unset a jail parameter.
175 By default, jails are created in interactive mode and
178 executed within the jail.
181 is specified, it will be executed instead of
183 The jail will be destroyed and the boot environment unmounted when the command
184 finishes executing, unless the
186 argument is specified.
190 argument enables batch mode, thereby disabling interactive mode.
193 argument will be ignored in batch mode.
200 must be set, the default values are specified below.
203 .Ar key Ns Cm = Ns Ar value
204 pairs are interpreted as jail parameters as described in
206 The following default parameters are provided:
207 .Bl -column "allow.mount.devfs" ""
208 .It Va allow.mount Ta Cm true
209 .It Va allow.mount.devfs Ta Cm true
210 .It Va enforce_statfs Ta Cm 1
211 .It Va name Ta Set to jail ID.
212 .It Va host.hostname Ta Va bootenv
213 .It Va path Ta Set to a path in Pa /tmp
218 All default parameters may be overwritten.
219 .It Cm list Op Fl aDHs
220 Display all boot environments.
223 field indicates whether the boot environment is active now
232 is used, display all datasets.
235 is used, display the full space usage for each boot environment, assuming all
236 other boot environments were destroyed.
239 option is used for scripting.
240 It does not print headers and separate fields by a single tab instead of
241 arbitrary white space.
244 is used, display all snapshots as well.
245 .It Cm mount Ar beName Op Ar mountpoint
246 Temporarily mount the boot environment.
247 Mount at the specified
250 .It Cm rename Ar origBeName newBeName
255 The boot environment will not be unmounted in order for this rename to occur.
256 .It Cm ujail Bro Ar jailId | jailName Brc Ar beName
257 .It Cm unjail Bro Ar jailId | jailName Brc Ar beName
258 Destroy the jail created from the given boot environment.
269 Unmount the given boot environment, if it is mounted.
272 will force the unmount if busy.
276 prints usage information if
284 To fill in with jail upgrade example when behavior is firm.
296 and was implemented as a project for the 2017 Summer of Code, along with
301 .An Kyle Kneitinger (kneitinger) Aq Mt kyle@kneit.in .
304 was written and is maintained by
305 .An Slawomir Wojciech Wojtczak (vermaden) Aq Mt vermaden@interia.pl .
307 .An Bryan Drewery (bdrewery) Aq Mt bryan@shatow.net
310 manual page that this one is derived from.