xref: /freebsd/sbin/bectl/bectl.8 (revision f993ed2fbd3c307200ed9a6351e649f0904b39c5)
1.\"
2.\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD
3.\"
4.\" Copyright (c) 2017 Kyle J. Kneitinger <kyle@kneit.in>
5.\" All rights reserved.
6.\"
7.\" Redistribution and use in source and binary forms, with or without
8.\" modification, are permitted provided that the following conditions
9.\" are met:
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.
15.\"
16.\"
17.\"     @(#)be.1
18.\"
19.\" $FreeBSD$
20.\"
21.Dd September 4, 2019
22.Dt BECTL 8
23.Os
24.Sh NAME
25.Nm bectl
26.Nd Utility to manage boot environments on ZFS
27.Sh SYNOPSIS
28.Nm
29.Cm activate
30.Op Fl t
31.Ar beName
32.Nm
33.Cm create
34.Op Fl r
35.Op Fl e Brq Ar nonActiveBe | Ar beName Ns Cm @ Ns Ar snapshot
36.Ar newBeName
37.Nm
38.Cm create
39.Op Fl r
40.Ar beName@snapshot
41.Nm
42.Cm destroy
43.Op Fl \&Fo
44.Ar beName Ns Op Cm @ Ns Ar snapshot
45.Nm
46.Cm export
47.Ar sourceBe
48.Nm
49.Cm import
50.Ar targetBe
51.Nm
52.Cm jail
53.Op Fl bU
54.Oo Bro Fl o Ar key Ns Cm = Ns Ar value | Fl u Ar key Brc Oc Ns ...
55.Ar beName
56.Op Ar utility Op Ar argument ...
57.Nm
58.Cm list
59.Op Fl aDHs
60.Op Fl c Ar property
61.Op Fl C Ar property
62.Oo Bro Fl c Ar property | Fl C Ar property Brc Oc
63.Nm
64.Cm mount
65.Ar beName
66.Op Ar mountpoint
67.Nm
68.Cm rename
69.Ar origBeName
70.Ar newBeName
71.Nm
72.Brq Cm ujail | unjail
73.Brq Ar jailId | jailName
74.Ar 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
98.Ar beName
99.Xc
100Activate the given
101.Ar beName
102as the default boot filesystem.
103If the
104.Op Fl t
105flag is given, this takes effect only for the next boot.
106.It Xo
107.Cm create
108.Op Fl r
109.Op Fl e Brq Ar nonActiveBe | Ar beName Ns Cm @ Ns Ar snapshot
110.Ar newBeName
111.Xc
112Create a new boot environment named
113.Ar newBeName .
114.Pp
115If the
116.Fl r
117flag is given, a recursive boot environment will be made.
118.Pp
119If the
120.Fl e
121flag is specified, the new environment will be cloned from the given
122.Ar nonActiveBe
123or
124.Ar beName Ns Cm @ Ns Ar snapshot .
125Otherwise, the new environment will be created from the currently booted environment.
126.Pp
127If
128.Nm
129is creating from another boot environment, a snapshot of that boot environment will be created to clone from.
130.It Xo
131.Cm create
132.Op Fl r
133.Ar beName@snapshot
134.Xc
135Create a snapshot of the boot environment named
136.Ar beName .
137.Pp
138If the
139.Fl r
140flag is given, a recursive snapshot of the boot environment will be created.
141A snapshot is created for each descendant dataset of the boot environment.
142.Pp
143No new boot environment is created with this command.
144.It Xo
145.Cm destroy
146.Op Fl \&Fo
147.Ar beName Ns Op Cm @ Ns Ar snapshot
148.Xc
149Destroy the given
150.Ar beName
151boot environment or
152.Ar beName Ns Cm @ Ns Ar snapshot
153snapshot without confirmation, unlike in
154.Xr beadm 1 .
155Specifying
156.Fl F
157will automatically unmount without confirmation.
158.Pp
159By default,
160.Nm
161will warn that it is not destroying the origin of
162.Ar beName .
163The
164.Fl o
165flag may be specified to destroy the origin as well.
166.It Cm export Ar sourceBe
167Export
168.Ar sourceBe
169to
170.Xr stdout 4 .
171.Xr stdout 4
172must be piped or redirected to a file.
173.It Cm import Ar targetBe
174Import
175.Ar targetBe
176from
177.Xr stdin 4 .
178.It Xo
179.Cm jail
180.Op Fl bU
181.Oo Bro Fl o Ar key Ns Cm = Ns Ar value | Fl u Ar key Brc Oc Ns ...
182.Ar beName
183.Op Ar utility Op Ar argument ...
184.Xc
185Create a jail of the given boot environment.
186Multiple
187.Fl o
188and
189.Fl u
190arguments may be specified.
191.Fl o
192will set a jail parameter, and
193.Fl u
194will unset a jail parameter.
195.Pp
196By default, jails are created in interactive mode and
197.Pa /bin/sh
198is
199executed within the jail.
200If
201.Ar utility
202is specified, it will be executed instead of
203.Pa /bin/sh .
204The jail will be destroyed and the boot environment unmounted when the command
205finishes executing, unless the
206.Fl U
207argument is specified.
208.Pp
209The
210.Fl b
211argument enables batch mode, thereby disabling interactive mode.
212The
213.Fl U
214argument will be ignored in batch mode.
215.Pp
216The
217.Va name ,
218.Va host.hostname ,
219and
220.Va path
221must be set, the default values are specified below.
222.Pp
223All
224.Ar key Ns Cm = Ns Ar value
225pairs are interpreted as jail parameters as described in
226.Xr jail 8 .
227The following default parameters are provided:
228.Bl -column "allow.mount.devfs" ""
229.It Va allow.mount Ta Cm true
230.It Va allow.mount.devfs Ta Cm true
231.It Va enforce_statfs Ta Cm 1
232.It Va name Ta Set to jail ID.
233.It Va host.hostname Ta Va bootenv
234.It Va path Ta Set to a path in Pa /tmp
235generated by
236.Xr libbe 3 .
237.El
238.Pp
239All default parameters may be overwritten.
240.It Xo
241.Cm list
242.Op Fl DHas
243.Oo Bro Fl c Ar property | Fl C Ar property Brc Oc
244.Xc
245.Pp
246Display all boot environments.
247The
248.Em Active
249field indicates whether the boot environment is active now
250.Pq Em \&N ;
251active on reboot
252.Pq Em \&R ;
253or both
254.Pq Em \&NR .
255.Pp
256.Bl -tag -width indent
257.It Fl a
258Display all datasets.
259.It Fl D
260Display the full space usage for each boot environment, assuming all
261other boot environments were destroyed.
262.It Fl H
263Used for scripting.
264Do not print headers and separate fields by a single tab instead of
265arbitrary white space.
266.It Fl s
267Display all snapshots as well.
268.It Fl c Ar property
269Sort boot environments by given property name.
270The following properties are supported:
271.Pp
272.Bl -tag -width 4n -offset indent -compact
273.It name (default output)
274.It creation
275.It origin
276.It used
277.It usedds
278.It usedsnap
279.It usedrefreserv
280.El
281.It Fl C Ar property
282Same as the
283.Fl c
284option, but displays in descending order.
285.El
286.Pp
287The
288.Fl D
289option is ignored when either the
290.Fl s
291or
292.Fl a
293option is used.
294.It Cm mount Ar beName Op Ar mountpoint
295Temporarily mount the boot environment.
296Mount at the specified
297.Ar mountpoint
298if provided.
299.It Cm rename Ar origBeName newBeName
300Rename the given
301.Ar origBeName
302to the given
303.Ar newBeName .
304The boot environment will not be unmounted in order for this rename to occur.
305.It Cm ujail Bro Ar jailId | jailName Brc Ar beName
306.It Cm unjail Bro Ar jailId | jailName Brc Ar beName
307Destroy the jail created from the given boot environment.
308.It Xo
309.Cm umount
310.Op Fl f
311.Ar beName
312.Xc
313.It Xo
314.Cm unmount
315.Op Fl f
316.Ar beName
317.Xc
318Unmount the given boot environment, if it is mounted.
319Specifying
320.Fl f
321will force the unmount if busy.
322.El
323.Pp
324.Nm
325prints usage information if
326.Fl h
327or
328.Fl \&?
329is specified.
330.Sh EXAMPLES
331.Bl -bullet
332.It
333To fill in with jail upgrade example when behavior is firm.
334.El
335.Sh SEE ALSO
336.Xr beinstall.sh 1 ,
337.Xr libbe 3 ,
338.Xr jail 8 ,
339.Xr zfs 8 ,
340.Xr zpool 8
341.Sh HISTORY
342.Nm
343is based on
344.Xr beadm 1
345and was implemented as a project for the 2017 Summer of Code, along with
346.Xr libbe 3 .
347.Sh AUTHORS
348.Nm
349was written by
350.An Kyle Kneitinger (kneitinger) Aq Mt kyle@kneit.in .
351.Pp
352.Xr beadm 1
353was written and is maintained by
354.An Slawomir Wojciech Wojtczak (vermaden) Aq Mt vermaden@interia.pl .
355.Pp
356.An Bryan Drewery (bdrewery) Aq Mt bryan@shatow.net
357wrote the original
358.Xr beadm 1
359manual page that this one is derived from.
360