xref: /freebsd/sbin/bectl/bectl.8 (revision 9768746b) 
1.\"
2.\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD
3.\"
4.\" Copyright (c) 2017 Kyle J. Kneitinger <kyle@kneit.in>
5.\"
6.\" Redistribution and use in source and binary forms, with or without
7.\" modification, are permitted provided that the following conditions
8.\" are met:
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.
14.\"
15.\"
16.\"     @(#)be.1
17.\"
18.\" $FreeBSD$
19.\"
20.Dd March 31, 2022
21.Dt BECTL 8
22.Os
23.Sh NAME
24.Nm bectl
25.Nd Utility to manage boot environments on ZFS
26.Sh SYNOPSIS
27.Nm
28.Cm activate
29.Op Fl t | Fl T
30.Ar beName
31.Nm
32.Cm check
33.Nm
34.Cm create
35.Op Fl r
36.Op Fl e Brq Ar nonActiveBe | Ar beName Ns Cm @ Ns Ar snapshot
37.Ar newBeName
38.Nm
39.Cm create
40.Op Fl r
41.Ar beName@snapshot
42.Nm
43.Cm destroy
44.Op Fl \&Fo
45.Ar beName Ns Op Cm @ Ns Ar snapshot
46.Nm
47.Cm export
48.Ar sourceBe
49.Nm
50.Cm import
51.Ar targetBe
52.Nm
53.Cm jail
54.Op Fl bU
55.Oo Bro Fl o Ar key Ns Cm = Ns Ar value | Fl u Ar key Brc Oc Ns ...
56.Ar beName
57.Op Ar utility Op Ar argument ...
58.Nm
59.Cm list
60.Op Fl aDHs
61.Op Fl c Ar property
62.Op Fl C Ar property
63.Oo Bro Fl c Ar property | Fl C Ar property Brc Oc
64.Nm
65.Cm mount
66.Ar beName
67.Op Ar mountpoint
68.Nm
69.Cm rename
70.Ar origBeName
71.Ar newBeName
72.Nm
73.Brq Cm ujail | unjail
74.Brq Ar jailId | jailName | beName
75.Nm
76.Brq Cm umount | unmount
77.Op Fl f
78.Ar beName
79.Pp
80.Nm
81.Op Fl h\&?
82.Sh DESCRIPTION
83The
84.Nm
85command is used to setup and interact with ZFS boot environments, which are
86bootable clones of datasets.
87.Pp
88Boot environments
89allow the system to be upgraded, while preserving the old system environment in
90a separate ZFS dataset.
91.Pp
92The following commands are supported by
93.Nm :
94.Bl -tag -width activate
95.It Xo
96.Cm activate
97.Op Fl t | Fl T
98.Ar beName
99.Xc
100Activate the given
101.Ar beName
102as the default boot filesystem.
103If the
104.Fl t
105flag is given, this takes effect only for the next boot.
106Flag
107.Fl T
108removes temporary boot once configuration.
109Without temporary configuration, the next boot will use zfs dataset specified
110in boot pool
111.Ar bootfs
112property.
113.It Xo
114.Cm check
115.Xc
116Performs a silent sanity check on the current system.
117If boot environments are supported and used,
118.Nm
119will exit with a status code of 0.
120Any other status code is not currently defined and may, in the future, grow
121special meaning for different degrees of sanity check failures.
122.It Xo
123.Cm create
124.Op Fl r
125.Op Fl e Brq Ar nonActiveBe | Ar beName Ns Cm @ Ns Ar snapshot
126.Ar newBeName
127.Xc
128Create a new boot environment named
129.Ar newBeName .
130.Pp
131If the
132.Fl r
133flag is given, a recursive boot environment will be made.
134See
135.Sx Boot Environment Structures
136for a discussion on different layouts.
137.Pp
138If the
139.Fl e
140flag is specified, the new environment will be cloned from the given
141.Ar nonActiveBe
142or
143.Ar beName Ns Cm @ Ns Ar snapshot .
144Otherwise, the new environment will be created from the currently booted environment.
145.Pp
146If
147.Nm
148is creating from another boot environment, a snapshot of that boot environment will be created to clone from.
149.It Xo
150.Cm create
151.Op Fl r
152.Ar beName@snapshot
153.Xc
154Create a snapshot of the boot environment named
155.Ar beName .
156.Pp
157If the
158.Fl r
159flag is given, a recursive snapshot of the boot environment will be created.
160A snapshot is created for each descendant dataset of the boot environment.
161See
162.Sx Boot Environment Structures
163for a discussion on different layouts.
164.Pp
165No new boot environment is created with this command.
166.It Xo
167.Cm destroy
168.Op Fl \&Fo
169.Ar beName Ns Op Cm @ Ns Ar snapshot
170.Xc
171Destroy the given
172.Ar beName
173boot environment or
174.Ar beName Ns Cm @ Ns Ar snapshot
175snapshot without confirmation, unlike in
176.Xr beadm 1 .
177Specifying
178.Fl F
179will automatically unmount without confirmation.
180.Pp
181By default,
182.Nm
183will warn that it is not destroying the origin of
184.Ar beName .
185The
186.Fl o
187flag may be specified to destroy the origin as well.
188.It Cm export Ar sourceBe
189Export
190.Ar sourceBe
191to
192.Xr stdout 4 .
193.Xr stdout 4
194must be piped or redirected to a file.
195.It Cm import Ar targetBe
196Import
197.Ar targetBe
198from
199.Xr stdin 4 .
200.It Xo
201.Cm jail
202.Op Fl bU
203.Oo Bro Fl o Ar key Ns Cm = Ns Ar value | Fl u Ar key Brc Oc Ns ...
204.Ar beName
205.Op Ar utility Op Ar argument ...
206.Xc
207Create a jail of the given boot environment.
208Multiple
209.Fl o
210and
211.Fl u
212arguments may be specified.
213.Fl o
214will set a jail parameter, and
215.Fl u
216will unset a jail parameter.
217.Pp
218By default, jails are created in interactive mode and
219.Pa /bin/sh
220is
221executed within the jail.
222If
223.Ar utility
224is specified, it will be executed instead of
225.Pa /bin/sh .
226The jail will be destroyed and the boot environment unmounted when the command
227finishes executing, unless the
228.Fl U
229argument is specified.
230.Pp
231The
232.Fl b
233argument enables batch mode, thereby disabling interactive mode.
234The
235.Fl U
236argument will be ignored in batch mode.
237.Pp
238The
239.Va name ,
240.Va host.hostname ,
241and
242.Va path
243must be set, the default values are specified below.
244.Pp
245All
246.Ar key Ns Cm = Ns Ar value
247pairs are interpreted as jail parameters as described in
248.Xr jail 8 .
249The 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
257generated by
258.Xr libbe 3 .
259.El
260.Pp
261All default parameters may be overwritten.
262.It Xo
263.Cm list
264.Op Fl aDHs
265.Oo Bro Fl c Ar property | Fl C Ar property Brc Oc
266.Xc
267.Pp
268Display all boot environments.
269The
270.Em Active
271field indicates whether the boot environment is active now
272.Pq Em \&N ;
273active on reboot
274.Pq Em \&R ;
275is used on next boot once
276.Pq Em \&T ;
277or combination of
278.Pq Em \&NRT .
279.Pp
280.Bl -tag -width indent
281.It Fl a
282Display all datasets.
283.It Fl D
284Display the full space usage for each boot environment, assuming all
285other boot environments were destroyed.
286.It Fl H
287Used for scripting.
288Do not print headers and separate fields by a single tab instead of
289arbitrary white space.
290.It Fl s
291Display all snapshots as well.
292.It Fl c Ar property
293Sort boot environments by given property name.
294The following properties are supported:
295.Pp
296.Bl -tag -width 4n -offset indent -compact
297.It name (default output)
298.It creation
299.It origin
300.It used
301.It usedds
302.It usedsnap
303.It usedrefreserv
304.El
305.It Fl C Ar property
306Same as the
307.Fl c
308option, but displays in descending order.
309.El
310.Pp
311The
312.Fl D
313option is ignored when either the
314.Fl s
315or
316.Fl a
317option is used.
318.It Cm mount Ar beName Op Ar mountpoint
319Temporarily mount the boot environment.
320Mount at the specified
321.Ar mountpoint
322if provided.
323.It Cm rename Ar origBeName newBeName
324Rename the given
325.Ar origBeName
326to the given
327.Ar newBeName .
328The 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
331Destroy the jail created from the given boot environment.
332.It Xo
333.Cm umount
334.Op Fl f
335.Ar beName
336.Xc
337.It Xo
338.Cm unmount
339.Op Fl f
340.Ar beName
341.Xc
342Unmount the given boot environment, if it is mounted.
343Specifying
344.Fl f
345will force the unmount if busy.
346.El
347.Pp
348.Nm
349prints usage information if
350.Fl h
351or
352.Fl \&?
353is specified.
354.Ss Boot Environment Structures
355The traditional
356.Fx
357boot environment layout, as created by the Auto ZFS option to
358.Xr bsdinstall 8 ,
359is a
360.Dq shallow
361boot environment structure, where boot environment datasets do not have any
362directly subordinate datasets.
363Instead, they're organized off in
364.Pa zroot/ROOT ,
365and they rely on datasets elsewhere in the pool having
366.Dv canmount
367set to
368.Dv off .
369For instance, a simplified pool may be laid out as such:
370.Bd -literal -offset indent
371% zfs list -o name,canmount,mountpoint
372NAME			CANMOUNT	MOUNTPOINT
373zroot
374zroot/ROOT		noauto		none
375zroot/ROOT/default	noauto		none
376zroot/usr		off		/usr
377zroot/usr/home		on		/usr/home
378zroot/var		on		/var
379.Ed
380.Pp
381In that example,
382.Pa zroot/usr
383has
384.Dv canmount
385set to
386.Dv off ,
387thus files in
388.Pa /usr
389typically fall into the boot environment because this dataset is not mounted.
390.Pa zroot/usr/home
391is mounted, thus files in
392.Pa /usr/home
393are not in the boot environment.
394.Pp
395The other style of boot environments in use, frequently called
396.Dq deep boot environments ,
397organizes some or all of the boot environment as subordinate to the boot
398environment dataset.
399For example:
400.Bd -literal -offset indent
401% zfs list -o name,canmount,mountpoint
402NAME				CANMOUNT	MOUNTPOINT
403zroot
404zroot/ROOT			noauto		none
405zroot/ROOT/default		noauto		none
406zroot/ROOT/default/usr		noauto		/usr
407zroot/ROOT/default/usr/local	noauto		/usr/local
408zroot/var			on		/var
409.Ed
410.Pp
411Note that the subordinate datasets now have
412.Dv canmount
413set to
414.Dv noauto .
415These are more obviously a part of the boot environment, as indicated by their
416positioning in the layout.
417These subordinate datasets will be mounted by the
418.Dv zfsbe
419.Xr rc 8
420script at boot time.
421In this example,
422.Pa /var
423is excluded from the boot environment.
424.Pp
425.Nm
426commands that have their own
427.Fl r
428operate on this second,
429.Dq deep
430style of boot environment, when the
431.Fl r
432flag is set.
433A future version of
434.Nm
435may default to handling both styles and deprecate the various
436.Fl r
437flags.
438\" .Sh EXAMPLES
439\" .Bl -bullet
440\" .It
441\" To fill in with jail upgrade example when behavior is firm.
442\" .El
443.Sh SEE ALSO
444.Xr libbe 3 ,
445.Xr beinstall.sh 8 ,
446.Xr jail 8 ,
447.Xr zfs 8 ,
448.Xr zpool 8
449.Sh HISTORY
450.Nm
451is based on
452.Xr beadm 1
453and was implemented as a project for the 2017 Summer of Code, along with
454.Xr libbe 3 .
455.Sh AUTHORS
456.Nm
457was written by
458.An Kyle Kneitinger (kneitinger) Aq Mt kyle@kneit.in .
459.Pp
460.Xr beadm 1
461was written and is maintained by
462.An Slawomir Wojciech Wojtczak (vermaden) Aq Mt vermaden@interia.pl .
463.Pp
464.An Bryan Drewery (bdrewery) Aq Mt bryan@shatow.net
465wrote the original
466.Xr beadm 1
467manual page that this one is derived from.
468