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
44 .Ar beName Ns Op Cm @ Ns Ar snapshot
54 .Oo Bro Fl o Ar key Ns Cm = Ns Ar value | Fl u Ar key Brc Oc Ns ...
56 .Op Ar utility Op Ar argument ...
69 .Brq Cm ujail | unjail
70 .Brq Ar jailId | jailName
73 .Brq Cm umount | unmount
82 command is used to setup and interact with ZFS boot environments, which are
83 bootable clones of datasets.
86 allow the system to be upgraded, while preserving the old system environment in
87 a separate ZFS dataset.
89 The following commands are supported by
91 .Bl -tag -width activate
99 as the default boot filesystem.
102 flag is given, this takes effect only for the next boot.
106 .Op Fl e Brq Ar nonActiveBe | Ar beName Ns Cm @ Ns Ar snapshot
109 Create a new boot environment named
114 flag is given, a recursive boot environment will be made.
118 flag is specified, the new environment will be cloned from the given
121 .Ar beName Ns Cm @ Ns Ar snapshot .
122 Otherwise, the new environment will be created from the currently booted environment.
126 is creating from another boot environment, a snapshot of that boot environment will be created to clone from.
132 Create a snapshot of the boot environment named
137 flag is given, a recursive snapshot of the boot environment will be created.
138 A snapshot is created for each descendant dataset of the boot environment.
140 No new boot environment is created with this command.
144 .Ar beName Ns Op Cm @ Ns Ar snapshot
149 .Ar beName Ns Cm @ Ns Ar snapshot
150 snapshot without confirmation, unlike in
154 will automatically unmount without confirmation.
158 will warn that it is not destroying the origin of
162 flag may be specified to destroy the origin as well.
163 .It Cm export Ar sourceBe
169 must be piped or redirected to a file.
170 .It Cm import Ar targetBe
178 .Oo Bro Fl o Ar key Ns Cm = Ns Ar value | Fl u Ar key Brc Oc Ns ...
180 .Op Ar utility Op Ar argument ...
182 Create a jail of the given boot environment.
187 arguments may be specified.
189 will set a jail parameter, and
191 will unset a jail parameter.
193 By default, jails are created in interactive mode and
196 executed within the jail.
199 is specified, it will be executed instead of
201 The jail will be destroyed and the boot environment unmounted when the command
202 finishes executing, unless the
204 argument is specified.
208 argument enables batch mode, thereby disabling interactive mode.
211 argument will be ignored in batch mode.
218 must be set, the default values are specified below.
221 .Ar key Ns Cm = Ns Ar value
222 pairs are interpreted as jail parameters as described in
224 The following default parameters are provided:
225 .Bl -column "allow.mount.devfs" ""
226 .It Va allow.mount Ta Cm true
227 .It Va allow.mount.devfs Ta Cm true
228 .It Va enforce_statfs Ta Cm 1
229 .It Va name Ta Set to jail ID.
230 .It Va host.hostname Ta Va bootenv
231 .It Va path Ta Set to a path in Pa /tmp
236 All default parameters may be overwritten.
237 .It Cm list Op Fl aDHs
238 Display all boot environments.
241 field indicates whether the boot environment is active now
250 is used, display all datasets.
253 is used, display the full space usage for each boot environment, assuming all
254 other boot environments were destroyed.
257 option is used for scripting.
258 It does not print headers and separate fields by a single tab instead of
259 arbitrary white space.
262 is used, display all snapshots as well.
263 .It Cm mount Ar beName Op Ar mountpoint
264 Temporarily mount the boot environment.
265 Mount at the specified
268 .It Cm rename Ar origBeName newBeName
273 The boot environment will not be unmounted in order for this rename to occur.
274 .It Cm ujail Bro Ar jailId | jailName Brc Ar beName
275 .It Cm unjail Bro Ar jailId | jailName Brc Ar beName
276 Destroy the jail created from the given boot environment.
287 Unmount the given boot environment, if it is mounted.
290 will force the unmount if busy.
294 prints usage information if
302 To fill in with jail upgrade example when behavior is firm.
314 and was implemented as a project for the 2017 Summer of Code, along with
319 .An Kyle Kneitinger (kneitinger) Aq Mt kyle@kneit.in .
322 was written and is maintained by
323 .An Slawomir Wojciech Wojtczak (vermaden) Aq Mt vermaden@interia.pl .
325 .An Bryan Drewery (bdrewery) Aq Mt bryan@shatow.net
328 manual page that this one is derived from.